X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pages%2FSDLx-Sprite.html-inc;fp=pages%2FSDLx-Sprite.html-inc;h=9f50564f89ff63e18092845955af70c5ec8c0d28;hb=30fd24c26cb4e59a5937d49aa4810269ace3a8b0;hp=0000000000000000000000000000000000000000;hpb=65a973147068b3edbbb232aa50fd53a79d7daaef;p=sdlgit%2FSDL-Site.git diff --git a/pages/SDLx-Sprite.html-inc b/pages/SDLx-Sprite.html-inc new file mode 100644 index 0000000..9f50564 --- /dev/null +++ b/pages/SDLx-Sprite.html-inc @@ -0,0 +1,343 @@ +
SDLx::Sprite - interact with images quick and easily in SDL
+ +Extension
+ +use SDLx::Sprite; + + my $sprite = SDLx::Sprite->new; + + # loads image file into a SDL::Surface and + # automatically sets a SDL::Rect inside with + # that image's dimensions. + $sprite->load('hero.png'); + + # set sprite image transparency + $sprite->alpha_key( $color ); + $sprite->alpha(0.5); + + # you can set and check the sprite position anytime + say $sprite->x; # rect->x shortcut accessor + $sprite->y(30); # rect->y shortcut accessor + + # read-only surface dimensions + $sprite->w; # width + $sprite->h; # height + + # you can also fetch the full rect + # (think destination coordinates for ->draw) + my $rect = $sprite->rect; + + # you can get the surface object too if you need it + my $surface = $sprite->surface; + + # rotation() + + # if your SDL has gfx, rotation is also straightforward: + $sprite->rotation( $degrees ); + $sprite->rotation( $degrees, $smooth ); + + + + + # add() / remove() NOT YET IMPLEMENTED + # you can also attach other sprites to it + $sprite->add( armor => $other_sprite ); + $sprite->remove('armor'); + + # blits $sprite (and attached sprites) into $screen, + # in the (x,y) coordinates of the sprite + $sprite->draw($screen); + + # if you need to clip the original image/surface + # before drawing it + $sprite->clip->x(10); + $sprite->clip->y(3); + $sprite->clip->w(5); + $sprite->clip->h(5); + + # ...or all at once: + $sprite->clip($x,$y,$w,$h); + + # spawning can include almost all of the above: + my $sprite = SDLx::Sprite->new( + image => 'hero.png', # or surface => SDL::Surface + rect => SDL::Rect, # or x => $x, y => $y + clip => SDL::Rect, + alpha_key => SDL::Color, # or [$r, $g, $b] + alpha => 1, + rotation => 45, # degrees + ); + + + + ++ +
SDLx::Sprite is a SDL::Surface on steroids! It let's you quickly +load, setup and interact with images in your SDL application, abstracting +all the drudge code and letting you concentrate on your app's logic instead.
+This module automatically creates and holds SDL::Rect objects for the source +and destination surfaces, and provides several surface manipulation options +like alpha blending and rotation.
+ +This is a new module and the API is subject to change without notice. +If you care, please join the discussion on the #sdl IRC channel in +irc.perl.org. All thoughts on further improving the API are welcome.
+You have been warned :)
+ +Creates a new SDLx::Sprite object. No option is mandatory. +Available options are:
+Uses $filename as source image for the Sprite's surface. See suported +formats in SDL::Image. This option cannot be used together +with the 'surface' option (see below).
+Uses the provided SDL::Surface object as source surface for this +sprite, instead of creating one automatically. This option cannot be +used together with the 'image' option (see above).
+Uses the provided SDL::Rect object as clipping rect for the source +surface. This means the object will only blit that particular area from +the surface.
+Uses the provided SDL::Rect object as destination coordinates to +whatever surface you call draw() on. You cannot use this option together +with 'x' and 'y' (see below)
+Uses $x as the x-axis (left-to-right, 0 being leftmost) positioning of +the Sprite into the destination you call draw() upon. This option cannot +be used together with 'rect' (see above).
+Uses $y as the y-axis (top-to-bottom, 0 being topmost) positioning of +the Sprite into the destination you call draw() upon. This option cannot +be used together with 'rect' (see above).
+A shortcut to draw at coordinates quickly. Calles x() , y() and draw()
+Uses $degrees as the angle to rotate the surface to, in degrees +(0..360, remember? :). This option is only available if your compiled SDL +library has support for GFX (see Alien::SDL for details).
+if $smooth is set the spirte is antialiased. This may mess with your alpha_key.
+MUST CALL SDL::Video::get_video_mode prior to this.
+Uses the provided SDL::Color object (or an array reference with red, +green and blue values) as the color to be turned into transparent +(see 'alpha' below).
+Uses $percentage (0 <-> 1 ) or $integer ( 0x01 - 0xff) as how much transparency to add to the surface. If you use +this, it is mandatory that you also provide the alpha_key (see above).
+Loads the given image file into the object's internal surface. A new surface +is always created, so whatever you had on the previous surface will be +lost. Croaks on errors such as no support built for the image or a file +reading error (the error message is SDL::get_error and should give more +details).
+Returns the own Sprite object, to allow method chaining.
+ +Returns the object's internal surface, or undef if there is none.
+If you pass a SDL::Surface to it, it will overwrite the original surface
+with it, while returning the old (previous) surface. Note that, as such,
+it will return undef
if you use it without having previously loaded
+either an image or a previous surface. It will croak if you pass anything
+that's not an SDL::Surface object (or SDL::Surface subclassed objects).
Returns the destination SDL::Rect object used when you call draw().
+If you haven't explicitly set it, it will be a SDL::Rect with the same +dimensions as the object's internal surface. If no surface was set yet, +it will be an empty SDL::Rect (dimensions 0,0,0,0).
+If you pass it a SDL::Rect object, it will set rect() to that object +before returning, but it will overwrite any width and height values, as +those are read only and set to the size of the underlying surface.
+If you want to clip the source surface, set clip() instead.
+ +Returns the source SDL::Rect object used when you call draw().
+You can use this method to choose only a small subset of the object's +internal surface to be used on calls to draw().
+If you haven't explicitly set it, it will be a SDL::Rect with the same +dimensions as the object's internal surface. If no surface was set yet, +it will be an empty SDL::Rect (dimensions 0,0,0,0).
+If you pass it a SDL::Rect object, it will set clip() to that object +before returning.
+ +Gets/sets the x-axis (left-to-right, 0 being leftmost) positioning of +the Sprite into the destination you call draw() upon.
+It is a shortcut to $sprite->rect->x
.
Gets/sets the y-axis (top-to-bottom, 0 being topmost) positioning of +the Sprite into the destination you call draw() upon.
+It is a shortcut to $sprite->rect->y
.
Returns the Sprite surface's width. This method is read-only.
+It is a shortcut to $sprite->surface->w
.
Returns the Sprite surface's height. This method is read-only.
+It is a shortcut to $sprite->surface->h
.
Draws the Sprite on the provided SDL::Surface object - usually the screen - +using the blit_surface SDL function, using the source rect from clip() and the +destination rect (position) from rect().
+Returns the own Sprite object, to allow method chaining.
+ +Dustin Mays, <dork.fish.wat@gmail.com>
Breno G. de Oliveira, <garu at cpan.org>
Kartik thakore <kthakore at cpan.org>
SDL::Surface, SDL +
+ +