Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pods::SDLx::Sprite(3) User Contributed Perl Documentationpods::SDLx::Sprite(3)

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

CATEGORY
       Extension

SYNOPSIS
	   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
       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
       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
   new
   new(	%options )
       Creates a new SDLx::Sprite object. No option is mandatory.  Available
       options are:

       o   image => $filename

	   Uses	$filename as source image for the Sprite's surface. See
	   supported formats in	SDL::Image. This option	cannot be used
	   together with the 'surface' option (see below).

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

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

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

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

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

       o   draw_xy => $surface,	$x, $y

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

       o   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 sprite	is antialiased.	This may mess with
	   your	alpha_key.

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

       o   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 Carp::confess 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
       See "AUTHORS" in	SDL.

SEE ALSO
       SDL::Surface, SDL

perl v5.24.1			  2017-07-11		 pods::SDLx::Sprite(3)

NAME | CATEGORY | SYNOPSIS | DESCRIPTION | WARNING! VOLATILE CODE AHEAD | METHODS | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pods::SDLx::Sprite&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help