1SDLx::Sprite(3pm) User Contributed Perl Documentation SDLx::Sprite(3pm)
2
6 SDLx::Sprite - interact with images quick and easily in SDL
7
9 Extension
10
12 use SDLx::Sprite;
13 my $sprite = SDLx::Sprite->new;
15 # 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 # set sprite image transparency
22 $sprite->alpha_key( $color );
23 $sprite->alpha(0.5);
24 # 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 # read-only surface dimensions
30 $sprite->w; # width
31 $sprite->h; # height
32 # you can also fetch the full rect
34 # (think destination coordinates for ->draw)
35 my $rect = $sprite->rect;
36 # you can get the surface object too if you need it
38 my $surface = $sprite->surface;
39 # rotation()
41 # if your SDL has gfx, rotation is also straightforward:
43 $sprite->rotation( $degrees );
44 $sprite->rotation( $degrees, $smooth );
45 # 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 # blits $sprite (and attached sprites) into $screen,
53 # in the (x,y) coordinates of the sprite
54 $sprite->draw($screen);
55 # 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 # ...or all at once:
64 $sprite->clip($x,$y,$w,$h);
65 # 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
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 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
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 You have been warned :)
92
94 new
95 new( %options )
96 Creates a new SDLx::Sprite object. No option is mandatory. Available
97 options are:
98 • image => $filename
100 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 • surface => SDL::Surface
106 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 • clip => SDL::Rect
112 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 • rect => SDL::Rect
118 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 • x => $x
124 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 • y => $y
130 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 • draw_xy => $surface, $x, $y
136 A shortcut to draw at coordinates quickly. Calls x() , y() and
138 draw()
139 • rotation => $degrees, [$smooth]
141 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 if $smooth is set the sprite is antialiased. This may mess with
148 your alpha_key.
149 • alpha_key => SDL::Color
151 MUST CALL SDL::Video::get_video_mode prior to this.
153 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 • alpha => $percentage or $integer
159 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 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 Returns the own Sprite object, to allow method chaining.
172 surface()
174 surface( SDL::Surface )
175 Returns the object's internal surface, or undef if there is none.
176 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 rect()
185 rect( SDL::Rect )
186 Returns the destination SDL::Rect object used when you call draw().
187 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 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 If you want to clip the source surface, set clip() instead.
197 clip()
199 clip( SDL::Rect )
200 Returns the source SDL::Rect object used when you call draw().
201 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 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 If you pass it a SDL::Rect object, it will set clip() to that object
210 before returning.
211 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 It is a shortcut to "$sprite->rect->x".
218 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 It is a shortcut to "$sprite->rect->y".
225 w()
227 Returns the Sprite surface's width. This method is read-only.
228 It is a shortcut to "$sprite->surface->w".
230 h()
232 Returns the Sprite surface's height. This method is read-only.
233 It is a shortcut to "$sprite->surface->h".
235 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 Returns the own Sprite object, to allow method chaining.
242
244 See "AUTHORS" in SDL.
245
247 SDL::Surface, SDL
248perl v5.38.0 2023-07-21 SDLx::Sprite(3pm)