Commit | Line | Data |
30fd24c2 |
1 | <div class="pod"> |
2 | <!-- INDEX START --> |
3 | <h3 id="TOP">Index</h3> |
4 | |
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> |
27 | </ul> |
28 | </li> |
29 | <li><a href="#AUTHORS">AUTHORS</a></li> |
30 | <li><a href="#SEE_ALSO">SEE ALSO</a> |
31 | </li> |
32 | </ul><hr /> |
33 | <!-- INDEX END --> |
34 | |
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> |
38 | |
39 | </div> |
40 | <h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p> |
41 | <div id="CATEGORY_CONTENT"> |
42 | <p>Extension</p> |
43 | |
44 | </div> |
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; |
48 | |
49 | my $sprite = SDLx::Sprite->new; |
50 | |
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'); |
55 | |
56 | # set sprite image transparency |
57 | $sprite->alpha_key( $color ); |
58 | $sprite->alpha(0.5); |
59 | |
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 |
63 | |
64 | # read-only surface dimensions |
65 | $sprite->w; # width |
66 | $sprite->h; # height |
67 | |
68 | # you can also fetch the full rect |
69 | # (think destination coordinates for ->draw) |
70 | my $rect = $sprite->rect; |
71 | |
72 | # you can get the surface object too if you need it |
73 | my $surface = $sprite->surface; |
74 | |
75 | # rotation() |
76 | |
77 | # if your SDL has gfx, rotation is also straightforward: |
78 | $sprite->rotation( $degrees ); |
79 | $sprite->rotation( $degrees, $smooth ); |
80 | |
81 | |
82 | |
83 | |
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'); |
88 | |
89 | # blits $sprite (and attached sprites) into $screen, |
90 | # in the (x,y) coordinates of the sprite |
91 | $sprite->draw($screen); |
92 | |
93 | # if you need to clip the original image/surface |
94 | # before drawing it |
95 | $sprite->clip->x(10); |
96 | $sprite->clip->y(3); |
97 | $sprite->clip->w(5); |
98 | $sprite->clip->h(5); |
99 | |
100 | # ...or all at once: |
101 | $sprite->clip($x,$y,$w,$h); |
102 | |
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] |
109 | alpha => 1, |
110 | rotation => 45, # degrees |
111 | ); |
112 | |
113 | |
114 | |
115 | |
116 | </pre> |
117 | |
118 | </div> |
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> |
127 | |
128 | </div> |
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> |
135 | |
136 | </div> |
137 | <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
138 | <div id="METHODS_CONTENT"> |
139 | |
140 | </div> |
141 | <h2 id="new">new</h2> |
142 | <div id="new_CONTENT"> |
143 | |
144 | </div> |
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> |
149 | <dl> |
150 | <dt>* image => $filename</dt> |
151 | <dd> |
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> |
155 | </dd> |
156 | <dt>* surface => SDL::Surface</dt> |
157 | <dd> |
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> |
161 | </dd> |
162 | <dt>* clip => SDL::Rect</dt> |
163 | <dd> |
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 |
166 | the surface.</p> |
167 | </dd> |
168 | <dt>* rect => SDL::Rect</dt> |
169 | <dd> |
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> |
173 | </dd> |
174 | <dt>* x => $x</dt> |
175 | <dd> |
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> |
179 | </dd> |
180 | <dt>* y => $y</dt> |
181 | <dd> |
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> |
185 | </dd> |
186 | <dt>* draw_xy => $surface, $x, $y</dt> |
187 | <dd> |
c7e8d3c6 |
188 | <p>A shortcut to draw at coordinates quickly. Calls x() , y() and draw()</p> |
30fd24c2 |
189 | </dd> |
190 | <dt>* rotation => $degrees, [$smooth]</dt> |
191 | <dd> |
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> |
c7e8d3c6 |
195 | <p>if $smooth is set the sprite is antialiased. This may mess with your alpha_key.</p> |
30fd24c2 |
196 | </dd> |
197 | <dt>* alpha_key => SDL::Color</dt> |
198 | <dd> |
1dbe1697 |
199 | <p>MUST CALL <a href="/SDL-Video.html#get_video_mode">SDL::Video::get_video_mode</a> prior to this. </p> |
30fd24c2 |
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> |
203 | </dd> |
204 | <dt>* alpha => $percentage or $integer</dt> |
205 | <dd> |
206 | |
207 | |
208 | |
209 | |
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> |
212 | </dd> |
213 | </dl> |
214 | |
215 | </div> |
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 |
222 | details).</p> |
223 | <p>Returns the own Sprite object, to allow method chaining.</p> |
224 | |
225 | </div> |
226 | <h2 id="surface">surface()</h2> |
227 | <div id="surface_CONTENT"> |
228 | |
229 | </div> |
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 |
3afd3fb0 |
236 | either an image or a previous surface. It will Carp::confess if you pass anything |
30fd24c2 |
237 | that's not an SDL::Surface object (or SDL::Surface subclassed objects).</p> |
238 | |
239 | </div> |
240 | <h2 id="rect">rect()</h2> |
241 | <div id="rect_CONTENT"> |
242 | |
243 | </div> |
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> |
254 | |
255 | </div> |
256 | <h2 id="clip">clip()</h2> |
257 | <div id="clip_CONTENT"> |
258 | |
259 | </div> |
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> |
270 | |
271 | </div> |
272 | <h2 id="x">x()</h2> |
273 | <div id="x_CONTENT"> |
274 | |
275 | </div> |
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> |
281 | |
282 | |
283 | |
284 | |
285 | |
286 | </div> |
287 | <h2 id="y">y()</h2> |
288 | <div id="y_CONTENT"> |
289 | |
290 | </div> |
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> |
296 | |
297 | |
298 | |
299 | |
300 | |
301 | </div> |
302 | <h2 id="w">w()</h2> |
303 | <div id="w_CONTENT"> |
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> |
306 | |
307 | |
308 | |
309 | |
310 | |
311 | </div> |
312 | <h2 id="h">h()</h2> |
313 | <div id="h_CONTENT"> |
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> |
316 | |
317 | |
318 | |
319 | |
320 | |
321 | </div> |
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> |
328 | |
329 | </div> |
330 | <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p> |
331 | <div id="AUTHORS_CONTENT"> |
1dbe1697 |
332 | <p>See <a href="/SDL.html#AUTHORS">/SDL.html#AUTHORS</a>.</p> |
30fd24c2 |
333 | |
334 | </div> |
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> |
338 | </p> |
339 | |
340 | </div> |
341 | </div> |