.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "pods::SDLx::Sprite::Animated 3pm"
.TH pods::SDLx::Sprite::Animated 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SDLx::Sprite::Animated \- create animated SDL sprites easily!
.SH CATEGORY
.IX Header "CATEGORY"
Extension
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use SDLx::Sprite::Animated;
\&
\&  # simplest possible form, where \*(Aqhero.png\*(Aq is an image containing
\&  # fixed\-length sprites in sequence. It doesn\*(Aqt matter if they are
\&  # placed vertically or horizontally, as long as the the widest
\&  # side is a multiple of the (narrowest) other. The widget will
\&  # automatically divide it in the proper frames, provided there is
\&  # no slack space between each frame.
\&
\&  my $animation = SDLx::Sprite::Animated\->new\->load(\*(Aqhero.png\*(Aq);
\&
\&  # that\*(Aqs it! Defaults are sane enough to DWIM in simple cases,
\&  # so you just have to call draw() on the right place. If you
\&  # need to setup your animation or have more control over it,
\&  # feel free to use the attributes and methods below.
\&
\&  # these are the most useful methods to use in your game loop
\&  # (or wherever you want to manipulate the animation):
\&  $animation\->next;
\&  $animation\->previous;
\&  $animation\->reset;
\&
\&  $animation\->current_frame;   # current frame number
\&  $animation\->current_loop;    # current loop number
\&
\&  # you can control positioning just like a regular SDLx::Sprite:
\&  $animation\->rect
\&  $animation\->x;
\&  $animation\->y;
\&
\&  # just like a regular Sprite, we fetch our source rect from \->clip,
\&  # updating it on each call to \->next (or \->previous, or \->reset).
\&  # If source rects for your animation are further apart (or less)
\&  # than the rect\*(Aqs width and height, you can adjust the animation
\&  # x/y offsets:
\&  $animation\->step_x(15);
\&  $animation\->step_y(30);
\&
\&  $animation\->draw($screen); # remember to do this! :)
\&
\&  # we can also call \->next() automatically after each draw():
\&  $animation\->start;
\&  $animation\->stop;
\&
\&  # default is to go to the next frame at each draw(). If this is
\&  # too fast for you, change the attribute below:
\&  $animation\->ticks_per_frame(10);
\&
\&  # select type of animation loop when it reaches the last frame:
\&  $animation\->type(\*(Aqcircular\*(Aq); # restarts loop at the beginning
\&  $animation\->type(\*(Aqreverse\*(Aq);  # goes backwards
\&
\&  $animation\->max_loops(3); 0 or undef for infinite looping
\&
\&
\&  # as usual, you can setup most of the above during object spawning
\&  my $animation = SDLx::Sprite::Animated\->new(
\&                       image  => \*(Aqhero.png\*(Aq,
\&                       rect   => SDL::Rect\->new(...),
\&                       step_x => 20,
\&                       step_y => 0,
\&                       ...
\&                  );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
An animation is a series of frames that are played in order. Frames are
loaded from an image, usually referred to as a Sprite Sheet or Sprite Strip.
.PP
This module let's you interact with such strips and create sprite animations
just as easily as you would manipulate a regular SDLx::Sprite object.
.SH "WARNING! VOLATILE CODE AHEAD"
.IX Header "WARNING! VOLATILE CODE AHEAD"
This is a new module and the API is subject to change without notice.
If you care, please join the discussion on the #sdl IRC channel in
\&\fIirc.perl.org\fR. All thoughts on further improving the API are welcome.
.PP
You have been warned :)
.SH "ATTRIBUTES AND METHODS"
.IX Header "ATTRIBUTES AND METHODS"
SDLx::Sprite::Animated is a \fBsubclass\fR of SDLx::Sprite, inheriting
all its attributes and methods. Please refer to that module's documentation
for information on those.
.PP
The one difference in behavior is that, while a standard SDLx::Sprite uses
\&\f(CW\*(C`\->clip()\*(C'\fR to select the part of the surface to display,
SDLx::Sprite::Animated treats \f(CW\*(C`\->clip()\*(C'\fR as the \fBinitial\fR rect, from
which to start the animation.
.PP
The following attributes and methods are available:
.SS new
.IX Subsection "new"
.ie n .SS "new( %options )"
.el .SS "new( \f(CW%options\fP )"
.IX Subsection "new( %options )"
Creates a new SDLx::Sprite::Animated object. No option is mandatory. It
accepts all the options from a regular SDLx::Sprite object plus these:
.IP \(bu 4
step_x => \f(CW$integer\fR
.Sp
Uses \f(CW$integer\fR as the number of pixels to move on the x\-axis (left-to-right,
0 being no dislocation whatsoever, when the strip goes from top to bottom)
to reach the next frame.
.IP \(bu 4
step_y => \f(CW$integer\fR
.Sp
Uses \f(CW$integer\fR as the number of pixels to move on the y\-axis (top-to-bottom,
0 being no dislocation whatsoever, when the strip goes from left to right)
to reach the next frame.
.IP \(bu 4
max_loops => \f(CW$integer\fR
.Sp
Uses \f(CW$integer\fR as the number of times to loop the animation (when it reaches
the end of the strip).
.IP \(bu 4
ticks_per_frame => \f(CW$integer\fR
.Sp
Uses \f(CW$integer\fR to set how many calls to \fBdraw()\fR must be issued before we go to
the next frame during autoplay (i.e. between calls to \fBstart()\fR and \fBstop()\fR).
.IP \(bu 4
type => \f(CW$string\fR
.Sp
Uses \f(CW$string\fR to set the type of animation loop when it reaches the last
frame in the strip. See the \fBtype()\fR method below for information on
available looping types.
.IP \(bu 4
sequences => { \f(CW$string\fR => [ [ \f(CW$x1\fR, \f(CW$y1\fR ], [ \f(CW$x2\fR, \f(CW$y2\fR ], ... ], ... }
.Sp
Uses the supplied hashref to define named sequences of frames.
.IP \(bu 4
sequence => \f(CW$string\fR
.Sp
Uses \f(CW$string\fR to set the current sequence.
.SS \fBstep_x()\fP
.IX Subsection "step_x()"
.ie n .SS "step_x( $integer )"
.el .SS "step_x( \f(CW$integer\fP )"
.IX Subsection "step_x( $integer )"
Uses \f(CW$integer\fR as the number of pixels to move on the x\-axis (left-to-right,
0 being no dislocation whatsoever, when the strip goes from top to bottom)
to reach the next frame.
.PP
Defaults to the same width as the \fBclip()\fR rect.
.SS \fBstep_y()\fP
.IX Subsection "step_y()"
.ie n .SS "step_y( $integer )"
.el .SS "step_y( \f(CW$integer\fP )"
.IX Subsection "step_y( $integer )"
Uses \f(CW$integer\fR as the number of pixels to move on the y\-axis (top-to-bottom,
0 being no dislocation whatsoever, when the strip goes from left to right)
to reach the next frame.
.PP
Defaults to the same height as the \fBclip()\fR rect.
.SS \fBmax_loops()\fP
.IX Subsection "max_loops()"
.ie n .SS "max_loops( $integer )"
.el .SS "max_loops( \f(CW$integer\fP )"
.IX Subsection "max_loops( $integer )"
Uses \f(CW$integer\fR as the number of times to loop the animation (when it reaches
the end of the strip). After that \fBall calls to previous() or next() will be no-ops\fR.
.PP
Set it to \f(CW0\fR or \f(CW\*(C`undef\*(C'\fR to allow infinite loops. Default is 0 (infinite).
.SS \fBticks_per_frame()\fP
.IX Subsection "ticks_per_frame()"
.ie n .SS "ticks_per_frame( $integer )"
.el .SS "ticks_per_frame( \f(CW$integer\fP )"
.IX Subsection "ticks_per_frame( $integer )"
Uses \f(CW$integer\fR to set how many calls to \fBdraw()\fR must be issued before we go to
the next frame during autoplay (i.e. between calls to \fBstart()\fR and \fBstop()\fR).
.PP
Default is just 1 tick per frame, so you might want to change this if it's too fast.
.SS \fBtype()\fP
.IX Subsection "type()"
.ie n .SS "type( $string )"
.el .SS "type( \f(CW$string\fP )"
.IX Subsection "type( $string )"
Uses \f(CW$string\fR to set the type of animation loop when it reaches the last
frame in the strip. Available looping types are:
.IP \(bu 4
\&'circular'
.Sp
Restarts loop at the beginning of the strip. If you have 4 frames, the flow
will be 1\-2\-3\-4\-1\-2\-3\-4\-1\-2\-3\-4\-1\-2\-... up until the number of loops you
set in the \fBmax_loops()\fR attribute.
.IP \(bu 4
\&'reverse'
.Sp
Loops back and forth on the strip. If you have 4 frames, the flow will be
1\-2\-3\-4\-3\-2\-1\-2\-3\-4\-3\-2\-... up until the number of loops you set in the
\&\fBmax_loops()\fR attribute.
.PP
Case is irrelevant for \fBtype()\fR, so for example 'Circular', 'CIRCULAR' and
\&'CiRcUlAr' are all accepted as 'circular'. The return value is guaranteed
to be lowercase.
.PP
Default value is 'circular'.
.ie n .SS "set_sequences( $string => [ [ $x1, $y1 ], [ $x2, $y2 ], ... ], ... )"
.el .SS "set_sequences( \f(CW$string\fP => [ [ \f(CW$x1\fP, \f(CW$y1\fP ], [ \f(CW$x2\fP, \f(CW$y2\fP ], ... ], ... )"
.IX Subsection "set_sequences( $string => [ [ $x1, $y1 ], [ $x2, $y2 ], ... ], ... )"
Uses the supplied hashref to define named sequences of frames. Replaces any
previously defined sequences.
.ie n .SS "sequence( $string )"
.el .SS "sequence( \f(CW$string\fP )"
.IX Subsection "sequence( $string )"
Uses \f(CW$string\fR to set the current sequence. Goes to the first frame in the
sequence and resets the loop counter.
.SS \fBnext()\fP
.IX Subsection "next()"
Goes to the next frame in the strip. Calling this method will also reset
the tick counter used by \fBticks_per_frame()\fR.
.PP
If \fBmax_loops()\fR has reached its limit, this will be a no-op.
.PP
Returns the object, allowing method chaining.
.SS \fBprevious()\fP
.IX Subsection "previous()"
Goes to the previous frame in the strip. Calling this method will also reset
the tick counter used by \fBticks_per_frame()\fR.
.PP
If \fBmax_loops()\fR has reached its limit, this will be a no-op.
.PP
Returns the object, allowing method chaining.
.SS \fBreset()\fP
.IX Subsection "reset()"
Goes to the first frame in the strip, meaning whatever clip is set to.
.PP
If \fBmax_loops()\fR has reached its limit, this will be a no-op.
.PP
Returns the object, allowing method chaining.
.SS \fBcurrent_frame()\fP
.IX Subsection "current_frame()"
Returns the current frame number. Note that this is 1\-based (first frame
is 1, second is 2, etc).
.SS \fBcurrent_loop()\fP
.IX Subsection "current_loop()"
Returns the loop counter, i.e. which run number is it at. This is also
1\-based (first time is 1, second time is 2, etc). Note that we only
keep track of the counter if \fBmax_loops()\fR is set to a finite number. Otherwise,
this will be a no-op.
.SH \fBstart()\fP
.IX Header "start()"
After you call this method, the object will issue a call to \f(CW\*(C`\->next()\*(C'\fR
automatically for you every time \f(CW\*(C`\->draw()\*(C'\fR is called
\&\f(CWticks_per_frame()\fR times.
.PP
If you want to stop autoplay, see \f(CWstop()\fR below.
.PP
Default is off (no autoplay).
.SH \fBstop()\fP
.IX Header "stop()"
Stops autoplay. After you call this, the object will need you to call
\&\f(CW\*(C`\->previous()\*(C'\fR and \f(CW\*(C`\->next()\*(C'\fR explicitly to change frames.
.PP
To resume autoplay from wherever you are, use \f(CWstart()\fR.
.PP
If you want to restart autoplay from the initial frame, just do:
.PP
.Vb 1
\&  $sprite\->reset\->start;
.Ve
.SH AUTHORS
.IX Header "AUTHORS"
See "AUTHORS" in SDL.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
SDL::Surface, SDL