/ 
SDL-sdlpl-1.08
River stage zero No dependents
/ SDL::Surface

NAME

SDL::Surface - a SDL perl extension

SYNOPSIS

use SDL::Surface;
$image = new SDL::Surface(-name=>"yomama.jpg");

DESCRIPTION

SDL::Surface->new(-name=>"yomama.jpg"); will load an image named
yomama.jpg, which works equally well with images of type bmp, ppm, pcx,
gif, jpeg, and png. Optionally, if you would like a scratch surface 
to work with, you can createit using this function using the following
syntax:

SDL::Surface->new(-flags=>SDL_SWSURFACE,-width=>666,-height=>666,-depth=>8);

which will produce a software suface, at 666x666x256 colors. To create an image using the default depth and flag state simply use:

SDL::Surface->new(-width=>$my_w,-height=>$my_h);

If you are on a big endian machine, or some really funky hardware you can set the RGBA bitmasks with the keys -Rmask, -Gmask, -Bmask, -Amask. For example to create a scratch surface on a big endian machine one would use: SDL::Surface->new(-width=>200,-height=>100, -Rmask=>0xff000000,-Gmask=>0x00ff0000, -Bmask=>0x0000ff00,-Amask=>0x000000ff);

DESTROY

When a surface is destroyed, perl will call SDL_FreeSurface() on
it. Hence don't worry about freeing it yourself.  If you must, then 
invoke the function SDL::sdlpl::sdl_free_surface($your_surface);

Read-only Surface fields

The SDL_Surface structure has many subfields.  Most of these
fields are accessible in read-only form.  Most of these fields are
useless to a perl hacker anyways, and are provided for a sense
of completeness.

$surface->flags()

This field returns the flags which are applicable to the
current surface.  The possible values for the flags are:

	SDL_ANYFORMAT
	SDL_SWSURFACE
	SDL_HWSURFACE
	SDL_HWPALETTE
	SDL_DOUBLEBUF
	SDL_FULLSCREEN

$surface->palette()

This field returns a pointer to the SDL_Palette
structure for this image if it is an 8 bit image, or NULL
if the image is 16, 24, or 32 bit.  cf. Palette.pm
NB: this should not be passed to any Palette method.
what you need there is to create a new Palette object,
passing it the image as in:

my $pal = new SDL::Palette $image;

cf Palette.pm for details.

$surface->bpp()

This field returns the bits per pixel, aka depth,
of the surface.

$surface->bytes_per_pixel()

This field returns the bytes per pixel, this should
in all cases be the same as bpp/8.  Technically, it reads
that field of the SDL_PixelFormat structure for the surface.

$surface->Rshift(); $surface->Gshift(); ...

These functions return the Rshift, Gshift, Bshift, and
Ashift respectively for the surface.  To be perfectly honest,
these are not all that useful from perl, but are provided
for future expansion.

$surface->Rmask(), $surface->Gmask() ...

Like Rshift & friends, Rmask, Gmask, Bmask, and Amask 
return the current byte masks for each component of RGBA 
surfaces.  They are provided for future expansion.

$surface->color_key();

This returns the pixel value which was set using
$surface->set_color_key(flag,pixel);  This is the transparent
color for the image.

$surface->alpha();

This returns the alpha value of the surface, usually
set by $surface->set_alpha(flag,alpha);  Alpha values are
not applicable to palettized images.

$surface->width();

This returns the width of the surface.

$surface->height();

This returns the height of the surface.

$surface->clip_minx ... clip_miny ... clip_maxx ... clip_maxy

clip_minx, clip_miny, clip_maxx, and clip_maxy return
the current clipping values for the surface.

$surface->pitch();

This returns the pitch of the image, aka the width
of a single row of pixels in bytes.  This should be the same
as $surface->width()*$surface->bytes_per_pixel().
It is provided for future expansion.

Poking Pixels

The swiss-army-chainsaw of pixel manipulation, the method
$surface->pixel(x,y,color); can be used to read or set the value
of a pixel at the point (x,y).  If no color value is passed, it
will simply read the value at that point.  If a color is passed, it
will set the point to that value and then return the value to which
it  was actually set.  

For the speed conscious, this function is SLOW.  It is not
designed for line drawing or other large-scale projects.  It is my
intention to provide a generic drawing system in the future,
and additional low level memory tools, but in the mean time, if you
must this cudgel.

So just to reiterate:

$surface->pixel(12,13);	# returns the pixel at (12,13)
$surface->pixel(12,13,0xffff); # sets that pixel to 0xffff

Filling areas

To fill a larger volume than a single pixel the method:

	$surface->fill($rect,color);

will fill a rectangle with the value of color. With intelligent use of Rect objects one can draw buttons and the like. It is also useful in clearing the screen.

Locking, Unlocking, and the like...

When writing to certain surfaces, notably some SDL_HWSURFACE
flaged surfaces, it is necessary to lock the surface before twiddling
its bits.  To tell if you must do so it is wise to call the function:

$suface->lockp();

If it returns non-zero you should then call:

$surface->lock();

and after your write call:

$surface->unlock();

and everything will be well. Locking and unlocking a surface which doesn't require locking only wastes time, so if you have time to spare, you could just do so by default.

Bliting & Updating

To copy image data from one surface to another, the SDL
provides a collection of functions.

$surface->update(rect,...);

will update any number of Rects of the screen, where as:

$surface->flip();

will update the entire screen.

$surface->blit($srect,$dest,$drect);

will copy the contents contained by $srect of the surface $surface into area specified bye $drect of the surface $dest. Please see the documents for Rect.pm for the creation of $srect and $drect.

So may Colors in the world ...

To set the colors in a palettized image, the method:

	$surface->set_colors($start,...)

is provided. It takes 1 or more Color objects, and sets the consecutive palette entries starting at entry $start. Hence to set the first ten palette entires one would use:

$my_surface->set_colors(0,$color1,$color2,...$color10);

where $color1 ... $color10 were created with Color->new(r,g,b); see Color.pm for details.

Transperancy and alpha levels for an image can also be set
using the methods:

	$surface->set_color_key(flag,pixel);

			and
	$surface->set_alpha(flag,alpha);

where the flags for set_color_key are: SDL_SRCCOLORKEY and SDL_RLEACCEL, and the flags for set_alpha are: SDL_SRCALPHA and SDL_MULACCEL.

Clipping

To set the clipping rectangle for a source surface the
method $surface->clip(top,left,bottom,right); will prevent
accidental bliting of material outside of this rectangle.

Format Conversion

Occasionally it will be necessary to manipulate images in
a format other than that used by the display, to manage the conversion
the method: $surface->display_format(); will produce a new surface
in the format used for display.

Fonts & Printing

As of version 1.01, SDLpl now supports SFont style
fonts.  Before printing, one must create and use a new font
as specified in SDL::Font.  For example to load a font stored
in Ionic.png one would use:

$font = new Font "Ionic.png";
$font->use;

Then to print a string to (10,13) on a surface one would use the print method of the surface:

$surface->print(10,13,"Hello World");

AUTHOR

David J. Goehrig

SEE ALSO

perl(1) SDL::Rect(3) SDL::Font(3).