1SDLx::Sprite(3)       User Contributed Perl Documentation      SDLx::Sprite(3)
2
3
4

NAME

6       SDLx::Sprite - interact with images quick and easily in SDL
7

CATEGORY

9       Extension
10

SYNOPSIS

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

DESCRIPTION

77       SDLx::Sprite is a SDL::Surface on steroids! It let's you quickly load,
78       setup and interact with images in your SDL application, abstracting all
79       the drudge code and letting you concentrate on your app's logic
80       instead.
81
82       This module automatically creates and holds SDL::Rect objects for the
83       source and destination surfaces, and provides several surface
84       manipulation options like alpha blending and rotation.
85

WARNING! VOLATILE CODE AHEAD

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

METHODS

94   new
95   new( %options )
96       Creates a new SDLx::Sprite object. No option is mandatory.  Available
97       options are:
98
99       •   image => $filename
100
101           Uses $filename as source image for the Sprite's surface. See
102           supported formats in SDL::Image. This option cannot be used
103           together with the 'surface' option (see below).
104
105       •   surface => SDL::Surface
106
107           Uses the provided SDL::Surface object as source surface for this
108           sprite, instead of creating one automatically. This option cannot
109           be used together with the 'image' option (see above).
110
111       •   clip => SDL::Rect
112
113           Uses the provided SDL::Rect object as clipping rect for the source
114           surface. This means the object will only blit that particular area
115           from the surface.
116
117       •   rect => SDL::Rect
118
119           Uses the provided SDL::Rect object as destination coordinates to
120           whatever surface you call draw() on. You cannot use this option
121           together with 'x' and 'y' (see below)
122
123       •   x => $x
124
125           Uses $x as the x-axis (left-to-right, 0 being leftmost) positioning
126           of the Sprite into the destination you call draw() upon. This
127           option cannot be used together with 'rect' (see above).
128
129       •   y => $y
130
131           Uses $y as the y-axis (top-to-bottom, 0 being topmost) positioning
132           of the Sprite into the destination you call draw() upon. This
133           option cannot be used together with 'rect' (see above).
134
135       •   draw_xy => $surface, $x, $y
136
137           A shortcut to draw at coordinates quickly. Calls x() , y() and
138           draw()
139
140       •   rotation => $degrees, [$smooth]
141
142           Uses $degrees as the angle to rotate the surface to, in degrees
143           (0..360, remember? :). This option is only available if your
144           compiled SDL library has support for GFX (see Alien::SDL for
145           details).
146
147           if $smooth is set the sprite is antialiased. This may mess with
148           your alpha_key.
149
150       •   alpha_key => SDL::Color
151
152           MUST CALL SDL::Video::get_video_mode prior to this.
153
154           Uses the provided SDL::Color object (or an array reference with
155           red, green and blue values) as the color to be turned into
156           transparent (see 'alpha' below).
157
158       •   alpha => $percentage or $integer
159
160           Uses $percentage (0 <-> 1 ) or $integer ( 0x01 - 0xff) as how much
161           transparency to add to the surface. If you use this, it is
162           mandatory that you also provide the alpha_key (see above).
163
164   load( $filename )
165       Loads the given image file into the object's internal surface. A new
166       surface is always created, so whatever you had on the previous surface
167       will be lost. Croaks on errors such as no support built for the image
168       or a file reading error (the error message is SDL::get_error and should
169       give more details).
170
171       Returns the own Sprite object, to allow method chaining.
172
173   surface()
174   surface( SDL::Surface )
175       Returns the object's internal surface, or undef if there is none.
176
177       If you pass a SDL::Surface to it, it will overwrite the original
178       surface with it, while returning the old (previous) surface. Note that,
179       as such, it will return "undef" if you use it without having previously
180       loaded either an image or a previous surface. It will Carp::confess if
181       you pass anything that's not an SDL::Surface object (or SDL::Surface
182       subclassed objects).
183
184   rect()
185   rect( SDL::Rect )
186       Returns the destination SDL::Rect object used when you call draw().
187
188       If you haven't explicitly set it, it will be a SDL::Rect with the same
189       dimensions as the object's internal surface. If no surface was set yet,
190       it will be an empty SDL::Rect (dimensions 0,0,0,0).
191
192       If you pass it a SDL::Rect object, it will set rect() to that object
193       before returning, but it will overwrite any width and height values, as
194       those are read only and set to the size of the underlying surface.
195
196       If you want to clip the source surface, set clip() instead.
197
198   clip()
199   clip( SDL::Rect )
200       Returns the source SDL::Rect object used when you call draw().
201
202       You can use this method to choose only a small subset of the object's
203       internal surface to be used on calls to draw().
204
205       If you haven't explicitly set it, it will be a SDL::Rect with the same
206       dimensions as the object's internal surface. If no surface was set yet,
207       it will be an empty SDL::Rect (dimensions 0,0,0,0).
208
209       If you pass it a SDL::Rect object, it will set clip() to that object
210       before returning.
211
212   x()
213   x( $int )
214       Gets/sets the x-axis (left-to-right, 0 being leftmost) positioning of
215       the Sprite into the destination you call draw() upon.
216
217       It is a shortcut to "$sprite->rect->x".
218
219   y()
220   y( $int )
221       Gets/sets the y-axis (top-to-bottom, 0 being topmost) positioning of
222       the Sprite into the destination you call draw() upon.
223
224       It is a shortcut to "$sprite->rect->y".
225
226   w()
227       Returns the Sprite surface's width. This method is read-only.
228
229       It is a shortcut to "$sprite->surface->w".
230
231   h()
232       Returns the Sprite surface's height. This method is read-only.
233
234       It is a shortcut to "$sprite->surface->h".
235
236   draw( SDL::Surface )
237       Draws the Sprite on the provided SDL::Surface object - usually the
238       screen - using the blit_surface SDL function, using the source rect
239       from clip() and the destination rect (position) from rect().
240
241       Returns the own Sprite object, to allow method chaining.
242

AUTHORS

244       See "AUTHORS" in SDL.
245

SEE ALSO

247       SDL::Surface, SDL
248
249
250
251perl v5.32.1                      2021-01-27                   SDLx::Sprite(3)
Impressum