3 <h3 id="TOP">Index</h3>
5 <ul><li><a href="#NAME">NAME</a></li>
6 <li><a href="#CATEGORY">CATEGORY</a></li>
7 <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
8 <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
9 <li><a href="#WARNING_VOLATILE_CODE_AHEAD">WARNING! VOLATILE CODE AHEAD</a></li>
10 <li><a href="#METHODS">METHODS</a>
11 <ul><li><a href="#new">new</a></li>
12 <li><a href="#new_options">new( %options )</a></li>
13 <li><a href="#load_filename">load( $filename )</a></li>
14 <li><a href="#surface">surface()</a></li>
15 <li><a href="#surface_SDL_Surface">surface( SDL::Surface )</a></li>
16 <li><a href="#rect">rect()</a></li>
17 <li><a href="#rect_SDL_Rect">rect( SDL::Rect )</a></li>
18 <li><a href="#clip">clip()</a></li>
19 <li><a href="#clip_SDL_Rect">clip( SDL::Rect )</a></li>
20 <li><a href="#x">x()</a></li>
21 <li><a href="#x_int">x( $int )</a></li>
22 <li><a href="#y">y()</a></li>
23 <li><a href="#y_int">y( $int )</a></li>
24 <li><a href="#w">w()</a></li>
25 <li><a href="#h">h()</a></li>
26 <li><a href="#draw_SDL_Surface">draw( SDL::Surface )</a></li>
29 <li><a href="#AUTHORS">AUTHORS</a></li>
30 <li><a href="#SEE_ALSO">SEE ALSO</a>
35 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
36 <div id="NAME_CONTENT">
37 <p>SDLx::Sprite - interact with images quick and easily in SDL</p>
40 <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
41 <div id="CATEGORY_CONTENT">
45 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
46 <div id="SYNOPSIS_CONTENT">
47 <pre> use SDLx::Sprite;
49 my $sprite = SDLx::Sprite->new;
51 # loads image file into a SDL::Surface and
52 # automatically sets a SDL::Rect inside with
53 # that image's dimensions.
54 $sprite->load('hero.png');
56 # set sprite image transparency
57 $sprite->alpha_key( $color );
58 $sprite->alpha(0.5);
60 # you can set and check the sprite position anytime
61 say $sprite->x; # rect->x shortcut accessor
62 $sprite->y(30); # rect->y shortcut accessor
64 # read-only surface dimensions
65 $sprite->w; # width
66 $sprite->h; # height
68 # you can also fetch the full rect
69 # (think destination coordinates for ->draw)
70 my $rect = $sprite->rect;
72 # you can get the surface object too if you need it
73 my $surface = $sprite->surface;
77 # if your SDL has gfx, rotation is also straightforward:
78 $sprite->rotation( $degrees );
79 $sprite->rotation( $degrees, $smooth );
84 # add() / remove() NOT YET IMPLEMENTED
85 # you can also attach other sprites to it
86 $sprite->add( armor => $other_sprite );
87 $sprite->remove('armor');
89 # blits $sprite (and attached sprites) into $screen,
90 # in the (x,y) coordinates of the sprite
91 $sprite->draw($screen);
93 # if you need to clip the original image/surface
95 $sprite->clip->x(10);
96 $sprite->clip->y(3);
97 $sprite->clip->w(5);
98 $sprite->clip->h(5);
101 $sprite->clip($x,$y,$w,$h);
103 # spawning can include almost all of the above:
104 my $sprite = SDLx::Sprite->new(
105 image => 'hero.png', # or surface => SDL::Surface
106 rect => SDL::Rect, # or x => $x, y => $y
107 clip => SDL::Rect,
108 alpha_key => SDL::Color, # or [$r, $g, $b]
110 rotation => 45, # degrees
119 <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
120 <div id="DESCRIPTION_CONTENT">
121 <p>SDLx::Sprite is a SDL::Surface on steroids! It let's you quickly
122 load, setup and interact with images in your SDL application, abstracting
123 all the drudge code and letting you concentrate on your app's logic instead.</p>
124 <p>This module automatically creates and holds SDL::Rect objects for the source
125 and destination surfaces, and provides several surface manipulation options
126 like alpha blending and rotation.</p>
129 <h1 id="WARNING_VOLATILE_CODE_AHEAD">WARNING! VOLATILE CODE AHEAD</h1><p><a href="#TOP" class="toplink">Top</a></p>
130 <div id="WARNING_VOLATILE_CODE_AHEAD_CONTENT">
131 <p>This is a new module and the API is subject to change without notice.
132 If you care, please join the discussion on the #sdl IRC channel in
133 <i>irc.perl.org</i>. All thoughts on further improving the API are welcome.</p>
134 <p>You have been warned :)</p>
137 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
138 <div id="METHODS_CONTENT">
141 <h2 id="new">new</h2>
142 <div id="new_CONTENT">
145 <h2 id="new_options">new( %options )</h2>
146 <div id="new_options_CONTENT">
147 <p>Creates a new SDLx::Sprite object. No option is mandatory.
148 Available options are:</p>
150 <dt>* image => $filename</dt>
152 <p>Uses $filename as source image for the Sprite's surface. See suported
153 formats in <a href="SDL-Image.html">SDL::Image</a>. This option <strong>cannot</strong> be used together
154 with the 'surface' option (see below).</p>
156 <dt>* surface => SDL::Surface</dt>
158 <p>Uses the provided <a href="SDL-Surface.html">SDL::Surface</a> object as source surface for this
159 sprite, instead of creating one automatically. This option <strong>cannot</strong> be
160 used together with the 'image' option (see above).</p>
162 <dt>* clip => SDL::Rect</dt>
164 <p>Uses the provided <a href="SDL-Rect.html">SDL::Rect</a> object as clipping rect for the source
165 surface. This means the object will only blit that particular area from
168 <dt>* rect => SDL::Rect</dt>
170 <p>Uses the provided <a href="SDL-Rect.html">SDL::Rect</a> object as destination coordinates to
171 whatever surface you call draw() on. You <strong>cannot</strong> use this option together
172 with 'x' and 'y' (see below)</p>
174 <dt>* x => $x</dt>
176 <p>Uses $x as the x-axis (left-to-right, 0 being leftmost) positioning of
177 the Sprite into the destination you call draw() upon. This option <strong>cannot</strong>
178 be used together with 'rect' (see above).</p>
180 <dt>* y => $y</dt>
182 <p>Uses $y as the y-axis (top-to-bottom, 0 being topmost) positioning of
183 the Sprite into the destination you call draw() upon. This option <strong>cannot</strong>
184 be used together with 'rect' (see above).</p>
186 <dt>* draw_xy => $surface, $x, $y</dt>
188 <p>A shortcut to draw at coordinates quickly. Calls x() , y() and draw()</p>
190 <dt>* rotation => $degrees, [$smooth]</dt>
192 <p>Uses $degrees as the angle to rotate the surface to, in degrees
193 (0..360, remember? :). This option is only available if your compiled SDL
194 library has support for GFX (see <a href="http://search.cpan.org/perldoc?Alien::SDL">Alien::SDL</a> for details).</p>
195 <p>if $smooth is set the sprite is antialiased. This may mess with your alpha_key.</p>
197 <dt>* alpha_key => SDL::Color</dt>
199 <p>MUST CALL <a href="/SDL-Video.html#get_video_mode">SDL::Video::get_video_mode</a> prior to this. </p>
200 <p>Uses the provided <a href="SDL-Color.html">SDL::Color</a> object (or an array reference with red,
201 green and blue values) as the color to be turned into transparent
202 (see 'alpha' below).</p>
204 <dt>* alpha => $percentage or $integer</dt>
210 <p>Uses $percentage (0 <-> 1 ) or $integer ( 0x01 - 0xff) as how much transparency to add to the surface. If you use
211 this, it is mandatory that you also provide the alpha_key (see above).</p>
216 <h2 id="load_filename">load( $filename )</h2>
217 <div id="load_filename_CONTENT">
218 <p>Loads the given image file into the object's internal surface. A new surface
219 is <strong>always</strong> created, so whatever you had on the previous surface will be
220 lost. Croaks on errors such as no support built for the image or a file
221 reading error (the error message is SDL::get_error and should give more
223 <p>Returns the own Sprite object, to allow method chaining.</p>
226 <h2 id="surface">surface()</h2>
227 <div id="surface_CONTENT">
230 <h2 id="surface_SDL_Surface">surface( SDL::Surface )</h2>
231 <div id="surface_SDL_Surface_CONTENT">
232 <p>Returns the object's internal surface, or undef if there is none.</p>
233 <p>If you pass a SDL::Surface to it, it will overwrite the original surface
234 with it, while returning the <strong>old</strong> (previous) surface. Note that, as such,
235 it will return <code>undef</code> if you use it without having previously loaded
236 either an image or a previous surface. It will Carp::confess if you pass anything
237 that's not an SDL::Surface object (or SDL::Surface subclassed objects).</p>
240 <h2 id="rect">rect()</h2>
241 <div id="rect_CONTENT">
244 <h2 id="rect_SDL_Rect">rect( SDL::Rect )</h2>
245 <div id="rect_SDL_Rect_CONTENT">
246 <p>Returns the destination <a href="SDL-Rect.html">SDL::Rect</a> object used when you call draw().</p>
247 <p>If you haven't explicitly set it, it will be a SDL::Rect with the same
248 dimensions as the object's internal surface. If no surface was set yet,
249 it will be an empty SDL::Rect (dimensions 0,0,0,0).</p>
250 <p>If you pass it a <a href="SDL-Rect.html">SDL::Rect</a> object, it will set rect() to that object
251 before returning, but it will <strong>overwrite</strong> any width and height values, as
252 those are read only and set to the size of the underlying surface.</p>
253 <p>If you want to clip the source surface, set clip() instead.</p>
256 <h2 id="clip">clip()</h2>
257 <div id="clip_CONTENT">
260 <h2 id="clip_SDL_Rect">clip( SDL::Rect )</h2>
261 <div id="clip_SDL_Rect_CONTENT">
262 <p>Returns the source <a href="SDL-Rect.html">SDL::Rect</a> object used when you call draw().</p>
263 <p>You can use this method to choose only a small subset of the object's
264 internal surface to be used on calls to draw().</p>
265 <p>If you haven't explicitly set it, it will be a SDL::Rect with the same
266 dimensions as the object's internal surface. If no surface was set yet,
267 it will be an empty SDL::Rect (dimensions 0,0,0,0).</p>
268 <p>If you pass it a <a href="SDL-Rect.html">SDL::Rect</a> object, it will set clip() to that object
269 before returning.</p>
276 <h2 id="x_int">x( $int )</h2>
277 <div id="x_int_CONTENT">
278 <p>Gets/sets the x-axis (left-to-right, 0 being leftmost) positioning of
279 the Sprite into the destination you call draw() upon.</p>
280 <p>It is a shortcut to <code>$sprite->rect->x</code>.</p>
291 <h2 id="y_int">y( $int )</h2>
292 <div id="y_int_CONTENT">
293 <p>Gets/sets the y-axis (top-to-bottom, 0 being topmost) positioning of
294 the Sprite into the destination you call draw() upon.</p>
295 <p>It is a shortcut to <code>$sprite->rect->y</code>.</p>
304 <p>Returns the Sprite surface's width. This method is read-only.</p>
305 <p>It is a shortcut to <code>$sprite->surface->w</code>.</p>
314 <p>Returns the Sprite surface's height. This method is read-only.</p>
315 <p>It is a shortcut to <code>$sprite->surface->h</code>.</p>
322 <h2 id="draw_SDL_Surface">draw( SDL::Surface )</h2>
323 <div id="draw_SDL_Surface_CONTENT">
324 <p>Draws the Sprite on the provided SDL::Surface object - usually the screen -
325 using the blit_surface SDL function, using the source rect from clip() and the
326 destination rect (position) from rect().</p>
327 <p>Returns the own Sprite object, to allow method chaining.</p>
330 <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
331 <div id="AUTHORS_CONTENT">
332 <p>See <a href="/SDL.html#AUTHORS">/SDL.html#AUTHORS</a>.</p>
335 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
336 <div id="SEE_ALSO_CONTENT">
337 <p><a href="SDL-Surface.html">SDL::Surface</a>, <a href="SDL.html">SDL</a>