SDLx::Sprite::Animated(3pm)

1SDLx::Sprite::Animated(U3s)er Contributed Perl DocumentatSiDoLnx::Sprite::Animated(3)
2
3
4

NAME

6       SDLx::Sprite::Animated - create animated SDL sprites easily!
7

SYNOPSIS

12         use SDLx::Sprite::Animated;
13
14         # simplest possible form, where 'hero.png' is an image containing
15         # fixed-length sprites in sequence. It doesn't matter if they are
16         # placed vertically or horizontally, as long as the the widest
17         # side is a multiple of the (narrowest) other. The widget will
18         # automatically divide it in the proper frames, provided there is
19         # no slack space between each frame.
20
21         my $animation = SDLx::Sprite::Animated->new->load('hero.png');
22
23         # that's it! Defaults are sane enough to DWIM in simple cases,
24         # so you just have to call draw() on the right place. If you
25         # need to setup your animation or have more control over it,
26         # feel free to use the attributes and methods below.
27
28         # these are the most useful methods to use in your game loop
29         # (or wherever you want to manipulate the animation):
30         $animation->next;
31         $animation->previous;
32         $animation->reset;
33
34         $animation->current_frame;   # current frame number
35         $animation->current_loop;    # current loop number
36
37         # you can control positioning just like a regular SDLx::Sprite:
38         $animation->rect
39         $animation->x;
40         $animation->y;
41
42         # just like a regular Sprite, we fetch our source rect from ->clip,
43         # updating it on each call to ->next (or ->previous, or ->reset).
44         # If source rects for your animation are further apart (or less)
45         # than the rect's width and height, you can adjust the animation
46         # x/y offsets:
47         $animation->step_x(15);
48         $animation->step_y(30);
49
50         $animation->draw($screen); # remember to do this! :)
51
52         # we can also call ->next() automatically after each draw():
53         $animation->start;
54         $animation->stop;
55
56         # default is to go to the next frame at each draw(). If this is
57         # too fast for you, change the attribute below:
58         $animation->ticks_per_frame(10);
59
60         # select type of animation loop when it reaches the last frame:
61         $animation->type('circular'); # restarts loop at the beginning
62         $animation->type('reverse');  # goes backwards
63
64         $animation->max_loops(3); 0 or undef for infinite looping
65
66
67         # as usual, you can setup most of the above during object spawning
68         my $animation = SDLx::Sprite::Animated->new(
69                              image  => 'hero.png',
70                              rect   => SDL::Rect->new(...),
71                              step_x => 20,
72                              step_y => 0,
73                              ...
74                         );
75

DESCRIPTION

77       An animation is a series of frames that are played in order. Frames are
78       loaded from an image, usually referred to as a Sprite Sheet or Sprite
79       Strip.
80
81       This module let's you interact with such strips and create sprite
82       animations just as easily as you would manipulate a regular
83       SDLx::Sprite object.
84

WARNING! VOLATILE CODE AHEAD

86       This is a new module and the API is subject to change without notice.
87       If you care, please join the discussion on the #sdl IRC channel in
88       irc.perl.org. All thoughts on further improving the API are welcome.
89
90       You have been warned :)
91

ATTRIBUTES AND METHODS

