1SDLx::Sprite(3) User Contributed Perl Documentation SDLx::Sprite(3)
2
3
4
6 SDLx::Sprite - interact with images quick and easily in SDL
7
9 Extension
10
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
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
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
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
244 See "AUTHORS" in SDL.
245
247 SDL::Surface, SDL
248
249
250
251perl v5.28.1 2019-02-02 SDLx::Sprite(3)