Public Methods

Informational methods

bool valid () const
Returns true if this surface is initialized, false otherwise. Uint32 flags () const
Returns the surface flags. const PixelFormat GetPixelFormat () const
Returns the pixel format. PixelFormat GetPixelFormat ()
int w () const
Returns the width of the surface. int h () const
Returns the height of the surface. Uint16 pitch () const
Returns the scanline length in bytes. const SRect clip_rect () const
Returns the surface clip rectangle. void* pixels ()
Returns the pixel data, which can be used for low-level manipulation. const void* pixels () const
Returns the pixel data, which can be used for low-level manipulation. struct private_hwdata* hwdata () const
Returns the hardware-specific surface info.

Clipping Methods

void ResetClipRect ()
Resets the clipping rectangle for the surface. void SetClipRect (const SDL_Rect &rect)
Sets the clipping rectangle for the surface. void GetClipRect (SDL_Rect &rect) const
Gets the clipping rectangle for the surface.

Blitting / Filling

int Blit (const BaseSurface &src)
Fast blit the entire source surface onto this surface. int Blit (const BaseSurface &src, SDL_Rect &dstrect)
Fast blit the entire source surface onto this surface at the specified coordinates. int Blit (const BaseSurface &src, const SPoint &dstpoint, SDL_Rect &dstrect)
Fast blit the entire source surface onto this surface at the specified coordinates. int Blit (const BaseSurface &src, const SPoint &dstpoint)
Fast blit the entire source surface onto this surface at the specified coordinates. int Blit (const BaseSurface &src, const SDL_Rect &srcrect, SDL_Rect &dstrect)
Fast blit the specified area part of the source surface onto this surface at the specified coordinates. int Blit (const BaseSurface &src, const SDL_Rect &srcrect, const SPoint &dstpoint, SDL_Rect &dstrect)
Fast blit the specified area part of the source surface onto this surface at the specified coordinates. int Blit (const BaseSurface &src, const SDL_Rect &srcrect, const SPoint &dstpoint)
Fast blit the specified area part of the source surface onto this surface at the specified coordinates. bool Fill (Color color)
Fast fill the surface with the specified color. bool Fill (Uint8 r, Uint8 g, Uint8 b)
Fast fill the surface with the specified color. bool Fill (Uint8 r, Uint8 g, Uint8 b, Uint8 a)
Fast fill the surface with the specified color. bool FillRect (SDL_Rect &dstrect, Color color)
Performs a fast fill of the given rectangle with the specified color. bool FillRect (SDL_Rect &dstrect, Uint8 r, Uint8 g, Uint8 b)
Performs a fast fill of the given rectangle with the specified color. bool FillRect (SDL_Rect &dstrect, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
Performs a fast fill of the given rectangle with the specified color.

Protected Methods

Protected Attributes

SDLmm::BaseSurface::BaseSurface (SDL_Surface * surface) [inline, explicit, protected]

This creates a new BaseSurface object from an existing SDL_Surface. Note that ownership of the SDL_Surface is passed on to the BaseSurface. It's very important not to free the original surface since that will cause a problem when the object is destructed (SDL_Surface storage freed twice). Use with caution.

SDLmm::BaseSurface::BaseSurface (const BaseSurface & other) [inline, protected]

SDLmm::BaseSurface::~BaseSurface () [inline, virtual]

int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SDL_Rect & srcrect, const SPoint & dstpoint)

The choosen rectangle of the source surface will be blitted to this surface. If the source area is larger than the destination, clipping will occur. No scaling will be performed. Blitting should not be used on a locked surface. The entire surface will be copied to this surface using this function.

Returns:
If the blit is successful, it returns 0, otherwise it returns -1. If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost. It should be reloaded with artwork and re-blitted.

Parameters:

src

the surface to blit from.

srcrect

the rectangular area to copy from the source surface.

dstpoint

the destination coordinates.

int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SDL_Rect & srcrect, const SPoint & dstpoint, SDL_Rect & dstrect) [inline]

