/lib/pods/SDLx/Sprite.pod

  1
  2=head1 NAME
  3
  4SDLx::Sprite - interact with images quick and easily in SDL
  5
  6=head1 CATEGORY
  7
  8Extension
  9
 10=head1 SYNOPSIS
 11
 12    use SDLx::Sprite;
 13
 14    my $sprite = SDLx::Sprite->new;
 15
 16    # loads image file into a SDL::Surface and
 17    # automatically sets a SDL::Rect inside with
 18    # that image's dimensions.
 19    $sprite->load('hero.png');
 20
 21    # set sprite image transparency
 22    $sprite->alpha_key( $color );
 23    $sprite->alpha(0.5);
 24
 25    # you can set and check the sprite position anytime
 26    say $sprite->x;   # rect->x shortcut accessor
 27    $sprite->y(30);   # rect->y shortcut accessor
 28
 29    # read-only surface dimensions
 30    $sprite->w;   # width
 31    $sprite->h;   # height
 32
 33    # you can also fetch the full rect
 34    # (think destination coordinates for ->draw)
 35    my $rect = $sprite->rect;
 36
 37    # you can get the surface object too if you need it
 38    my $surface = $sprite->surface;
 39
 40    # rotation() 
 41
 42    # if your SDL has gfx, rotation is also straightforward:
 43    $sprite->rotation( $degrees );
 44    $sprite->rotation( $degrees, $smooth );
 45
 46
 47    # add() / remove() NOT YET IMPLEMENTED
 48    # you can also attach other sprites to it
 49    $sprite->add( armor => $other_sprite );
 50    $sprite->remove('armor');
 51
 52    # blits $sprite (and attached sprites) into $screen,
 53    # in the (x,y) coordinates of the sprite
 54    $sprite->draw($screen);
 55
 56    # if you need to clip the original image/surface
 57    # before drawing it
 58    $sprite->clip->x(10);
 59    $sprite->clip->y(3);
 60    $sprite->clip->w(5);
 61    $sprite->clip->h(5);
 62
 63    # ...or all at once:
 64    $sprite->clip($x,$y,$w,$h);
 65
 66    # spawning can include almost all of the above:
 67    my $sprite = SDLx::Sprite->new(
 68              image   => 'hero.png',   # or surface => SDL::Surface
 69              rect    => SDL::Rect,    # or x => $x, y => $y
 70              clip    => SDL::Rect,
 71              alpha_key => SDL::Color, # or [$r, $g, $b]
 72              alpha     => 1,
 73              rotation  => 45, # degrees
 74         );
 75
 76
 77=head1 DESCRIPTION
 78
 79SDLx::Sprite is a SDL::Surface on steroids! It let's you quickly
 80load, setup and interact with images in your SDL application, abstracting
 81all the drudge code and letting you concentrate on your app's logic instead.
 82
 83This module automatically creates and holds SDL::Rect objects for the source
 84and destination surfaces, and provides several surface manipulation options
 85like alpha blending and rotation.
 86
 87=head1 WARNING! VOLATILE CODE AHEAD
 88
 89This is a new module and the API is subject to change without notice.
 90If you care, please join the discussion on the #sdl IRC channel in
 91I<irc.perl.org>. All thoughts on further improving the API are welcome.
 92
 93You have been warned :)
 94
 95=head1 METHODS
 96
 97=head2 new
 98
 99=head2 new( %options )
