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 @@ +
+ +

Index

+ +
+ + +

NAME

Top

+
+

SDLx::Sprite - interact with images quick and easily in SDL

+ +
+

CATEGORY

Top

+
+

Extension

+ +
+

SYNOPSIS

Top

+
+
    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
+         );
+
+
+
+
+
+ +
+

DESCRIPTION

Top

+
+

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.

+ +
+

WARNING! VOLATILE CODE AHEAD

Top

+
+

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 :)

+ +
+

METHODS

Top

+
+ +
+

new

+
+ +
+

new( %options )

+
+

Creates a new SDLx::Sprite object. No option is mandatory. +Available options are:

+
+
* image => $filename
+
+

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).

+
+
* surface => SDL::Surface
+
+

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).

+
+
* clip => SDL::Rect
+
+

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.

+
+
* rect => SDL::Rect
+
+

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)

+
+
* x => $x
+
+

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).

+
+
* y => $y
+
+

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).

+
+
* draw_xy => $surface, $x, $y
+
+

A shortcut to draw at coordinates quickly. Calles x() , y() and draw()

+
+
* rotation => $degrees, [$smooth]
+
+

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.

+
+
* alpha_key => SDL::Color
+
+

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).

+
+
* alpha => $percentage or $integer
+
+ + + + +

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).

+
+
+ +
+

load( $filename )

+
+

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.

+ +
+

surface()

+
+ +
+

surface( SDL::Surface )

+
+

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).

+ +
+

rect()

+
+ +
+

rect( SDL::Rect )

+
+

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.

+ +
+

clip()

+
+ +
+

clip( SDL::Rect )

+
+

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.

+ +
+

x()

+
+ +
+

x( $int )

+
+

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.

+ + + + + +
+

y()

+
+ +
+

y( $int )

+
+

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.

+ + + + + +
+

w()

+
+

Returns the Sprite surface's width. This method is read-only.

+

It is a shortcut to $sprite->surface->w.

+ + + + + +
+

h()

+
+

Returns the Sprite surface's height. This method is read-only.

+

It is a shortcut to $sprite->surface->h.

+ + + + + +
+

draw( SDL::Surface )

+
+

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.

+ +
+

AUTHORS

Top

+
+

Dustin Mays, <dork.fish.wat@gmail.com>

+

Breno G. de Oliveira, <garu at cpan.org>

+

Kartik thakore <kthakore at cpan.org>

+ +
+

SEE ALSO

Top

+
+

SDL::Surface, SDL +

+ +
+
\ No newline at end of file