Commit | Line | Data |
1f1aba66 |
1 | <div class="pod"> |
2 | <!-- INDEX START --> |
3 | <h3 id="TOP">Index</h3> |
4 | |
5 | <ul><li><a href="#NAME">NAME</a></li> |
6 | <li><a href="#CATEGORY">CATEGORY</a></li> |
7 | <li><a href="#SYNOPSIS">SYNOPSIS</a></li> |
8 | <li><a href="#DESCRIPTION">DESCRIPTION</a></li> |
9 | <li><a href="#WARNING_VOLATILE_CODE_AHEAD">WARNING! VOLATILE CODE AHEAD</a></li> |
10 | <li><a href="#ATTRIBUTES_AND_METHODS">ATTRIBUTES AND METHODS</a> |
11 | <ul><li><a href="#new">new</a></li> |
12 | <li><a href="#new_options">new( %options )</a></li> |
13 | <li><a href="#step_x">step_x()</a></li> |
14 | <li><a href="#step_x_integer">step_x( $integer )</a></li> |
15 | <li><a href="#step_y">step_y()</a></li> |
16 | <li><a href="#step_y_integer">step_y( $integer )</a></li> |
17 | <li><a href="#max_loops">max_loops()</a></li> |
18 | <li><a href="#max_loops_integer">max_loops( $integer )</a></li> |
19 | <li><a href="#ticks_per_frame">ticks_per_frame()</a></li> |
20 | <li><a href="#ticks_per_frame_integer">ticks_per_frame( $integer )</a></li> |
21 | <li><a href="#type">type()</a></li> |
22 | <li><a href="#type_string">type( $string )</a></li> |
23 | <li><a href="#next">next()</a></li> |
24 | <li><a href="#previous">previous()</a></li> |
25 | <li><a href="#reset">reset()</a></li> |
26 | <li><a href="#current_frame">current_frame()</a></li> |
27 | <li><a href="#current_loop">current_loop()</a></li> |
28 | </ul> |
29 | </li> |
30 | <li><a href="#start">start()</a></li> |
31 | <li><a href="#stop">stop()</a></li> |
32 | <li><a href="#AUTHORS">AUTHORS</a></li> |
33 | <li><a href="#SEE_ALSO">SEE ALSO</a> |
34 | </li> |
35 | </ul><hr /> |
36 | <!-- INDEX END --> |
37 | |
38 | <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p> |
39 | <div id="NAME_CONTENT"> |
40 | <p>SDLx::Sprite::Animated - create animated SDL sprites easily!</p> |
41 | |
42 | </div> |
43 | <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p> |
44 | <div id="CATEGORY_CONTENT"> |
45 | <p>Extension</p> |
46 | |
47 | </div> |
48 | <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
49 | <div id="SYNOPSIS_CONTENT"> |
50 | <pre> use SDLx::Sprite::Animated; |
51 | |
52 | # simplest possible form, where 'hero.png' is an image containing |
53 | # fixed-length sprites in sequence. It doesn't matter if they are |
54 | # placed vertically or horizontally, as long as the the widest |
55 | # side is a multiple of the (narrowest) other. The widget will |
56 | # automatically divide it in the proper frames, provided there is |
57 | # no slack space between each frame. |
58 | |
59 | my $animation = SDLx::Sprite::Animated->new->load('hero.png'); |
60 | |
61 | # that's it! Defaults are sane enough to DWIM in simple cases, |
62 | # so you just have to call draw() on the right place. If you |
63 | # need to setup your animation or have more control over it, |
64 | # feel free to use the attributes and methods below. |
65 | |
66 | # these are the most useful methods to use in your game loop |
67 | # (or wherever you want to manipulate the animation): |
68 | $animation->next; |
69 | $animation->previous; |
70 | $animation->reset; |
71 | |
72 | $animation->current_frame; # current frame number |
73 | $animation->current_loop; # current loop number |
74 | |
75 | # you can control positioning just like a regular SDLx::Sprite: |
76 | $animation->rect |
77 | $animation->x; |
78 | $animation->y; |
79 | |
80 | # just like a regular Sprite, we fetch our source rect from ->clip, |
81 | # updating it on each call to ->next (or ->previous, or ->reset). |
82 | # If source rects for your animation are further appart (or less) |
83 | # than the rect's width and height, you can adjust the animation |
84 | # x/y offsets: |
85 | $animation->step_x(15); |
86 | $animation->step_y(30); |
87 | |
88 | $animation->draw($screen); # remember to do this! :) |
89 | |
90 | # we can also call ->next() automatically after each draw(): |
91 | $animation->start; |
92 | $animation->stop; |
93 | |
94 | # default is to go to the next frame at each draw(). If this is |
95 | # too fast for you, change the attribute below: |
96 | $animation->ticks_per_frame(10); |
97 | |
98 | # select type of animation loop when it reaches the last frame: |
99 | $animation->type('circular'); # restarts loop at the beginning |
100 | $animation->type('reverse'); # goes backwards |
101 | |
102 | $animation->max_loops(3); 0 or undef for infinite looping |
103 | |
104 | |
105 | |
106 | |
107 | # as usual, you can setup most of the above during object spawning |
108 | my $animation = SDLx::Sprite::Animated->new( |
109 | image => 'hero.png', |
110 | rect => SDL::Rect->new(...), |
111 | step_x => 20, |
112 | step_y => 0, |
113 | ... |
114 | ); |
115 | |
116 | |
117 | |
118 | |
119 | </pre> |
120 | |
121 | </div> |
122 | <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p> |
123 | <div id="DESCRIPTION_CONTENT"> |
124 | <p>An animation is a series of frames that are played in order. Frames are |
125 | loaded from an image, usually referred to as a Sprite Sheet or Sprite Strip.</p> |
126 | <p>This module let's you interact with such strips and create sprite animations |
127 | just as easily as you would manipulate a regular SDLx::Sprite object.</p> |
128 | |
129 | </div> |
130 | <h1 id="WARNING_VOLATILE_CODE_AHEAD">WARNING! VOLATILE CODE AHEAD</h1><p><a href="#TOP" class="toplink">Top</a></p> |
131 | <div id="WARNING_VOLATILE_CODE_AHEAD_CONTENT"> |
132 | <p>This is a new module and the API is subject to change without notice. |
133 | If you care, please join the discussion on the #sdl IRC channel in |
134 | <i>irc.perl.org</i>. All thoughts on further improving the API are welcome.</p> |
135 | <p>You have been warned :)</p> |
136 | |
137 | </div> |
138 | <h1 id="ATTRIBUTES_AND_METHODS">ATTRIBUTES AND METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
139 | <div id="ATTRIBUTES_AND_METHODS_CONTENT"> |
140 | <p>SDLx::Sprite::Animated is a <strong>subclass</strong> of <a href="http://search.cpan.org/perldoc?SDLx::Sprite">SDLx::Sprite</a>, inheriting |
141 | all its attributes and methods. Please refer to that module's documentation |
142 | for information on those.</p> |
143 | <p>The one difference in behavior is that, while a standard SDLx::Sprite uses |
144 | <code>->clip()</code> to select the part of the surface to display, |
145 | SDLx::Sprite::Animated treats <code>->clip()</code> as the <strong>initial</strong> rect, from |
146 | which to start the animation.</p> |
147 | <p>The following attributes and methods are available:</p> |
148 | |
149 | </div> |
150 | <h2 id="new">new</h2> |
151 | <div id="new_CONTENT"> |
152 | |
153 | </div> |
154 | <h2 id="new_options">new( %options )</h2> |
155 | <div id="new_options_CONTENT"> |
156 | <p>Creates a new SDLx::Sprite::Animated object. No option is mandatory. It |
157 | accepts all the options from a regular SDLx::Sprite object plus these:</p> |
158 | <dl> |
159 | <dt>* step_x => $integer</dt> |
160 | <dd> |
161 | <p>Uses $integer as the number of pixels to move on the x-axis (left-to-right, |
162 | 0 being no dislocation whatsoever, when the strip goes from top to bottom) |
163 | to reach the next frame.</p> |
164 | </dd> |
165 | <dt>* step_y => $integer</dt> |
166 | <dd> |
167 | <p>Uses $integer as the number of pixels to move on the y-axis (top-to-bottom, |
168 | 0 being no dislocation whatsoever, when the strip goes from left to right) |
169 | to reach the next frame.</p> |
170 | </dd> |
171 | <dt>* max_loops => $integer</dt> |
172 | <dd> |
173 | <p>Uses $integer as the number of times to loop the animation (when it reaches |
174 | the end of the strip).</p> |
175 | </dd> |
176 | <dt>* ticks_per_frame => $integer</dt> |
177 | <dd> |
178 | <p>Uses $integer to set how many calls to draw() must be issued before we go to |
179 | the next frame during autoplay (i.e. between calls to start() and stop()).</p> |
180 | </dd> |
181 | <dt>* type => $string</dt> |
182 | <dd> |
183 | <p>Uses $string to set the type of animation loop when it reaches the last |
184 | frame in the strip. See the type() method below for information on |
185 | available looping types.</p> |
186 | </dd> |
187 | </dl> |
188 | |
189 | </div> |
190 | <h2 id="step_x">step_x()</h2> |
191 | <div id="step_x_CONTENT"> |
192 | |
193 | </div> |
194 | <h2 id="step_x_integer">step_x( $integer )</h2> |
195 | <div id="step_x_integer_CONTENT"> |
196 | <p>Uses $integer as the number of pixels to move on the x-axis (left-to-right, |
197 | 0 being no dislocation whatsoever, when the strip goes from top to bottom) |
198 | to reach the next frame.</p> |
199 | <p>Defaults to the same width as the clip() rect.</p> |
200 | |
201 | </div> |
202 | <h2 id="step_y">step_y()</h2> |
203 | <div id="step_y_CONTENT"> |
204 | |
205 | </div> |
206 | <h2 id="step_y_integer">step_y( $integer )</h2> |
207 | <div id="step_y_integer_CONTENT"> |
208 | <p>Uses $integer as the number of pixels to move on the y-axis (top-to-bottom, |
209 | 0 being no dislocation whatsoever, when the strip goes from left to right) |
210 | to reach the next frame.</p> |
211 | <p>Defaults to the same height as the clip() rect.</p> |
212 | |
213 | </div> |
214 | <h2 id="max_loops">max_loops()</h2> |
215 | <div id="max_loops_CONTENT"> |
216 | |
217 | </div> |
218 | <h2 id="max_loops_integer">max_loops( $integer )</h2> |
219 | <div id="max_loops_integer_CONTENT"> |
220 | <p>Uses $integer as the number of times to loop the animation (when it reaches |
221 | the end of the strip). After that <strong>all calls to previous() or next() will be no-ops</strong>.</p> |
222 | <p>Set it to <code>0</code> or <code>undef</code> to allow infinite loops. Default is 0 (infinite).</p> |
223 | |
224 | </div> |
225 | <h2 id="ticks_per_frame">ticks_per_frame()</h2> |
226 | <div id="ticks_per_frame_CONTENT"> |
227 | |
228 | </div> |
229 | <h2 id="ticks_per_frame_integer">ticks_per_frame( $integer )</h2> |
230 | <div id="ticks_per_frame_integer_CONTENT"> |
231 | <p>Uses $integer to set how many calls to draw() must be issued before we go to |
232 | the next frame during autoplay (i.e. between calls to start() and stop()).</p> |
233 | <p>Default is just 1 tick per frame, so you might want to change this if it's too fast.</p> |
234 | |
235 | </div> |
236 | <h2 id="type">type()</h2> |
237 | <div id="type_CONTENT"> |
238 | |
239 | </div> |
240 | <h2 id="type_string">type( $string )</h2> |
241 | <div id="type_string_CONTENT"> |
242 | <p>Uses $string to set the type of animation loop when it reaches the last |
243 | frame in the strip. Available looping types are:</p> |
244 | <dl> |
245 | <dt>* 'circular'</dt> |
246 | <dd> |
247 | <p>Restarts loop at the beginning of the strip. If you have 4 frames, the flow |
248 | will be 1-2-3-4-1-2-3-4-1-2-3-4-1-2-... up until the number of loops you |
249 | set in the max_loops() attribute.</p> |
250 | </dd> |
251 | <dt>* 'reverse'</dt> |
252 | <dd> |
253 | <p>Loops back and forth on the strip. If you have 4 frames, the flow will be |
254 | 1-2-3-4-3-2-1-2-3-4-3-2-... up until the number of loops you set in the |
255 | max_loops() attribute.</p> |
256 | </dd> |
257 | </dl> |
258 | <p>Case is irrelevant for type(), so for example 'Circular', 'CIRCULAR' and |
259 | 'CiRcUlAr' are all accepted as 'circular'. The return value is guaranteed |
260 | to be lowercase.</p> |
261 | <p>Default value is 'circular'.</p> |
262 | |
263 | </div> |
264 | <h2 id="next">next()</h2> |
265 | <div id="next_CONTENT"> |
266 | <p>Goes to the next frame in the strip. Calling this method will also reset |
267 | the tick counter used by ticks_per_frame().</p> |
268 | <p>If max_loops() has reached its limit, this will be a no-op.</p> |
269 | <p>Returns the object, allowing method chaining.</p> |
270 | |
271 | </div> |
272 | <h2 id="previous">previous()</h2> |
273 | <div id="previous_CONTENT"> |
274 | <p>Goes to the previous frame in the strip. Calling this method will also reset |
275 | the tick counter used by ticks_per_frame().</p> |
276 | <p>If max_loops() has reached its limit, this will be a no-op.</p> |
277 | <p>Returns the object, allowing method chaining.</p> |
278 | |
279 | </div> |
280 | <h2 id="reset">reset()</h2> |
281 | <div id="reset_CONTENT"> |
282 | <p>Goes to the first frame in the strip, meaning whatever clip is set to.</p> |
283 | <p>If max_loops() has reached its limit, this will be a no-op.</p> |
284 | <p>Returns the object, allowing method chaining.</p> |
285 | |
286 | </div> |
287 | <h2 id="current_frame">current_frame()</h2> |
288 | <div id="current_frame_CONTENT"> |
289 | <p>Returns the current frame number. Note that this is 1-based (first frame |
290 | is 1, second is 2, etc).</p> |
291 | |
292 | </div> |
293 | <h2 id="current_loop">current_loop()</h2> |
294 | <div id="current_loop_CONTENT"> |
295 | <p>Returns the loop counter, i.e. which run number is it at. This is also |
296 | 1-based (first time is 1, second time is 2, etc). Note that we only |
297 | keep track of the counter if max_loops() is set to a finite number. Otherwise, |
298 | this will be a no-op.</p> |
299 | |
300 | </div> |
301 | <h1 id="start">start()</h1><p><a href="#TOP" class="toplink">Top</a></p> |
302 | <div id="start_CONTENT"> |
303 | <p>After you call this method, the object will issue a call to <code>->next()</code> |
304 | automatically for you every time <code>->draw()</code> is called |
305 | <code>ticks_per_frame()</code> times.</p> |
306 | <p>If you want to stop autoplay, see <code>stop()</code> below.</p> |
307 | <p>Default is off (no autoplay).</p> |
308 | |
309 | </div> |
310 | <h1 id="stop">stop()</h1><p><a href="#TOP" class="toplink">Top</a></p> |
311 | <div id="stop_CONTENT"> |
312 | <p>Stops autoplay. After you call this, the object will need you to call |
313 | <code>->previous()</code> and <code>->next()</code> explicitly to change frames.</p> |
314 | <p>To resume autoplay from wherever you are, use <code>start()</code>.</p> |
315 | <p>If you want to restart autoplay from the initial frame, just do:</p> |
316 | <pre> $sprite->reset->start; |
317 | |
318 | |
319 | |
320 | |
321 | </pre> |
322 | |
323 | </div> |
324 | <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
325 | <div id="AUTHORS_CONTENT"> |
326 | <p>Jeffrey T. Palmer <code><jeffrey.t.palmer at gmail.com></code></p> |
327 | <p>Dustin Mays, <code><dork.fish.wat@gmail.com></code></p> |
328 | <p>Breno G. de Oliveira, <code><garu at cpan.org></code></p> |
329 | <p>Kartik thakore <code><kthakore at cpan.org></code></p> |
330 | |
331 | </div> |
332 | <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p> |
333 | <div id="SEE_ALSO_CONTENT"> |
334 | <p><a href="SDL-Surface.html">SDL::Surface</a>, <a href="SDL.html">SDL</a></p> |
335 | |
336 | </div> |
337 | </div> |