The choosen rectangle of the source surface will be blitted to this surface. If the source area is larger than the destination, clipping will occur. No scaling will be performed. Blitting should not be used on a locked surface. The entire surface will be copied to this surface using this function. The final blit rectangle is saved in dstrect after all clipping is performed (srcrect is not modified).

Returns:
If the blit is successful, it returns 0, otherwise it returns -1. If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost. It should be reloaded with artwork and re-blitted.

Parameters:

src

the surface to blit from.

srcrect

the rectangular area to copy from the source surface.

dstpoint

the destination coordinates.

dstrect

the final position and size is set upon returning.

int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SDL_Rect & srcrect, SDL_Rect & dstrect)

The choosen rectangle of the source surface will be blitted to this surface. If the source area is larger than the destination, clipping will occur. No scaling will be performed. Blitting should not be used on a locked surface. The entire surface will be copied to this surface using this function. The final blit rectangle is saved in dstrect after all clipping is performed (srcrect is not modified).

Returns:
If the blit is successful, it returns 0, otherwise it returns -1. If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost. It should be reloaded with artwork and re-blitted.

Parameters:

src

the surface to blit from.

srcrect

the rectangular area to copy from the source surface.

dstrect

the destination coordinates. Only the position is used (i.e width and height are ignored). The width and height are set upon returning.

int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SPoint & dstpoint)

The source surface will be blitted to this surface. If the source area is larger than the destination, clipping will occur. No scaling will be performed. Blitting should not be used on a locked surface. The entire surface will be copied to this surface using this function.

Returns:
If the blit is successful, it returns 0, otherwise it returns -1. If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost. It should be reloaded with artwork and re-blitted.

Parameters:

src

the surface to blit from.

dstpoint

the destination coordinates.

int SDLmm::BaseSurface::Blit (const BaseSurface & src, const SPoint & dstpoint, SDL_Rect & dstrect) [inline]

The source surface will be blitted to this surface. If the source area is larger than the destination, clipping will occur. No scaling will be performed. Blitting should not be used on a locked surface. The entire surface will be copied to this surface using this function. The final blit rectangle is saved in dstrect after all clipping is performed.

Returns:
If the blit is successful, it returns 0, otherwise it returns -1. If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost. It should be reloaded with artwork and re-blitted.

Parameters:

src

the surface to blit from.

dstpoint

the destination coordinates.

dstrect

the final position and size is set upon returning.

int SDLmm::BaseSurface::Blit (const BaseSurface & src, SDL_Rect & dstrect)

The source surface will be blitted to this surface. If the source area is larger than the destination, clipping will occur. No scaling will be performed. Blitting should not be used on a locked surface. The entire surface will be copied to this surface using this function. The final blit rectangle is saved in dstrect after all clipping is performed.

Returns:
If the blit is successful, it returns 0, otherwise it returns -1. If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost. It should be reloaded with artwork and re-blitted.

Parameters:

src

the surface to blit from.

dstrect

the destination coordinates. Only the position is used (i.e width and height are ignored). The width and height are set upon returning.

int SDLmm::BaseSurface::Blit (const BaseSurface & src)

The source surface will be blitted to this surface. If the source area is larger than the destination, clipping will occur. No scaling will be performed. Blitting should not be used on a locked surface. The entire surface will be copied to this surface using this function.

Returns:
If the blit is successful, it returns 0, otherwise it returns -1. If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost. It should be reloaded with artwork and re-blitted.

Parameters:

src

the surface to blit from.

bool SDLmm::BaseSurface::Fill (Uint8 r, Uint8 g, Uint8 b, Uint8 a) [inline]

If a clipping rectangle has been set using SetClipRect(), only the area within that rectangle will be filled.

Returns:
Returns true for success, false if there was an error.

Parameters:

r, g, b

the red, green and blue color values.

a

the alpha value

bool SDLmm::BaseSurface::Fill (Uint8 r, Uint8 g, Uint8 b) [inline]

If a clipping rectangle has been set using SetClipRect(), only the area within that rectangle will be filled.