100
101Creates a new SDLx::Sprite object. No option is mandatory.
102Available options are:
103
104=over 4
105
106=item * image => $filename
107
108Uses $filename as source image for the Sprite's surface. See supported
109formats in L<< SDL::Image >>. This option B<cannot> be used together
110with the 'surface' option (see below).
111
112=item * surface => SDL::Surface
113
114Uses the provided L<< SDL::Surface >> object as source surface for this
115sprite, instead of creating one automatically. This option B<cannot> be
116used together with the 'image' option (see above).
117
118=item * clip => SDL::Rect
119
120Uses the provided L<< SDL::Rect >> object as clipping rect for the source
121surface. This means the object will only blit that particular area from
122the surface.
123
124=item * rect => SDL::Rect
125
126Uses the provided L<< SDL::Rect >> object as destination coordinates to
127whatever surface you call draw() on. You B<cannot> use this option together
128with 'x' and 'y' (see below)
129
130=item * x => $x
131
132Uses $x as the x-axis (left-to-right, 0 being leftmost) positioning of
133the Sprite into the destination you call draw() upon. This option B<cannot>
134be used together with 'rect' (see above).
135
136=item * y => $y
137
138Uses $y as the y-axis (top-to-bottom, 0 being topmost) positioning of
139the Sprite into the destination you call draw() upon. This option B<cannot>
140be used together with 'rect' (see above).
141
142=item * draw_xy => $surface, $x, $y
143
144A shortcut to draw at coordinates quickly. Calls x() , y() and draw()
145
146=item * rotation => $degrees, [$smooth]
147
148Uses $degrees as the angle to rotate the surface to, in degrees
149(0..360, remember? :). This option is only available if your compiled SDL
150library has support for GFX (see L<< Alien::SDL >> for details).
151
152if $smooth is set the sprite is antialiased. This may mess with your alpha_key.
153
154=item * alpha_key => SDL::Color
155
156MUST CALL L<SDL::Video::get_video_mode|SDL::Video/"get_video_mode"> prior to this. 
157
158Uses the provided L<< SDL::Color >> object (or an array reference with red,
159green and blue values) as the color to be turned into transparent
160(see 'alpha' below).
161
162=item * alpha => $percentage or $integer
163
164
165Uses $percentage (0 <-> 1 ) or $integer ( 0x01 - 0xff) as how much transparency to add to the surface. If you use
166this, it is mandatory that you also provide the alpha_key (see above).
167
168=back
169
170=head2 load( $filename )
171
172Loads the given image file into the object's internal surface. A new surface
173is B<always> created, so whatever you had on the previous surface will be
174lost. Croaks on errors such as no support built for the image or a file
175reading error (the error message is SDL::get_error and should give more
176details).
177
178Returns the own Sprite object, to allow method chaining.
179
180=head2 surface()
181
182=head2 surface( SDL::Surface )
183
184Returns the object's internal surface, or undef if there is none.
185
186If you pass a SDL::Surface to it, it will overwrite the original surface
187with it, while returning the B<old> (previous) surface. Note that, as such,
188it will return C<undef> if you use it without having previously loaded
189either an image or a previous surface. It will Carp::confess if you pass anything
190that's not an SDL::Surface object (or SDL::Surface subclassed objects).
191
192=head2 rect()
193
194=head2 rect( SDL::Rect )
195
196Returns the destination L<< SDL::Rect >> object used when you call draw().
197
198If you haven't explicitly set it, it will be a SDL::Rect with the same
199dimensions as the object's internal surface. If no surface was set yet,
200it will be an empty SDL::Rect (dimensions 0,0,0,0).
201
202If you pass it a L<< SDL::Rect >> object, it will set rect() to that object
203before returning, but it will B<overwrite> any width and height values, as
204those are read only and set to the size of the underlying surface.
205
206If you want to clip the source surface, set clip() instead.
207
208=head2 clip()
209
210=head2 clip( SDL::Rect )
211
212Returns the source L<< SDL::Rect >> object used when you call draw().
213
214You can use this method to choose only a small subset of the object's
215internal surface to be used on calls to draw().
216
217If you haven't explicitly set it, it will be a SDL::Rect with the same
218dimensions as the object's internal surface. If no surface was set yet,
219it will be an empty SDL::Rect (dimensions 0,0,0,0).
220
221If you pass it a L<< SDL::Rect >> object, it will set clip() to that object
222before returning.
223
224=head2 x()
225
226=head2 x( $int )
227
228Gets/sets the x-axis (left-to-right, 0 being leftmost) positioning of
229the Sprite into the destination you call draw() upon.
230
231It is a shortcut to C<< $sprite->rect->x >>.
232
233
234=head2 y()
235
236=head2 y( $int )
237
238Gets/sets the y-axis (top-to-bottom, 0 being topmost) positioning of
239the Sprite into the destination you call draw() upon.
240
241It is a shortcut to C<< $sprite->rect->y >>.
242
243
244=head2 w()
245
246Returns the Sprite surface's width. This method is read-only.
247
248It is a shortcut to C<< $sprite->surface->w >>.
249
250
251=head2 h()
252
253Returns the Sprite surface's height. This method is read-only.
254
255It is a shortcut to C<< $sprite->surface->h >>.
256
257
258=head2 draw( SDL::Surface )
259
260Draws the Sprite on the provided SDL::Surface object - usually the screen -
261using the blit_surface SDL function, using the source rect from clip() and the
262destination rect (position) from rect().
263
264Returns the own Sprite object, to allow method chaining.
265
266=head1 AUTHORS
267
268See L<SDL/AUTHORS>.
269
270=head1 SEE ALSO
271
272L<< SDL::Surface >>, L<< SDL >>