Surface operations

sge_UpdateRect
sge_Update_ON/OFF
sge_Lock_ON/OFF
sge_CreateAlphaSurface
sge_ClearSurface
sge_copy_surface
sge_BlitTransparent
sge_Blit
sge_FloodFill

Tip when you initialize the video in SDL (SDL_SetVideoMode()):

If you request SDL_SWSURFACE, then you get a video buffer allocated in system memory, and you must call SDL_UpdateRects() or SDL_Flip() to update the screen. SDL_Flip() calls SDL_UpdateRects(the-whole-screen) in this case. All allocated surfaces will be in system memory for blit speed.

If you request SDL_HWSURFACE, then if possible SDL will give you access to the actual video memory being displayed to the screen. If this is successful, the returned surface will have the SDL_HWSURFACE flag set, and you will be able to allocate other surfaces in video memory, which presumably can be blitted very fast. The disadvantage is that video memory tends to be much slower than system memory, so you don't want to write directly to it in most cases. In this case, SDL_UpdateRects() and SDL_Flip() are inexpensive noops, as you are writing to memory automatically being displayed.

If you request SDL_HWSURFACE, you may also request double-buffering by adding the SDL_DOUBLEBUF flag. If possible, SDL will set up two buffers in video memory for double-buffered page flipping. If this is successfully set up, then you will be writing to the non-visible back-buffer, and when you call SDL_Flip(), SDL will queue up a page flip for the next vertical retrace, so that the current video surface will then be displayed, and the front and back video buffers will be swapped. The next display surface lock will block until the flip has completed.

Sam Lantinga

void sge_UpdateRect(SDL_Surface *screen, Sint16 x, Sint16 y, Uint16 w, Uint16 h)
Makes sure the given rectangle is updated on the given screen. Unlike SDL_UpdateRect() this function does work even if some part of the given rectangle is outside the surface. Use SDL_UpdateRect(surface,0,0,0,0) to update the entire surface. Does not respect clipping.

void sge_Update_ON(void)
void sge_Update_OFF(void)
Most of SGE:s functions will call sge_UpdateRect() to update the destination screen when finished. But if you don't want the result to be visible directly after the call (to avoid tearing) you can turn off this automatic update feature with sge_Update_OFF(), turn it on again with sge_Update_ON(). Default is ON. You can get the current mode with 'Uint8 sge_getUpdate(void)', returns 1 if updating is on or else 0.

void sge_Lock_ON(void)
void sge_Lock_OFF(void)
Most of SGE:s functions will lock the surface if necessary, but with these functions you can control that behavior. Keep in mind that it's unwise to turn of locking and keep update on for surfaces that requires locking! Default is ON. You can get the current mode with 'Uint8 sge_getLock(void)', returns 1 if locking is on or else 0.

SDL_Surface *sge_CreateAlphaSurface(Uint32 flags, int width, int height)
Creates a 32bit alpha surface (RGBA - 8/8/8/8). The alpha channel is blended on blitting.

void sge_ClearSurface(SDL_Surface *Surface, Uint32 color)
void sge_ClearSurface(SDL_Surface *Surface, Uint8 R, Uint8 G, Uint8 B)
Clear surface to color. Does lock and update the surface.

SDL_Surface *sge_copy_surface(SDL_Surface *src)
Copies a surface to a new.

int sge_BlitTransparent(SDL_Surface *Src, SDL_Surface *Dest, Sint16 SrcX, Sint16 SrcY, Sint16 DestX, Sint16 DestY, Sint16 W, Sint16 H, Uint32 Clear, Uint8 Alpha)
This performs a blit from the source surface to the destination surface. Clear is the color key (transparent pixel) in the source surface. Alpha sets the transparency of the source surface (0-255). Note that the original alpha and color key is lost on the source surface. Only use this function if the surface will be blitted once, in other cases set the alpha and color key and use sge_Blit(). Does respect clipping on destination surface. Returns 0 on success.

int sge_Blit(SDL_Surface *Src, SDL_Surface *Dest, Sint16 SrcX, Sint16 SrcY, Sint16 DestX, Sint16 DestY, Sint16 W, Sint16 H)
This performs a blit from the source surface to the destination surface, without touching color key or alpha. Does respect clipping on destination surface. Returns 0 on success.

void sge_FloodFill(SDL_Surface *dst, Sint16 x, Sint16 y, Uint32 color)
void sge_FloodFill(SDL_Surface *dst, Sint16 x, Sint16 y, Uint8 R, Uint8 G, Uint8 B)
Flood fills (with the specified color) all areas that connects to and has the same color as the point (x,y). Use with care! Does respect clipping but doesn't update the surface.