Returns:
Returns true for success, false if there was an error.

Parameters:

r, g, b

the red, green and blue color values.

bool SDLmm::BaseSurface::Fill (Color color)

If a clipping rectangle has been set using SetClipRect(), only the area within that rectangle will be filled.

Returns:
Returns true for success, false if there was an error.

Parameters:

color

the color to fill with, generated by MapRGB() or MapRGBA().

bool SDLmm::BaseSurface::FillRect (SDL_Rect & dstrect, Uint8 r, Uint8 g, Uint8 b, Uint8 a) [inline]

If a clipping rectangle has been set using SetClipRect(), the area filled will be the intersection of the clipping rectangle and dstrect.

Returns:
Returns true for success, false if there was an error.

Parameters:

dstrect

the rectangle to fill, upon returning it contains the clipped rectangle that was actually filled.

r, g, b

the red, green and blue color values.

a

the alpha value

bool SDLmm::BaseSurface::FillRect (SDL_Rect & dstrect, Uint8 r, Uint8 g, Uint8 b) [inline]

If a clipping rectangle has been set using SetClipRect(), the area filled will be the intersection of the clipping rectangle and dstrect.

Returns:
Returns true for success, false if there was an error.

Parameters:

dstrect

the rectangle to fill, upon returning it contains the clipped rectangle that was actually filled.

r, g, b

the red, green and blue color values.

bool SDLmm::BaseSurface::FillRect (SDL_Rect & dstrect, Color color)

If a clipping rectangle has been set using SetClipRect(), the area filled will be the intersection of the clipping rectangle and dstrect.

Returns:
Returns true for success, false if there was an error.

Parameters:

dstrect

the rectangle to fill, upon returning it contains the clipped rectangle that was actually filled.

color

the color to fill with, generated by MapRGB() or MapRGBA().

void SDLmm::BaseSurface::GetClipRect (SDL_Rect & rect) const

Gets the clipping rectangle for a surface. When this surface is the destination of a blit, only the area within the clip rectangle is drawn into.

Parameters:

rect

reference to a rectangle which will be filled with the clipping rectangle of this surface.

See also:
SetClipRect, ResetClipRect, Blit

Color SDLmm::BaseSurface::GetPixel (const SRect & point) const [inline]

Warning:
You can only use this function when the surface is locked.

Color SDLmm::BaseSurface::GetPixel (int x, int y) const

Warning:
You can only use this function when the surface is locked.

PixelFormat SDLmm::BaseSurface::GetPixelFormat () [inline]

const PixelFormat SDLmm::BaseSurface::GetPixelFormat () const [inline]

const SDL_Surface * SDLmm::BaseSurface::GetSurface () const [inline]

SDL_Surface * SDLmm::BaseSurface::GetSurface () [inline]

bool SDLmm::BaseSurface::Lock ()

void SDLmm::BaseSurface::ResetClipRect ()

This functions resets the clipping to the full size of the surface.

See also:
GetClipRect, SetClipRect, Blit

bool SDLmm::BaseSurface::SaveBMP (const std::string & file) const [inline]

Parameters:

file

the file name to save to.

Returns:
True if the loading succeeded, false otherwise.

bool SDLmm::BaseSurface::SaveBMP (const char * file) const

Parameters:

file

the file name to save to.

Returns:
True if the loading succeeded, false otherwise.

bool SDLmm::BaseSurface::SetAlpha (Uint32 flag, Uint8 alpha)

SetAlpha is used for setting the surface alpha value and / or enabling and disabling alpha blending.

Parameters:

flag

used to specify whether alpha blending should be used (SDL_SRCALPHA) and whether the surface should use RLE acceleration for blitting (SDL_RLEACCEL). flag 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.

alpha

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.

Note:
The per-surface alpha value of 128 is considered a special case and is optimised, so it's much faster than other per-surface values.

Returns:
true for success or false if there was an error.

void SDLmm::BaseSurface::SetClipRect (const SDL_Rect & rect)

