18.13Class SDLSurface

Encapsulates SDL_Surface structures and provides related services.

Class SDLSurface

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)
flagsSDL flags for this surface.
format instance describing the pixels in this surface.
h Height of the surface.
pitch Bytes per line; see remarks on .
pixelsMemBuf storage for pixels of this surface.
w Width of the surface.
Methods
BlitSurfaceCopies a surface of part of it onto another surface.
DisplayFormatAlphaEnables this surface to work with source alpha transparency.
FillRectFills a rectangle with a given color.
GetPixelGet a single pixel value from the surface
GetPixelIndexReturn the index of a pixel in the pixels array of this class
GetRGBADecomposes a given pixel value to RGBA values.
IsLockNeededTells wether locks are needed on this surface or not.
LockIfNeededLocks a surface for deep binary access only if needed.
LockSurfaceLocks the surface for low level byte access.
MapRGBABuilds a color value from RGBA values.
SaveBMPSaves a BMP files to disk.
SetAlphaSets the ALPHA settings for this surface
SetColorsChanges part of the color map of a palettized surface.
SetIconSets this surface as the icon for the SDL window.
SetPixelSets a single pixel to desired value
UnlockIfNeededUnlocks a surface for deep binary access only if needed.
UnlockSurfaceUnlocks the surface.

Properties

bpp

Shortcut to access format.

Shortcut to access format.BytesPerPixel.

clip_rect

An object of class holding the clip rectangle (read only)

An object of class SDLRect holding the clip rectangle (read only)

flags

SDL flags for this surface.

They can be a combination of the following:

format

instance describing the pixels in this surface.

SDLPixelFormat instance describing the pixels in this surface.

h

Height of the surface.

Height of the surface.

pitch

Bytes per line; see remarks on .

Bytes per line; see remarks on SDLSurface.pixels.

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.

Width of the surface.

Methods

BlitSurface

Copies a surface of part of it onto another surface.

SDLSurface.BlitSurface( srcRect, dest, [dstRect] )
srcRect a SDLRect containing the source coordinates or nil.
dest the destionation SDLSurface.
dstRect a SDLRect containing destination coordinates or nil.
Raise
SDLError on copy failure.

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] )
srcRect a SDLRect containing the source coordinates or nil.
dest the destionation SDLSurface.
dstRect a SDLRect containing destination coordinates or nil.
Raise
SDLError on copy failure.

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 )
rect an SDLRect instance containing the coordinates to fill, or nil to fill all
color a color value to be used in fills.
Raise
SDLError on error

GetPixel

Get a single pixel value from the surface

SDLSurface.GetPixel( x, y )
x X coordinates of the pixel to be retreived
y Y coordinates of the pixel to be retreived
Raise
ParamError if x or y are out of range

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 )
x X coordinates of the desired pixel position
y Y coordinates of the desired pixel position
Raise
ParamError if x or y are out of range

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] )
color multibyte value of a color
retArray An array that is used to store the desired values.
Returna 4 element array (Red, Green, Blue and Alpha).
Raise
ParamError if color is out of index in palette based images

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()
Returntrue if the user should lock this surface before accessing its binary buffers.

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] )
red Red component of the final color
green Green component of the final color
blue Blue component of the final color
alpha Alpha component of the final color
Returnan integer that can be directly stored as color in this image.

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

SaveBMP

Saves a BMP files to disk.

SDLSurface.SaveBMP( filename )
filename the file where to store this BMP.
Raise
SDLError on failure.

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.

See also: SDL.

SetAlpha

Sets the ALPHA settings for this surface

SDLSurface.SetAlpha( flags, alpha )
flags ALPHA composition flags.
alpha A value between 0 (transparent) and 255 (opaque)
Raise
SDLError on error.

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 )
colors A 4 bytes per entry MemBuf containing the color data.
firstColor An integer specifying the first color of the palette.
Returntrue if the palette could be changed, 0 if the image has no palette or if the color map was too wide to fit the image palette.

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 )
x X coordinates of the pixel to be set
y Y coordinates of the pixel to be set
value The value to be set
Raise
ParamError if x or y are out of ranges

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.

Made with http://www.falconpl.org