SDL::Surface

NAME

SDL::Surface - a SDL perl extension

SYNOPSIS

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

DESCRIPTION

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.

EXPORTS

        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

METHODS

new (-name => 'foo.png')

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

new (-from => $buffer, ... )

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

new ( -flags => SDL_SWSURFACE, ... )

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

flags ()

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

palette ()

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

bpp ()

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

bytes_per_pixel ()

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

Rshift ()

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

Gshift ()

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

Bshift ()

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

Ashift ()

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

Rmask ()

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

Gmask ()

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

Bmask ()

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

Amask ()

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

color_key ()

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

alpha ()

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

width ()

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

height ()

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

pitch ()

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

pixels ()

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

pixel (x,y,[color])

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

fill (rect,color)

"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*

lockp ()

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

lock ()

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

unlock ()

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

update ( rects...)

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

flip ()

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

blit (srect,dest,drect)

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

set_colors (start,colors...)

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

set_color_key (flag,pixel) or (flag,x,y)

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

set_alpha (flag,alpha)

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

display_format ()

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

rgb () SDL::Surface::rgb converts the surface to a 24 bit rgb format regardless of the initial format.

rgba () SDL::Surface::rgba converts the surface to a 32 bit rgba format regarless of the initial format.

print (x,y,text...)

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

save_bmp (filename)

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

video_info ()

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

AUTHOR

David J. Goehrig

Index

NAME
SYNOPSIS
DESCRIPTION
EXPORTS
METHODS
new (-name => 'foo.png')
new (-from => $buffer, ... )
new ( -flags => SDL_SWSURFACE, ... )
flags ()
palette ()
bpp ()
bytes_per_pixel ()
Rshift ()
Gshift ()
Bshift ()
Ashift ()
Rmask ()
Gmask ()
Bmask ()
Amask ()
color_key ()
alpha ()
width ()
height ()
pitch ()
pixels ()
pixel (x,y,[color])
fill (rect,color)
lockp ()
lock ()
unlock ()
update ( rects...)
flip ()
blit (srect,dest,drect)
set_colors (start,colors...)
set_color_key (flag,pixel) or (flag,x,y)
set_alpha (flag,alpha)
display_format ()
rgb () SDL::Surface::rgb converts the surface to a 24 bit rgb format regardless of the initial format.
rgba () SDL::Surface::rgba converts the surface to a 32 bit rgba format regarless of the initial format.
print (x,y,text...)
save_bmp (filename)
video_info ()
AUTHOR
SEE ALSO