pages/SDLx-Sprite-Animated.html-inc

   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="#set_sequences_string_gt_x1_y1_x2_y2">set_sequences( $string =&gt; [ [ $x1, $y1 ], [ $x2, $y2 ], ... ], ... )</a></li>
  24 <li><a href="#sequence_string">sequence( $string )</a></li>
  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-&gt;new-&gt;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-&gt;next;
  71   $animation-&gt;previous;
  72   $animation-&gt;reset;
  73
  74   $animation-&gt;current_frame;   # current frame number
  75   $animation-&gt;current_loop;    # current loop number
  76
  77   # you can control positioning just like a regular SDLx::Sprite:
  78   $animation-&gt;rect
  79   $animation-&gt;x;
  80   $animation-&gt;y;
  81
  82   # just like a regular Sprite, we fetch our source rect from -&gt;clip,
  83   # updating it on each call to -&gt;next (or -&gt;previous, or -&gt;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-&gt;step_x(15);
  88   $animation-&gt;step_y(30);
  89
  90   $animation-&gt;draw($screen); # remember to do this! :)
  91
  92   # we can also call -&gt;next() automatically after each draw():
  93   $animation-&gt;start;
  94   $animation-&gt;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-&gt;ticks_per_frame(10);
  99
 100   # select type of animation loop when it reaches the last frame:
 101   $animation-&gt;type('circular'); # restarts loop at the beginning
 102   $animation-&gt;type('reverse');  # goes backwards
 103
 104   $animation-&gt;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-&gt;new(
 111                        image  =&gt; 'hero.png',
 112                        rect   =&gt; SDL::Rect-&gt;new(...),
 113                        step_x =&gt; 20,
 114                        step_y =&gt; 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>-&gt;clip()</code> to select the part of the surface to display,
 147 SDLx::Sprite::Animated treats <code>-&gt;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 =&gt; $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 =&gt; $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 =&gt; $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 =&gt; $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 =&gt; $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>
 189         <dt>* sequences =&gt; { $string =&gt; [ [ $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 =&gt; $string</dt>
 194         <dd>
 195                 <p>Uses $string to set the current sequence.</p>
 196         </dd>
 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>
 274 <h2 id="set_sequences_string_gt_x1_y1_x2_y2">set_sequences( $string =&gt; [ [ $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>
 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>-&gt;next()</code>
 326 automatically for you every time <code>-&gt;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>-&gt;previous()</code> and <code>-&gt;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-&gt;reset-&gt;start;
 339
 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">
 345 <p>See <b>AUTHORS</b> in <cite>SDL</cite>.</p>
 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>