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) |
| flags | SDL flags for this surface. |
| 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. |
| w | Width of the surface. |
| Methods | |
| BlitSurface | Copies a surface of part of it onto another surface. |
| DisplayFormatAlpha | Enables this surface to work with source alpha transparency. |
| FillRect | Fills a rectangle with a given color. |
| GetPixel | Get a single pixel value from the surface |
| GetPixelIndex | Return the index of a pixel in the pixels array of this class |
| GetRGBA | Decomposes a given pixel value to RGBA values. |
| IsLockNeeded | Tells wether locks are needed on this surface or not. |
| LockIfNeeded | Locks a surface for deep binary access only if needed. |
| LockSurface | Locks the surface for low level byte access. |
| MapRGBA | Builds a color value from RGBA values. |
| SaveBMP | Saves a BMP files to disk. |
| SetAlpha | Sets the ALPHA settings for this surface |
| SetColors | Changes part of the color map of a palettized surface. |
| SetIcon | Sets this surface as the icon for the SDL window. |
| SetPixel | Sets a single pixel to desired value |
| UnlockIfNeeded | Unlocks a surface for deep binary access only if needed. |
| UnlockSurface | Unlocks the surface. |
Shortcut to access format.
Shortcut to access format.BytesPerPixel.
An object of class holding the clip rectangle (read only)
An object of class SDLRect holding the clip rectangle (read only)
SDL flags for this surface.
They can be a combination of the following:
instance describing the pixels in this surface.
SDLPixelFormat instance describing the pixels in this surface.
Height of the surface.
Height of the surface.
Bytes per line; see remarks on .
Bytes per line; see remarks on SDLSurface.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).
Width of the surface.
Width of the surface.
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 |
|
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).
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 |
|
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).
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 |
|
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 |
|
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.
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 |
|
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).
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. | ||
| Return | a 4 element array (Red, Green, Blue and Alpha). | ||
| Raise |
|
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.
Tells wether locks are needed on this surface or not.
SDLSurface.IsLockNeeded()
| Return | true if the user should lock this surface before accessing its binary buffers. |
Locks a surface for deep binary access only if needed.
SDLSurface.LockIfNeeded()
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.
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 |
| Return | an integer that can be directly stored as color in this image. |
It is just a shortcut to properly perfomed shifts and binary operations.
Saves a BMP files to disk.
SDLSurface.SaveBMP( filename )
| filename | the file where to store this BMP. | ||
| Raise |
|
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.
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 |
|
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.
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. |
| Return | true 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.
Sets this surface as the icon for the SDL window.
SDLSurface.SetIcon()
This function must be called before the first call to SDL.SetVideoMode.
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 |
|
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.
Unlocks a surface for deep binary access only if needed.
SDLSurface.UnlockIfNeeded()
Unlocks the surface.
SDLSurface.UnlockSurface()
Possibly, use the SDLSurface.UnlockIfNeeded Falcon specific extension.