Class SDLSurface[in The SDL Falcon Module.]

Encapsulates SDL_Surface structures and provides related services.

class SDLSurface

more...

Summary

Encapsulates SDL_Surface structures and provides related services.

This class is used to store SDL_Surface C structure that is widely used by SDL graphics engine. This class also provides the vast majority of the functions that operates on SDL surfaces as methods.

Falcon provides a subclass called SDLScreen that provides also screen oriented functions; SDL do not differentiates between surfaces being used to handle image buffers and surfaces used as screen handles, but Falcon embedding provides a differentiation both for OOP cleanness and to minimize memory usage (i.e. to store method pointers unneeded by the vast majority of surfaces).

Properties

bpp

Shortcut to access format

clip_rect

An object of class holding the clip rectangle (read only

flags

SDL flags for this surface.

They can be a combination of the following:

• SDL.SWSURFACE
• SDL.HWSURFACE
• SDL.ASYNCBLIT
• SDL.ANYFORMAT
• SDL.HWPALETTE
• SDL.DOUBLEBUF
• SDL.FULLSCREEN
• SDL.OPENGL
• SDL.OPENGLBLIT
• SDL.RESIZABLE
• SDL.NOFRAME
• SDL.HWACCEL
• SDL.SRCCOLORKEY
• SDL.RLEACCEL
• SDL.SRCALPHA
• SDL.PREALLOC

format

instance describing the pixels in this surface

h

Height of the surface

pitch

Bytes per line; see remarks on

pixels

MemBuf storage for pixels of this surface.

This property allows to read and write from a surface memory buffer. Each entry is already pointing to an item of the correct size to represent pixels on this surface. So, if the surface is large 640 pixels, the correct size of a line is 640 elements, regardless of the number of bytes per pixels. It is possible to retreive the count of elements for a line dividing SDLSurface.pitch by SDLSurface.bpp.

Remember to call SDLSurface.LockIfNeeded before using this property if the object may be used by another thread in your application (or if it is a shared object as a screen).

w

Width of the surface

Methods

BlitSurface()

Copies a surface of part of it onto another surface.

SDLSurface.BlitSurface( srcRect, dest, [dstRect] )

This functions copies a part of an image into another. The srcRect parameter determines which portion of the source image is copied; if nil, the whole image will be used. Only x and y coordinates from dstRect are used; if not provided, the image is copied starting at 0,0 (upper left corner).

DisplayFormatAlpha()

Enables this surface to work with source alpha transparency.

SDLSurface.DisplayFormatAlpha( srcRect, dest, [dstRect] )

This functions copies a part of an image into another. The srcRect parameter determines which portion of the source image is copied; if nil, the whole image will be used. Only x and y coordinates from dstRect are used; if not provided, the image is copied starting at 0,0 (upper left corner).

FillRect()

Fills a rectangle with a given color.

SDLSurface.FillRect( rect, color )

GetPixel()

Get a single pixel value from the surface

SDLSurface.GetPixel( x, y )

This functions gets the color of a pixel. The value is the palette index if this map has a palette, otherwise is a truecolor value whose precision depends on the mode depth.

To determine the RGBA values of this pixel, use SDLSurface.GetPixelComponents.

GetPixelIndex()

Return the index of a pixel in the pixels array of this class

SDLSurface.GetPixelIndex( x, y )

This is just a shortcut for the formula \code index = x * bpp + y * pitch \endcode

Through the direct index, it is possible to change or read directly a pixel in the pixels property of this class (which holds a correctly sized MemBuf).

GetRGBA()

Decomposes a given pixel value to RGBA values.

SDLSurface.GetRGBA( color, [retArray] )

This method is meant to determine the value of each component in a palette or truecolor value that has been read on a surface with compatible pixel format.

IsLockNeeded()

Tells wether locks are needed on this surface or not.

SDLSurface.IsLockNeeded( )

LockIfNeeded()

Locks a surface for deep binary access only if needed.

SDLSurface.LockIfNeeded( )

LockSurface()

Locks the surface for low level byte access.

SDLSurface.LockSurface( )

This allows to mangle with internal surface and format bits. An internal counter of locks is kept, and the surface is unlocked correctly at destruction, if needed.

So, it is still possible to interrupt VM and destroy it while holding locks on surfaces. However, please notice that SDL Locks are quite invasive, use them sparcely and only for the needed operations.

Possibly, use the SDLSurface.LockIfNeeded Falcon specific extension.

MapRGBA()

Builds a color value from RGBA values.

SDLSurface.MapRGBA( red, green, blue, [alpha] )

It is just a shortcut to properly perfomed shifts and binary operations.

SaveBMP()

Saves a BMP files to disk.

SDLSurface.SaveBMP( filename )

Save a memory image (or even a screenshot, if this surface is also a screen) to a disk BMP file.

The filename is totally subject to SDL rules, as it is simply passed to SDL engine. No Falcon URI parsing is perfomred before invoking SDL; as such, it is advisable to use this function only in simple applications.

SetAlpha()

Sets the ALPHA settings for this surface

SDLSurface.SetAlpha( flags, alpha )

SDL_SetAlpha is used for setting the per-surface alpha value and/or enabling and disabling alpha blending.

The flags is used to specify whether alpha blending should be used (SDL.SRCALPHA) and whether the surface should use RLE acceleration for blitting (SDL.RLEACCEL). The flags can be an OR'd combination of these two options, one of these options or 0. If SDL.SRCALPHA is not passed as a flag then all alpha information is ignored when blitting the surface.

The alpha parameter is the per-surface alpha value; a surface need not have an alpha channel to use per-surface alpha and blitting can still be accelerated with SDL_RLEACCEL.

SetColors()

Changes part of the color map of a palettized surface.

SDLSurface.SetColors( colors, firstColor )

The colors in the MemBuf are stored with red, green, blue stored respectively at smallest, medium and highest address (regardless of endianity). In other words, the first 8 bits of the color number are the red value, the next 8 bits are the green value and the next 8 bits are blue.

SetIcon()

Sets this surface as the icon for the SDL window.

SDLSurface.SetIcon( )

This function must be called before the first call to SDL.SetVideoMode.

SetPixel()

Sets a single pixel to desired value

SDLSurface.SetPixel( x, y, value )

This functions sets the color of a pixel to the desired value. The value is the palette index if this map has a palette, otherwise is a truecolor value whose precision depends on the mode depth.

To get a suitable value for this surface, use SDLSurface.GetPixel.

UnlockIfNeeded()

Unlocks a surface for deep binary access only if needed.

SDLSurface.UnlockIfNeeded( )

UnlockSurface()

Unlocks the surface.

SDLSurface.UnlockSurface( )

Possibly, use the SDLSurface.UnlockIfNeeded Falcon specific extension.