Sets the clipping rectangle for a surface. When this surface is the destination of a blit, only the area within the clip rectangle will be drawn into.

Parameters:

rect

The rectangle pointed to by rect will be clipped to the edges of the surface so that the clip rectangle for a surface can never fall outside the edges of the surface.

See also:
GetClipRect, ResetClipRect, Blit

bool SDLmm::BaseSurface::SetColorKey (Uint32 flag, Color key)

RLE acceleration can substantially speed up blitting of images with large horizontal runs of transparent pixels (i.e., pixels that match the key value). The key must be of the same pixel format as the surface, MapRGB() is often useful for obtaining an acceptable value.

Returns:
Returns true for success, false if there was an error.

Parameters:

flag

If

bool SDLmm::BaseSurface::SetDisplayFormat () [pure virtual]

This function converts the surface to the pixel format and colors of the video framebuffer, making it suitable for fast blitting onto the display surface.

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function.

Returns:
The functions returns true if the conversion succeeded or false otherwise. If the conversion failed, the BaseSurface object will not have changed.

Note:
Please note that this function doesn't return a new, modified object like the SDL_DisplayFormat() function does. Thus there is no need to manually free the old surface.

See also:
SetDisplayFormatAlpha(), SetAlpha(), SetColorKey()

Reimplemented in SDLmm::Display, and SDLmm::Surface.

bool SDLmm::BaseSurface::SetDisplayFormatAlpha () [pure virtual]

This function converts the surface to the pixel format and colors of the video framebuffer plus an alpha channel, making it suitable for fast blitting onto the display surface.

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function.

Returns:
The functions returns true if the conversion succeeded or false otherwise. If the conversion failed, the BaseSurface object will not have changed.

Note:
Please note that this function doesn't return a new, modified object like the SDL_DisplayFormatAlpha() function does. Thus there is no need to manually free the old surface.

See also:
SetDisplayFormat(), SetAlpha(), SetColorKey()

Reimplemented in SDLmm::Display, and SDLmm::Surface.

void SDLmm::BaseSurface::SetPixel (const SRect & point, Color color) [inline]

Warning:
You can only use this function when the surface is locked.

void SDLmm::BaseSurface::SetPixel (int x, int y, Color color)

Warning:
You can only use this function when the surface is locked.

void SDLmm::BaseSurface::SetPixel1 (int x, int y, Color color)

Warning:
You can only use this function when the surface is locked and when the bytes per pixel is 1.

void SDLmm::BaseSurface::SetPixel2 (int x, int y, Color color)

Warning:
You can only use this function when the surface is locked and when the bytes per pixel is 2.

void SDLmm::BaseSurface::SetPixel3 (int x, int y, Color color)

Warning:
You can only use this function when the surface is locked and when the bytes per pixel is 3.

void SDLmm::BaseSurface::SetPixel4 (int x, int y, Color color)

Warning:
You can only use this function when the surface is locked and when the bytes per pixel is 4.

void SDLmm::BaseSurface::SetSurface (SDL_Surface * surface) [inline, protected, virtual]

void SDLmm::BaseSurface::Unlock ()

const SRect SDLmm::BaseSurface::clip_rect () const [inline]

Uint32 SDLmm::BaseSurface::flags () const [inline]

int SDLmm::BaseSurface::h () const [inline]

struct private_hwdata * SDLmm::BaseSurface::hwdata () const [inline]

BaseSurface & SDLmm::BaseSurface::operator= (const BaseSurface & other) [inline, protected]

Uint16 SDLmm::BaseSurface::pitch () const [inline]

const void * SDLmm::BaseSurface::pixels () const [inline]

Warning:
You can only modify this surface when the surface is locked.

void * SDLmm::BaseSurface::pixels () [inline]

Warning:
You can only modify this surface when the surface is locked.

bool SDLmm::BaseSurface::valid () const [inline]

Warning:
Using an uninitialzied surface can cause many problems.

int SDLmm::BaseSurface::w () const [inline]

SDL_Surface * SDLmm::BaseSurface::me [protected]