Video | Events | Audio | CD-ROM | Threads |
Introduction | Function List | Function Reference | Examples |
This function returns a read-only pointer to information about the
video hardware. If this is called before
Return a pointer to an array of available screen dimensions for the
given format and video flags, sorted largest to smallest. Returns
Check to see if a particular video mode is supported.
The arguments to
Set up a video mode with the specified width, height and bits-per-pixel.
Makes sure the given list of rectangles is updated on the given screen.
On hardware that supports double-buffering, this function sets up a flip
and returns. The hardware will wait for vertical retrace, and then swap
video buffers before the next video surface blit or lock will return.
On hardware that doesn not support double-buffering, this is equivalent
to calling
Sets a portion of the colormap for the given 8-bit surface. If
'
Note that when you change the palette of a surface, you have to redo
any mapping you had previously set with
When '
Maps an RGB value to a 32-bit pixel for a given pixel format
Allocate and free a SDL surface (must be called after SDL_SetVideoMode)
Load a surface from a named Windows BMP file.
Save a surface to the named Windows BMP file.
Sets the color key (transparent pixel) in a blittable surface.
If '
Sets the clipping rectangle for the source surface in a blit.
If the destination rectangle falls outside this rectangle, the source
surface will be clipped so the blit doesn't write outside the clipping
rectangle.
Maps a source surface to a destination surface format/colormap.
This mapping must be done before calling
Creates a new surface of the specified format, and then copies and maps
the given surface to it so the blit of the converted surface will be as
fast as possible. If this function fails, it returns
This performs a fast blit from the source surface to the destination
surface.
This function performs a fast fill of the given rectangle with
'
This function takes a surface and copies it to a new surface of the
pixel format and colors of the video framebuffer, suitable for fast
blitting onto the display surface. It calls
This should never be necessary, but is included for completeness,
and is used internally.
Sets/Gets the title-bar of the display window, if any.
Sets the icon for the display window.
Cursors created with this function must be freed with
Create a color cursor using the specified surface image.
If this function succeeds, it returns the new cursor, otherwise it returns
Cursors created with this function must be freed with
Set the currently active cursor to the specified one.
Returns the currently active cursor.
Deallocates a cursor created with
Toggle whether or not the cursor is shown on the screen.
extern const
SDL_VideoInfo
*SDL_GetVideoInfo(void);
SDL_SetVideoMode()
, the
'vfmt
' member of the returned structure will
contain the pixel format of the "best" video mode.
extern SDL_Rect **SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
NULL
if there are no dimensions available for a particular
format, or
If 'format
' is NULL
, the mode list will be
for the format returned by
SDL_GetPixelFormat()
extern int SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
It returns 0
if the requested mode is not supported under
any bit depth, or returns the bits-per-pixel of the closest available
mode with the given width and height. If this bits-per-pixel is different
from the one used when setting the video mode,
SDL_SetVideoMode()
will succeed,
but will emulate the requested bits-per-pixel with a shadow surface.
SDL_VideoModeOK()
are the same ones you
would pass to SDL_SetVideoMode()
extern SDL_Surface *SDL_SetVideoMode(int width, int height, int bpp,
Uint32 flags);
If 'bpp
' is 0
, it is treated as the
current display bits per pixel.
If SDL_ANYFORMAT
is set in 'flags
',
the SDL library will try to set the requested bits-per-pixel, but will
return whatever video pixel format is available. The default is to
emulate the requested pixel format if it is not natively available.
If SDL_HWSURFACE
is set in 'flags
',
the video surface will be placed in video memory, if possible, and you
may have to call SDL_LockSurface()
in order to access the raw framebuffer. Otherwise, the video surface
will be created in system memory.
If SDL_HWPALETTE
is set in 'flags
', the
SDL library will guarantee that the colors set by
SDL_SetColors()
will be the
colors you get. Otherwise, in 8-bit mode,
SDL_SetColors()
may not be able
to set all of the colors exactly the way they are requested, and you should
look at the video surface structure to determine the actual palette.
If SDL cannot guarantee that the colors you request can be set,
i.e. if the colormap is shared, then the video surface may be created
under emulation in system memory, overriding the SDL_HWSURFACE
flag.
If SDL_FULLSCREEN
is set in 'flags
', the
SDL library will try to set a fullscreen video mode. The default is to
create a windowed mode if the current graphics system has a window manager.
If the SDL library is able to set a fullscreen video mode, this flag will
be set in the surface that is returned.
If SDL_DOUBLEBUF
is set in 'flags
', the
SDL library will try to set up two surfaces in video memory and swap
between them when you call SDL_Flip()
.
This is usually slower than the normal single-buffering scheme, but
prevents "tearing" artifacts caused by modifying video memory while
the monitor is refreshing. It should only be used by applications that
redraw the entire screen on every update.
This function returns the frambuffer surface, or NULL
if it fails.
extern void SDL_UpdateRects(SDL_Surface *screen, int numrects, SDL_Rect *rects);
extern void SDL_UpdateRect(SDL_Surface *screen,
Sint32 x, Sint32 y, Uint32 w, Uint32 h);
If 'x
', 'y
', 'w
'
and 'h
' are all 0
,
SDL_UpdateRect()
will update the
entire screen.
These functions should not be called while 'screen
' is
locked.
extern int SDL_Flip(SDL_Surface *screen);
SDL_UpdateRect
(screen, 0, 0, 0, 0)
The SDL_DOUBLEBUF
flag must have been passed to
SDL_SetVideoMode()
when
setting the video mode for this function to perform hardware flipping.
This function returns 0
if successful, or -1
if
there was an error.
extern int SDL_SetColors(SDL_Surface *surface,
SDL_Color *colors, int firstcolor, int ncolors);
surface
' is not a palettized surface, this function
does nothing, returning 0
.
If all of the colors were set as passed to SDL_SetColors()
,
it will return 1
. If not all the color entries were set
exactly as given, it will return 0
, and you should look at
the surface palette to determine the actual color palette.
SDL_MapSurface()
.
surface
' is the surface associated with the
current display, the display colormap will be updated with the requested
colors. If SDL_HWPALETTE
was set in
SDL_SetVideoMode()
flags,
SDL_SetColors()
will always return 1
, and the
palette is guaranteed to be set the way you desire, even if the window
colormap has to be warped or run under emulation.
extern Uint32 SDL_MapRGB(SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b);
extern SDL_Surface *SDL_AllocSurface
(Uint32 flags, int width, int height, int depth,
Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
extern void SDL_FreeSurface(SDL_Surface *surface);
If 'depth
' is 4 or 8 bits, an empty palette is allocated for the surface.
If 'depth
' is greater than 8 bits, the pixel format is
set using the flags '[RGB]mask
'.
The 'flags
' tell what kind of surface to create.
SDL_SWSURFACE
means that the surface should be created in system memory.
SDL_HWSURFACE
means that the surface should be created in
video memory, with the same format as the display surface. This is useful
for surfaces that will not change much, to take advantage of hardware
acceleration when being blitted to the display surface.
SDL_SRCCOLORKEY
means that the surface will be used for
colorkey blits and if the hardware supports hardware acceleration of
colorkey blits between two surfaces in video memory, to place the surface
in video memory if possible, otherwise it will be placed in system memory.
SDL_SRCALPHA
means that the surface will be used for alpha
blits and if the hardware supports hardware acceleration of alpha blits
between two surfaces in video memory, to place the surface in video memory
if possible, otherwise it will be placed in system memory.
SDL_SRCCOLORKEY
and SDL_SRCALPHA
will only be
honored if the display surface is in video video memory (the surface
returned by SDL_SetVideoMode()
has the SDL_HWSURFACE
flag set.)
If the function runs out of memory, it will return NULL
.
extern int SDL_LockSurface(SDL_Surface *surface);
extern void SDL_UnlockSurface(SDL_Surface *surface);
SDL_LockSurface()
sets up a surface for directly accessing
the pixels. Between calls to SDL_LockSurface()
/
SDL_UnlockSurface()
, you can write to and read from
'surface->pixels
', using the pixel format stored in
'surface->format
'. Once you are done accessing the
surface, you should use SDL_UnlockSurface()
to release it.
Not all surfaces require locking. If SDL_MUSTLOCK(surface)
evaluates to 0
, then you can read and write to the surface
at any time, and the pixel format of the surface will not change. In
particular, if the SDL_HWSURFACE
flag is not given when
calling SDL_SetVideoMode(), you will not need to lock the display surface
before accessing it.
No operating system or library calls should be made between lock/unlock
pairs, as critical system locks may be held during this time.
SDL_LockSurface()
returns 0
, or -1
if the surface couldn't be locked.
extern SDL_Surface *SDL_LoadBMP(const char *file);
Returns the new surface, or NULL
if there was an error.
The new surface should be freed with
SDL_FreeSurface()
.
extern int SDL_SaveBMP(SDL_Surface *surface, const char *file);
Returns 0
if successful or -1
if there was an error.
extern int SDL_SetColorKey(SDL_Surface *surface, Uint32 flag, Uint32 key);
If 'flag
' is SDL_SRCCOLORKEY
(optionally
OR'd with SDL_RLEACCEL
), the 'key
' is
the transparent pixel in the source image of a blit.
If 'flag
' is 0
, this function clears
any current color key.
This function returns 0
, or -1
if there was an error.
extern int SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
alpha
' is non-zero, this function sets the alpha
value for the entire surface, as opposed to using the alpha component of
each pixel. This value measures the range of transparency of the surface,
0
being completely opaque to 255
being completely
transparent.
If 'flag
' is 0
, alpha blending is disabled
for the surface.
If 'flag
' is SDL_SRCALPHA
, alpha blending
is enabled for the surface.
If 'flag
' is (SDL_SRCALPHA|SDL_MULACCEL)
,
alpha blending is enabled with alpha pre-multiplication enabled.
Alpha blend premultiplication is an optimization that cuts the actual
alpha blend operation in half. There are a couple of drawbacks however.
It slightly reduces the accuracy of the blending operation.
You must lock and unlock the surface to access it, and each lock and
unlock operation reduces the color accuracy of the unchanged pixels.
The best use of this optimization is on surfaces that will be loaded
once and then be static most of the time they are in use.
extern void SDL_SetClipping(SDL_Surface *surface,
int top, int left, int bottom, int right);
If the clip rectangle is { 0, 0, 0, 0 }, clipping will be disabled.
Note that blits are automatically clipped to the edges of the source
and destination surfaces.
extern int SDL_MapSurface(SDL_Surface *src, SDL_PixelFormat *dstfmt);
SDL_BlitSurface()
, and
should be re-done if the destination surface format or colormap changes.
SDL_MapSurface()
returns
0
, or
-1
on failure.
extern SDL_Surface *SDL_ConvertSurface(SDL_Surface *src, SDL_PixelFormat *fmt,
Uint32 flags);
NULL
.
The 'flags
' parameter is passed to
SDL_AllocSurface()
and has those
semantics.
This function is used internally by
SDL_DisplayFormat()
.
extern int SDL_BlitSurface(SDL_Surface *src, SDL_Rect *srcrect,
SDL_Surface *dst, SDL_Rect *dstrect);
It assumes that the source surface has already been mapped to the
destination with SDL_MapSurface()
,
and the source and destination rectangles are the same size. If either
'srcrect
' or 'dstrect
' are
NULL
, the entire surface (src or dst) is copied. The final
blit rectangles are saved in 'srcrect
' and
'dstrect
' after all clipping is performed.
If the blit is successful, it returns 0
, otherwise it returns
-1
.
The blit function should not be called on a locked surface.
If either of the surfaces were in video memory, and the blit returns -2,
the video memory was lost, so it should be reloaded with artwork and
re-blitted:
This happens under DirectX 5.0 when the system switches away from your
fullscreen application. Locking the surface will also fail until you
have access to the video memory again.
while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
while ( SDL_LockSurface(image)) < 0 )
Sleep(10);
-- Write image pixels to image->pixels --
SDL_UnlockSurface(image);
}
extern int SDL_FillRect(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
color
'. If 'dstrect
' is
NULL
, the whole surface will be filled with
'color
'
The color should be a pixel of the format used by the surface, and
can be generated by the SDL_MapRGB()
function.
This function returns 0
on success, or -1
on error.
extern SDL_Surface *SDL_DisplayFormat(SDL_Surface *surface);
SDL_ConvertSurface()
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.
If the conversion fails or runs out of memory, it returns NULL
extern void SDL_UnmapSurface(SDL_Surface *src);
extern void SDL_WM_SetCaption(const char *title, const char *icon);
extern void SDL_WM_GetCaption(char **title, char **icon);
extern void SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
This function must be called before the first call to SDL_SetVideoMode().
It takes an icon surface, and a mask in MSB format.
If 'mask
' is NULL
, the entire icon surface
will be used as the icon.
data mask resulting pixel on screen
0 1 White
1 1 Black
0 0 Transparent
1 0 Inverted color if possible, black if not.
SDL_FreeCursor()
.
extern SDL_Cursor *SDL_CreateColorCursor(SDL_Surface *surface,
int hot_x, int hot_y);
NULL
.
SDL_FreeCursor()
.
extern void SDL_SetCursor(SDL_Cursor *cursor);
If the cursor is currently visible, the change will be immediately
represented on the display.
extern SDL_Cursor *SDL_GetCursor(void);
extern void SDL_FreeCursor(SDL_Cursor *cursor);
SDL_CreateCursor()
.
extern int SDL_ShowCursor(int toggle);
The cursor start off displayed, but can be turned off.
SDL_ShowCursor()
returns
1
if the cursor was being displayed before the call, or
0
if it was not.
Structure definitions:
typedef struct {
Sint16 x, y;
Uint16 w, h;
} SDL_Rect;
typedef struct {
Uint8 r;
Uint8 g;
Uint8 b;
Uint8 unused;
} SDL_Color;
typedef struct {
int ncolors;
SDL_Color *colors;
} SDL_Palette;
typedef struct SDL_PixelFormat {
SDL_Palette *palette;
Uint8 BitsPerPixel;
Uint8 BytesPerPixel;
Uint8 Rloss;
Uint8 Gloss;
Uint8 Bloss;
Uint8 Aloss;
Uint8 Rshift;
Uint8 Gshift;
Uint8 Bshift;
Uint8 Ashift;
Uint32 Rmask;
Uint32 Gmask;
Uint32 Bmask;
Uint32 Amask;
/* RGB color key information */
Uint32 colorkey;
/* Alpha value information (per-surface alpha) */
Uint8 alpha;
} SDL_PixelFormat;
/* This structure should be treated as read-only, except for 'pixels',
which, if not NULL, contains the raw pixel data for the surface.
*/
typedef struct SDL_Surface {
Uint32 flags; /* Read-only */
SDL_PixelFormat *format; /* Read-only */
int w, h; /* Read-only */
Uint16 pitch; /* Read-only */
void *pixels; /* Read-write */
int offset; /* Private */
/* Thread-safe surface lock */
int locked; /* Read-only */
SDL_mutex *mutex; /* Private */
/* clipping information */
int clip_minx; /* Read-only */
int clip_maxx; /* Read-only */
int clip_miny; /* Read-only */
int clip_maxy; /* Read-only */
/* info for fast blit mapping to other surfaces */
int identity; /* Private */
SDL_PixelFormat *dstfmt; /* Private */
SDL_blit hw_blit; /* Private */
SDL_blit sw_blit; /* Private */
Uint8 *palmap; /* Private */
struct private_hwdata *hwaccel_data; /* Private */
struct private_swdata *swaccel_data; /* Private */
/* Reference count -- used when freeing surface */
int refcount; /* Read-mostly */
} SDL_Surface;
/* These are the currently supported flags for the SDL_surface */
/* Available for SDL_AllocSurface() or SDL_SetVideoMode() */
#define SDL_SWSURFACE 0x00000000 /* Surface is in system memory */
#define SDL_HWSURFACE 0x00000001 /* Surface is in video memory */
#define SDL_THREADSAFE 0x00000010 /* SDL_LockSurface exclusively locks */
/* Available for SDL_SetVideoMode() */
#define SDL_ANYFORMAT 0x10000000 /* Allow any video pixel format */
#define SDL_HWPALETTE 0x00000002 /* Surface has exclusive palette */
#define SDL_DOUBLEBUF 0x40000000 /* Surface has exclusive palette */
#define SDL_FULLSCREEN 0x80000000 /* Surface is a full screen display */
/* Useful for determining the video hardware capabilities */
typedef struct {
Uint8 hw_available :1; /* Flag: Can you create hardware surfaces? */
Uint8 wm_available :1; /* Flag: Can you talk to a window manager? */
Uint8 UnusedBits1 :6;
Uint8 blit_endian :1; /* Value: 0 for LSB, 1 for MSB */
Uint8 blit_hw :1; /* Flag: Accelerated blits HW --> HW */
Uint8 blit_hw_CC :1; /* Flag: Accelerated blits with Colorkey */
Uint8 blit_hw_A :1; /* Flag: Accelerated blits with Alpha */
Uint8 blit_sw :1; /* Flag: Accelerated blits SW --> HW */
Uint8 blit_sw_CC :1; /* Flag: Accelerated blits with Colorkey */
Uint8 blit_sw_A :1; /* Flag: Accelerated blits with Alpha */
Uint8 blit_fill :1; /* Flag: Accelerated color fill */
Uint8 UnusedByte1;
Uint8 UnusedByte2;
Uint32 video_mem; /* The total amount of video memory (in K) */
SDL_PixelFormat *vfmt; /* Value: The format of the video surface */
} SDL_VideoInfo;
typedef struct WMcursor WMcursor; /* Implementation dependent */
typedef struct {
int remap; /* Does the cursor need remapping? */
Sint16 hot_x, hot_y; /* The "tip" of the cursor */
SDL_Surface *sw_cursor; /* Software cursor surface */
SDL_Surface *sw_erased; /* Area behind cursor surface */
WMcursor *wm_cursor; /* Window-manager cursor */
} SDL_Cursor;