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