SDL Library
SDL_surface.h File Reference
Header file for SDL_Surface definition and management functions. More...
Go to the source code of this file.
Data Structures | |
struct | SDL_Surface |
A collection of pixels used in software blitting. More... | |
Typedefs | |
typedef struct SDL_Surface | SDL_Surface |
A collection of pixels used in software blitting. | |
typedef int(* | SDL_blit )(struct SDL_Surface *src, SDL_Rect *srcrect, struct SDL_Surface *dst, SDL_Rect *dstrect) |
The type of function used for surface blitting functions. | |
Functions | |
DECLSPEC SDL_Surface *SDLCALL | SDL_CreateRGBSurface (Uint32 flags, int width, int height, int depth, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask) |
Allocate and free an RGB surface. | |
DECLSPEC int SDLCALL | SDL_SetSurfacePalette (SDL_Surface *surface, SDL_Palette *palette) |
Set the palette used by a surface. | |
DECLSPEC int SDLCALL | SDL_LockSurface (SDL_Surface *surface) |
Sets up a surface for directly accessing the pixels. | |
DECLSPEC void SDLCALL | SDL_UnlockSurface (SDL_Surface *surface) |
DECLSPEC SDL_Surface *SDLCALL | SDL_LoadBMP_RW (SDL_RWops *src, int freesrc) |
Load a surface from a seekable SDL data stream (memory or file). | |
DECLSPEC int SDLCALL | SDL_SaveBMP_RW (SDL_Surface *surface, SDL_RWops *dst, int freedst) |
Save a surface to a seekable SDL data stream (memory or file). | |
DECLSPEC int SDLCALL | SDL_SetSurfaceRLE (SDL_Surface *surface, int flag) |
Sets the RLE acceleration hint for a surface. | |
DECLSPEC int SDLCALL | SDL_SetColorKey (SDL_Surface *surface, int flag, Uint32 key) |
Sets the color key (transparent pixel) in a blittable surface. | |
DECLSPEC int SDLCALL | SDL_GetColorKey (SDL_Surface *surface, Uint32 *key) |
Gets the color key (transparent pixel) in a blittable surface. | |
DECLSPEC int SDLCALL | SDL_SetSurfaceColorMod (SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b) |
Set an additional color value used in blit operations. | |
DECLSPEC int SDLCALL | SDL_GetSurfaceColorMod (SDL_Surface *surface, Uint8 *r, Uint8 *g, Uint8 *b) |
Get the additional color value used in blit operations. | |
DECLSPEC int SDLCALL | SDL_SetSurfaceAlphaMod (SDL_Surface *surface, Uint8 alpha) |
Set an additional alpha value used in blit operations. | |
DECLSPEC int SDLCALL | SDL_GetSurfaceAlphaMod (SDL_Surface *surface, Uint8 *alpha) |
Get the additional alpha value used in blit operations. | |
DECLSPEC int SDLCALL | SDL_SetSurfaceBlendMode (SDL_Surface *surface, SDL_BlendMode blendMode) |
Set the blend mode used for blit operations. | |
DECLSPEC int SDLCALL | SDL_GetSurfaceBlendMode (SDL_Surface *surface, SDL_BlendMode *blendMode) |
Get the blend mode used for blit operations. | |
DECLSPEC SDL_bool SDLCALL | SDL_SetClipRect (SDL_Surface *surface, const SDL_Rect *rect) |
Sets the clipping rectangle for the destination surface in a blit. | |
DECLSPEC void SDLCALL | SDL_GetClipRect (SDL_Surface *surface, SDL_Rect *rect) |
Gets the clipping rectangle for the destination surface in a blit. | |
DECLSPEC SDL_Surface *SDLCALL | SDL_ConvertSurface (SDL_Surface *src, const SDL_PixelFormat *fmt, Uint32 flags) |
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. | |
DECLSPEC int SDLCALL | SDL_ConvertPixels (int width, int height, Uint32 src_format, const void *src, int src_pitch, Uint32 dst_format, void *dst, int dst_pitch) |
Copy a block of pixels of one format to another format. | |
DECLSPEC int SDLCALL | SDL_FillRect (SDL_Surface *dst, const SDL_Rect *rect, Uint32 color) |
Performs a fast fill of the given rectangle with color . | |
DECLSPEC int SDLCALL | SDL_UpperBlit (SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect) |
This is the public blit function, SDL_BlitSurface(), and it performs rectangle validation and clipping before passing it to SDL_LowerBlit() | |
DECLSPEC int SDLCALL | SDL_LowerBlit (SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect) |
This is a semi-private blit function and it performs low-level surface blitting only. | |
DECLSPEC int SDLCALL | SDL_SoftStretch (SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect) |
Perform a fast, low quality, stretch blit between two surfaces of the same pixel format. | |
DECLSPEC int SDLCALL | SDL_UpperBlitScaled (SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect) |
This is the public scaled blit function, SDL_BlitScaled(), and it performs rectangle validation and clipping before passing it to SDL_LowerBlitScaled() | |
DECLSPEC int SDLCALL | SDL_LowerBlitScaled (SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect) |
This is a semi-private blit function and it performs low-level surface scaled blitting only. |
Detailed Description
Header file for SDL_Surface definition and management functions.
Definition in file SDL_surface.h.
Typedef Documentation
typedef int(* SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect, struct SDL_Surface *dst, SDL_Rect *dstrect) |
The type of function used for surface blitting functions.
Definition at line 97 of file SDL_surface.h.
typedef struct SDL_Surface SDL_Surface |
A collection of pixels used in software blitting.
- Note:
- This structure should be treated as read-only, except for
pixels
, which, if not NULL, contains the raw pixel data for the surface.
Function Documentation
DECLSPEC int SDLCALL SDL_ConvertPixels | ( | int | width, |
int | height, | ||
Uint32 | src_format, | ||
const void * | src, | ||
int | src_pitch, | ||
Uint32 | dst_format, | ||
void * | dst, | ||
int | dst_pitch | ||
) |
Copy a block of pixels of one format to another format.
- Returns:
- 0 on success, or -1 if there was an error
DECLSPEC SDL_Surface* SDLCALL SDL_ConvertSurface | ( | SDL_Surface * | src, |
const SDL_PixelFormat * | fmt, | ||
Uint32 | flags | ||
) |
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 NULL.
The flags
parameter is passed to SDL_CreateRGBSurface() and has those semantics. You can also pass SDL_RLEACCEL in the flags parameter and SDL will try to RLE accelerate colorkey and alpha blits in the resulting surface.
DECLSPEC SDL_Surface* SDLCALL SDL_CreateRGBSurface | ( | Uint32 | flags, |
int | width, | ||
int | height, | ||
int | depth, | ||
Uint32 | Rmask, | ||
Uint32 | Gmask, | ||
Uint32 | Bmask, | ||
Uint32 | Amask | ||
) |
Allocate and free an RGB surface.
If the depth is 4 or 8 bits, an empty palette is allocated for the surface. If the depth is greater than 8 bits, the pixel format is set using the flags '[RGB]mask'.
If the function runs out of memory, it will return NULL.
- Parameters:
-
flags The flags
are obsolete and should be set to 0.width The width in pixels of the surface to create. height The height in pixels of the surface to create. depth The depth in bits of the surface to create. Rmask The red mask of the surface to create. Gmask The green mask of the surface to create. Bmask The blue mask of the surface to create. Amask The alpha mask of the surface to create.
DECLSPEC int SDLCALL SDL_FillRect | ( | SDL_Surface * | dst, |
const SDL_Rect * | rect, | ||
Uint32 | color | ||
) |
Performs a fast fill of the given rectangle with color
.
If rect
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.
- Returns:
- 0 on success, or -1 on error.
DECLSPEC void SDLCALL SDL_GetClipRect | ( | SDL_Surface * | surface, |
SDL_Rect * | rect | ||
) |
Gets the clipping rectangle for the destination surface in a blit.
rect
must be a pointer to a valid rectangle which will be filled with the correct values.
DECLSPEC int SDLCALL SDL_GetColorKey | ( | SDL_Surface * | surface, |
Uint32 * | key | ||
) |
Gets the color key (transparent pixel) in a blittable surface.
- Parameters:
-
surface The surface to update key A pointer filled in with the transparent pixel in the native surface format
- Returns:
- 0 on success, or -1 if the surface is not valid or colorkey is not enabled.
DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod | ( | SDL_Surface * | surface, |
Uint8 * | alpha | ||
) |
Get the additional alpha value used in blit operations.
- Parameters:
-
surface The surface to query. alpha A pointer filled in with the current alpha value.
- Returns:
- 0 on success, or -1 if the surface is not valid.
- See also:
- SDL_SetSurfaceAlphaMod()
DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode | ( | SDL_Surface * | surface, |
SDL_BlendMode * | blendMode | ||
) |
Get the blend mode used for blit operations.
- Parameters:
-
surface The surface to query. blendMode A pointer filled in with the current blend mode.
- Returns:
- 0 on success, or -1 if the surface is not valid.
- See also:
- SDL_SetSurfaceBlendMode()
DECLSPEC int SDLCALL SDL_GetSurfaceColorMod | ( | SDL_Surface * | surface, |
Uint8 * | r, | ||
Uint8 * | g, | ||
Uint8 * | b | ||
) |
Get the additional color value used in blit operations.
- Parameters:
-
surface The surface to query. r A pointer filled in with the current red color value. g A pointer filled in with the current green color value. b A pointer filled in with the current blue color value.
- Returns:
- 0 on success, or -1 if the surface is not valid.
- See also:
- SDL_SetSurfaceColorMod()
DECLSPEC SDL_Surface* SDLCALL SDL_LoadBMP_RW | ( | SDL_RWops * | src, |
int | freesrc | ||
) |
Load a surface from a seekable SDL data stream (memory or file).
If freesrc
is non-zero, the stream will be closed after being read.
The new surface should be freed with SDL_FreeSurface().
- Returns:
- the new surface, or NULL if there was an error.
DECLSPEC int SDLCALL SDL_LockSurface | ( | SDL_Surface * | surface ) |
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.
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.
- See also:
- SDL_UnlockSurface()
DECLSPEC int SDLCALL SDL_LowerBlit | ( | SDL_Surface * | src, |
SDL_Rect * | srcrect, | ||
SDL_Surface * | dst, | ||
SDL_Rect * | dstrect | ||
) |
This is a semi-private blit function and it performs low-level surface blitting only.
DECLSPEC int SDLCALL SDL_LowerBlitScaled | ( | SDL_Surface * | src, |
SDL_Rect * | srcrect, | ||
SDL_Surface * | dst, | ||
SDL_Rect * | dstrect | ||
) |
This is a semi-private blit function and it performs low-level surface scaled blitting only.
DECLSPEC int SDLCALL SDL_SaveBMP_RW | ( | SDL_Surface * | surface, |
SDL_RWops * | dst, | ||
int | freedst | ||
) |
Save a surface to a seekable SDL data stream (memory or file).
If freedst
is non-zero, the stream will be closed after being written.
- Returns:
- 0 if successful or -1 if there was an error.
DECLSPEC SDL_bool SDLCALL SDL_SetClipRect | ( | SDL_Surface * | surface, |
const SDL_Rect * | rect | ||
) |
Sets the clipping rectangle for the destination surface in a blit.
If the clip rectangle is NULL, clipping will be disabled.
If the clip rectangle doesn't intersect the surface, the function will return SDL_FALSE and blits will be completely clipped. Otherwise the function returns SDL_TRUE and blits to the surface will be clipped to the intersection of the surface area and the clipping rectangle.
Note that blits are automatically clipped to the edges of the source and destination surfaces.
DECLSPEC int SDLCALL SDL_SetColorKey | ( | SDL_Surface * | surface, |
int | flag, | ||
Uint32 | key | ||
) |
Sets the color key (transparent pixel) in a blittable surface.
- Parameters:
-
surface The surface to update flag Non-zero to enable colorkey and 0 to disable colorkey key The transparent pixel in the native surface format
- Returns:
- 0 on success, or -1 if the surface is not valid
You can pass SDL_RLEACCEL to enable RLE accelerated blits.
DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod | ( | SDL_Surface * | surface, |
Uint8 | alpha | ||
) |
Set an additional alpha value used in blit operations.
- Parameters:
-
surface The surface to update. alpha The alpha value multiplied into blit operations.
- Returns:
- 0 on success, or -1 if the surface is not valid.
- See also:
- SDL_GetSurfaceAlphaMod()
DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode | ( | SDL_Surface * | surface, |
SDL_BlendMode | blendMode | ||
) |
Set the blend mode used for blit operations.
- Parameters:
-
surface The surface to update. blendMode SDL_BlendMode to use for blit blending.
- Returns:
- 0 on success, or -1 if the parameters are not valid.
- See also:
- SDL_GetSurfaceBlendMode()
DECLSPEC int SDLCALL SDL_SetSurfaceColorMod | ( | SDL_Surface * | surface, |
Uint8 | r, | ||
Uint8 | g, | ||
Uint8 | b | ||
) |
Set an additional color value used in blit operations.
- Parameters:
-
surface The surface to update. r The red color value multiplied into blit operations. g The green color value multiplied into blit operations. b The blue color value multiplied into blit operations.
- Returns:
- 0 on success, or -1 if the surface is not valid.
- See also:
- SDL_GetSurfaceColorMod()
DECLSPEC int SDLCALL SDL_SetSurfacePalette | ( | SDL_Surface * | surface, |
SDL_Palette * | palette | ||
) |
Set the palette used by a surface.
- Returns:
- 0, or -1 if the surface format doesn't use a palette.
- Note:
- A single palette can be shared with many surfaces.
DECLSPEC int SDLCALL SDL_SetSurfaceRLE | ( | SDL_Surface * | surface, |
int | flag | ||
) |
Sets the RLE acceleration hint for a surface.
- Returns:
- 0 on success, or -1 if the surface is not valid
- Note:
- If RLE is enabled, colorkey and alpha blending blits are much faster, but the surface must be locked before directly accessing the pixels.
DECLSPEC int SDLCALL SDL_SoftStretch | ( | SDL_Surface * | src, |
const SDL_Rect * | srcrect, | ||
SDL_Surface * | dst, | ||
const SDL_Rect * | dstrect | ||
) |
Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
- Note:
- This function uses a static buffer, and is not thread-safe.
DECLSPEC void SDLCALL SDL_UnlockSurface | ( | SDL_Surface * | surface ) |
- See also:
- SDL_LockSurface()
DECLSPEC int SDLCALL SDL_UpperBlit | ( | SDL_Surface * | src, |
const SDL_Rect * | srcrect, | ||
SDL_Surface * | dst, | ||
SDL_Rect * | dstrect | ||
) |
This is the public blit function, SDL_BlitSurface(), and it performs rectangle validation and clipping before passing it to SDL_LowerBlit()
DECLSPEC int SDLCALL SDL_UpperBlitScaled | ( | SDL_Surface * | src, |
const SDL_Rect * | srcrect, | ||
SDL_Surface * | dst, | ||
SDL_Rect * | dstrect | ||
) |
This is the public scaled blit function, SDL_BlitScaled(), and it performs rectangle validation and clipping before passing it to SDL_LowerBlitScaled()
Generated on Tue Jul 12 2022 15:10:21 by 1.7.2