93       SDLx::Sprite::Animated is a subclass of SDLx::Sprite, inheriting all
94       its attributes and methods. Please refer to that module's documentation
95       for information on those.
96
97       The one difference in behavior is that, while a standard SDLx::Sprite
98       uses "->clip()" to select the part of the surface to display,
99       SDLx::Sprite::Animated treats "->clip()" as the initial rect, from
100       which to start the animation.
101
102       The following attributes and methods are available:
103
104   new
105   new( %options )
106       Creates a new SDLx::Sprite::Animated object. No option is mandatory. It
107       accepts all the options from a regular SDLx::Sprite object plus these:
108
109       •   step_x => $integer
110
111           Uses $integer as the number of pixels to move on the x-axis (left-
112           to-right, 0 being no dislocation whatsoever, when the strip goes
113           from top to bottom) to reach the next frame.
114
115       •   step_y => $integer
116
117           Uses $integer as the number of pixels to move on the y-axis (top-
118           to-bottom, 0 being no dislocation whatsoever, when the strip goes
119           from left to right) to reach the next frame.
120
121       •   max_loops => $integer
122
123           Uses $integer as the number of times to loop the animation (when it
124           reaches the end of the strip).
125
126       •   ticks_per_frame => $integer
127
128           Uses $integer to set how many calls to draw() must be issued before
129           we go to the next frame during autoplay (i.e. between calls to
130           start() and stop()).
131
132       •   type => $string
133
134           Uses $string to set the type of animation loop when it reaches the
135           last frame in the strip. See the type() method below for
136           information on available looping types.
137
138       •   sequences => { $string => [ [ $x1, $y1 ], [ $x2, $y2 ], ... ], ...
139           }
140
141           Uses the supplied hashref to define named sequences of frames.
142
143       •   sequence => $string
144
145           Uses $string to set the current sequence.
146
147   step_x()
148   step_x( $integer )
149       Uses $integer as the number of pixels to move on the x-axis (left-to-
150       right, 0 being no dislocation whatsoever, when the strip goes from top
151       to bottom) to reach the next frame.
152
153       Defaults to the same width as the clip() rect.
154
155   step_y()
156   step_y( $integer )
157       Uses $integer as the number of pixels to move on the y-axis (top-to-
158       bottom, 0 being no dislocation whatsoever, when the strip goes from
159       left to right) to reach the next frame.
160
161       Defaults to the same height as the clip() rect.
162
163   max_loops()
164   max_loops( $integer )
165       Uses $integer as the number of times to loop the animation (when it
166       reaches the end of the strip). After that all calls to previous() or
167       next() will be no-ops.
168
169       Set it to 0 or "undef" to allow infinite loops. Default is 0
170       (infinite).
171
172   ticks_per_frame()
173   ticks_per_frame( $integer )
174       Uses $integer to set how many calls to draw() must be issued before we
175       go to the next frame during autoplay (i.e. between calls to start() and
176       stop()).
177
178       Default is just 1 tick per frame, so you might want to change this if
179       it's too fast.
180
181   type()
182   type( $string )
183       Uses $string to set the type of animation loop when it reaches the last
184       frame in the strip. Available looping types are:
185
186       •   'circular'
187
188           Restarts loop at the beginning of the strip. If you have 4 frames,
189           the flow will be 1-2-3-4-1-2-3-4-1-2-3-4-1-2-... up until the
190           number of loops you set in the max_loops() attribute.
191
192       •   'reverse'
193
194           Loops back and forth on the strip. If you have 4 frames, the flow
195           will be 1-2-3-4-3-2-1-2-3-4-3-2-... up until the number of loops
196           you set in the max_loops() attribute.
197
198       Case is irrelevant for type(), so for example 'Circular', 'CIRCULAR'
199       and 'CiRcUlAr' are all accepted as 'circular'. The return value is
200       guaranteed to be lowercase.
201
202       Default value is 'circular'.
203
204   set_sequences( $string => [ [ $x1, $y1 ], [ $x2, $y2 ], ... ], ... )
205       Uses the supplied hashref to define named sequences of frames. Replaces
206       any previously defined sequences.
207
208   sequence( $string )
209       Uses $string to set the current sequence. Goes to the first frame in
210       the sequence and resets the loop counter.
211
212   next()
213       Goes to the next frame in the strip. Calling this method will also
214       reset the tick counter used by ticks_per_frame().
215
216       If max_loops() has reached its limit, this will be a no-op.
217
218       Returns the object, allowing method chaining.
219
220   previous()
221       Goes to the previous frame in the strip. Calling this method will also
222       reset the tick counter used by ticks_per_frame().
223
224       If max_loops() has reached its limit, this will be a no-op.
225
226       Returns the object, allowing method chaining.
227
228   reset()
229       Goes to the first frame in the strip, meaning whatever clip is set to.
230
231       If max_loops() has reached its limit, this will be a no-op.
232
233       Returns the object, allowing method chaining.
234
235   current_frame()
236       Returns the current frame number. Note that this is 1-based (first
237       frame is 1, second is 2, etc).
238
239   current_loop()
240       Returns the loop counter, i.e. which run number is it at. This is also
241       1-based (first time is 1, second time is 2, etc). Note that we only
242       keep track of the counter if max_loops() is set to a finite number.
243       Otherwise, this will be a no-op.
244

start()

246       After you call this method, the object will issue a call to "->next()"
247       automatically for you every time "->draw()" is called ticks_per_frame()
248       times.
249
250       If you want to stop autoplay, see stop() below.
251
252       Default is off (no autoplay).
253

stop()

255       Stops autoplay. After you call this, the object will need you to call
256       "->previous()" and "->next()" explicitly to change frames.
257
258       To resume autoplay from wherever you are, use start().
259
260       If you want to restart autoplay from the initial frame, just do:
261
262         $sprite->reset->start;
263

AUTHORS

265       See "AUTHORS" in SDL.
266

NAME

CATEGORY

SYNOPSIS

DESCRIPTION

WARNING! VOLATILE CODE AHEAD

ATTRIBUTES AND METHODS

start()

stop()

AUTHORS

SEE ALSO