SDL::Surface - a SDL perl extension

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

The SDL::Surface module encapsulates the SDL_Surface* structure, and many of its ancillatory functions. Not only is it a workhorse of the OO Layer, it is the base class for the SDL::App class.

	SDL_SWSURFACE		SDL_HWSURFACE
	SDL_ASYNCBLIT 		SDL_ANYFORMAT
	SDL_HWPALETTE 		SDL_DOUBLEBUF 
	SDL_FULLSCREEN		SDL_OPENGL 
	SDL_OPENGLBLIT		SDL_RESIZEABLE
	SDL_NOFRAME		SDL_SRCCOLORKEY
	SDL_RLEACCEL		SDL_SRCALPHA
	SDL_PREALLOC

The SDL::Surface class can be instantiated in a number of different ways. If support for the SDL_image library was included when SDL_perl was compiled, the easiest way to create a new surface is to use the SDL::Surface::new method with the -name option. This will load the image from the file and return an object encapsulating the SDL_Surface*.

If the contents of the new Surface is already in memory, SDL::Surface::new may be called with the -from option to create an image from that section of memory. This method takes the following additional parameters:

• -width the width of the image in pixels
• -height the height of the image in pixels
• -depth the number of bits per pixel
• -pitch the number of bytes per line
• -Rmask an optional bitmask for red
• -Gmask an optional bitmask for green
• -Bmask an optional bitmask for green
• -Amask an optional bitmask for alpha

Finally, SDL::Suface::new may be invoked with the -flags option, in a similar fashion to the -from directive. This invocation takes the same additional options as -from with the exception of -pitch which is ignored. This method returns a new, blank, SDL::Surface option with any of the following flags turned on:

• SWSURFACE() a non-accelerated surface
• HWSURFACE() a hardware accelerated surface
• SRCCOLORKEY() a surface with a transperant color
• SRCALPHA() an alpha blended, translucent surface

SDL::Surface::flags returns the flags with which the surface was initialized.

SDL::Surface::palette currently returns a SDL_Palette*, this may change in future revisions.

SDL::Surface::bpp returns the bits per pixel of the surface

SDL::Surface::bytes_per_pixel returns the bytes per pixel of the surface

SDL::Surface::Rshift returns the bit index of the red field for the surface's pixel format

SDL::Surface::Gshift returns the bit index of the green field for the surface's pixel format

SDL::Surface::Bshift returns the bit index of the blue field for the surface's pixel format

SDL::Surface::Ashift returns the bit index of the alpha field for the surface's pixel format

SDL::Surface::Rmask returns the bit mask for the red field for teh surface's pixel format

SDL::Surface::Gmask returns the bit mask for the green field for teh surface's pixel format

SDL::Surface::Bmask returns the bit mask for the blue field for teh surface's pixel format

SDL::Surface::Amask returns the bit mask for the alpha field for teh surface's pixel format

SDL::Surface::color_key returns the current color key for the image, which can be set with the SDL::Surface::set_color_key method. Before calling SDL::Surface::color_key on a image, you should fist call SDL::Surface::display_format to convert it to the same format as the display. Failure to do so will result in failure to apply the correct color_key.

SDL::Surface::alpha returns the current alpha value for the image, which can be set with the SDL::Surface::set_alpha method.

SDL::Surface::width returns the width in pixels of the surface

SDL::Surface::height returns the height in pixels of the surface

SDL::Surface::pitch returns the width of a surface's scanline in bytes

SDL::Surface::pixels returns a Uint8* to the image's pixel data. This is not inherently useful within perl, though may be used to pass image data to user provided C functions.

SDL::Surface::pixel will set the color value of the pixel at (x,y) to the given color if provided. SDL::Surface::pixel returns a SDL::Color object for the color value of the pixel at (x,y) after any possible modifications.

SDL::Surface::fill will fill the given SDL::Rect rectangle with the specified SDL::Color This function optionally takes a SDL_Rect* and a SDL_Color*

SDL::Surface::lockp returns true if the surface must be locked

SDL::Surface::lock places a hardware lock if necessary, preventing access to the surface's memory

SDL::Surface::unlock removes any hardware locks, enabling blits

SDL::Surface::update takes one or more SDL::Rect's which determine which sections of the image are to be updated. This option is only useful on the appliaction surface.

SDL::Surface::flip updates the full surface, using a double buffer if available

SDL::Surface::blit blits the current surface onto the destination surface, according to the provided rectangles. If a rectangle is 0, then the full surface is used.

SDL::Surface::set_colors updates the palette starting at index start with the supplied colors. The colors may either be SDL::Color objects or SDL_Color* from the low level C-style API.

SDL::Surface::set_color_key sets the blit flag, usually SDL_SRCCOLORKEY, to the specified SDL::Color object. Optional a SDL_Color* may be passed.

SDL::Surface::set_alpha sets the opacity of the image for alpha blits. alpha takes a value from 0x00 to 0xff.

SDL::Surface::display_format converts the surface to the same format as the current screen.

SDL::Surface::print renders the text using the current font onto the image. This option is only supported for with SDL_image and SFont.

SDL::Surface::save_bmp saves the surface to filename in Windows BMP format.

SDL::Surface::video_info returns a hash describing the current state of the video hardware.

David J. Goehrig

perl SDL::App SDL::Color SDL::Palette SDL::Rect