SDL::Surface - a SDL perl extension
use SDL::Surface; $image = new SDL::Surface(-name=>"yomama.jpg");
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);
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);
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.
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
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.
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.
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.
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.
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.
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.
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");
David J. Goehrig
perl(1) SDL::Rect(3) SDL::Font(3).
To install SDL::sdlpl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SDL::sdlpl
CPAN shell
perl -MCPAN -e shell install SDL::sdlpl
For more information on module installation, please visit the detailed CPAN module installation guide.