Documentation

Allocate a new surface with a specific pixel format.

The pixels of the new surface are initialized to zero.

width

the width of the surface.

height

the height of the surface.

format

the SDL_PixelFormat for the new surface's pixel format.

Returns

the new SDL_Surface structure that is created or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_CreateSurfaceFrom, sDL_DestroySurface

C declaration

SDL_CreateSurface, defined at SDL3/SDL_surface.h 173:43

Since: 3.2.0

Allocate a new surface with a specific pixel format and existing pixel data.

No copy is made of the pixel data. Pixel data is not managed automatically; you must free the surface before you free the pixel data.

Pitch is the offset in bytes from one row of pixels to the next, e.g. width*4 for SDL_PIXELFORMAT_RGBA8888.

You may pass NULL for pixels and 0 for pitch to create a surface that you will fill in with valid values later.

width

the width of the surface.

height

the height of the surface.

format

the SDL_PixelFormat for the new surface's pixel format.

pixels

a pointer to existing pixel data.

pitch

the number of bytes between each row, including padding.

Returns

the new SDL_Surface structure that is created or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_CreateSurface, sDL_DestroySurface

C declaration

SDL_CreateSurfaceFrom, defined at SDL3/SDL_surface.h 203:43

Since: 3.2.0

Free a surface.

It is safe to pass NULL to this function.

surface

the SDL_Surface to free.

Thread safety

No other thread should be using the surface when it is freed.

See also

sDL_CreateSurface, sDL_CreateSurfaceFrom

C declaration

SDL_DestroySurface, defined at SDL3/SDL_surface.h 219:34

Since: 3.2.0

Get the properties associated with a surface.

The following properties are understood by SDL:

• sDL_PROP_SURFACE_SDR_WHITE_POINT_FLOAT: for HDR10 and floating point surfaces, this defines the value of 100% diffuse white, with higher values being displayed in the High Dynamic Range headroom. This defaults to 203 for HDR10 surfaces and 1.0 for floating point surfaces.
• sDL_PROP_SURFACE_HDR_HEADROOM_FLOAT: for HDR10 and floating point surfaces, this defines the maximum dynamic range used by the content, in terms of the SDR white point. This defaults to 0.0, which disables tone mapping.
• sDL_PROP_SURFACE_TONEMAP_OPERATOR_STRING: the tone mapping operator used when compressing from a surface with high dynamic range to another with lower dynamic range. Currently this supports "chrome", which uses the same tone mapping that Chrome uses for HDR content, the form "*=N", where N is a floating point scale factor applied in linear space, and "none", which disables tone mapping. This defaults to "chrome".
• sDL_PROP_SURFACE_HOTSPOT_X_NUMBER: the hotspot pixel offset from the left edge of the image, if this surface is being used as a cursor.
• sDL_PROP_SURFACE_HOTSPOT_Y_NUMBER: the hotspot pixel offset from the top edge of the image, if this surface is being used as a cursor.
• sDL_PROP_SURFACE_ROTATION_FLOAT: the number of degrees a surface's data is meant to be rotated clockwise to make the image right-side up. Default 1. This is used by the camera API, if a mobile device is oriented differently than what its camera provides (i.e. - the camera always provides portrait images but the phone is being held in landscape orientation). Since SDL 3.4.0.

surface

the SDL_Surface structure to query.

Returns

a valid property ID on success or 0 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetSurfaceProperties, defined at SDL3/SDL_surface.h 259:46

Since: 3.2.0

Set the colorspace used by a surface.

Setting the colorspace doesn't change the pixels, only how they are interpreted in color operations.

surface

the SDL_Surface structure to update.

colorspace

an SDL_Colorspace value describing the surface colorspace.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_GetSurfaceColorspace

C declaration

SDL_SetSurfaceColorspace, defined at SDL3/SDL_surface.h 287:34

Since: 3.2.0

Get the colorspace used by a surface.

The colorspace defaults to SDL_COLORSPACE_SRGB_LINEAR for floating point formats, SDL_COLORSPACE_HDR10 for 10-bit formats, SDL_COLORSPACE_SRGB for other RGB surfaces and SDL_COLORSPACE_BT709_FULL for YUV textures.

surface

the SDL_Surface structure to query.

Returns

the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if the surface is NULL.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_SetSurfaceColorspace

C declaration

SDL_GetSurfaceColorspace, defined at SDL3/SDL_surface.h 307:44

Since: 3.2.0

Create a palette and associate it with a surface.

This function creates a palette compatible with the provided surface. The palette is then returned for you to modify, and the surface will automatically use the new palette in future operations. You do not need to destroy the returned palette, it will be freed when the reference count reaches 0, usually when the surface is destroyed.

Bitmap surfaces (with format SDL_PIXELFORMAT_INDEX1LSB or SDL_PIXELFORMAT_INDEX1MSB) will have the palette initialized with 0 as white and 1 as black. Other surfaces will get a palette initialized with white in every entry.

If this function is called for a surface that already has a palette, a new palette will be created to replace it.

surface

the SDL_Surface structure to update.

Returns

a new SDL_Palette structure on success or NULL on failure (e.g. if the surface didn't have an index format); call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

SDL_SetPaletteColors

C declaration

SDL_CreateSurfacePalette, defined at SDL3/SDL_surface.h 338:43

Since: 3.2.0

Set the palette used by a surface.

Setting the palette keeps an internal reference to the palette, which can be safely destroyed afterwards.

A single palette can be shared with many surfaces.

surface

the SDL_Surface structure to update.

palette

the SDL_Palette structure to use.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

SDL_CreatePalette, sDL_GetSurfacePalette

C declaration

SDL_SetSurfacePalette, defined at SDL3/SDL_surface.h 361:34

Since: 3.2.0

Get the palette used by a surface.

surface

the SDL_Surface structure to query.

Returns

a pointer to the palette used by the surface, or NULL if there is no palette used.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetSurfacePalette

C declaration

SDL_GetSurfacePalette, defined at SDL3/SDL_surface.h 376:43

Since: 3.2.0

Add an alternate version of a surface.

This function adds an alternate version of this surface, usually used for content with high DPI representations like cursors or icons. The size, format, and content do not need to match the original surface, and these alternate versions will not be updated when the original surface changes.

This function adds a reference to the alternate version, so you should call SDL_DestroySurface() on the image after this call.

surface

the SDL_Surface structure to update.

image

a pointer to an alternate SDL_Surface to associate with this surface.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_RemoveSurfaceAlternateImages, sDL_GetSurfaceImages, sDL_SurfaceHasAlternateImages

C declaration

SDL_AddSurfaceAlternateImage, defined at SDL3/SDL_surface.h 404:34

Since: 3.2.0

Return whether a surface has alternate versions available.

surface

the SDL_Surface structure to query.

Returns

true if alternate versions are available or false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_AddSurfaceAlternateImage, sDL_RemoveSurfaceAlternateImages, sDL_GetSurfaceImages

C declaration

SDL_SurfaceHasAlternateImages, defined at SDL3/SDL_surface.h 420:34

Since: 3.2.0

Get an array including all versions of a surface.

This returns all versions of a surface, with the surface being queried as the first element in the returned array.

Freeing the array of surfaces does not affect the surfaces in the array. They are still referenced by the surface being queried and will be cleaned up normally.

surface

the SDL_Surface structure to query.

count

a pointer filled in with the number of surface pointers returned, may be NULL.

Returns

a NULL terminated array of SDL_Surface pointers or NULL on failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_AddSurfaceAlternateImage, sDL_RemoveSurfaceAlternateImages, sDL_SurfaceHasAlternateImages

C declaration

SDL_GetSurfaceImages, defined at SDL3/SDL_surface.h 448:44

Since: 3.2.0

Remove all alternate versions of a surface.

This function removes a reference from all the alternative versions, destroying them if this is the last reference to them.

surface

the SDL_Surface structure to update.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_AddSurfaceAlternateImage, sDL_GetSurfaceImages, sDL_SurfaceHasAlternateImages

C declaration

SDL_RemoveSurfaceAlternateImages, defined at SDL3/SDL_surface.h 467:34

Since: 3.2.0

Set 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.

surface

the SDL_Surface structure to be locked.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces. The locking referred to by this function is making the pixels available for direct access, not thread-safe locking.

See also

SDL_MUSTLOCK, sDL_UnlockSurface

C declaration

SDL_LockSurface, defined at SDL3/SDL_surface.h 495:34

Since: 3.2.0

Release a surface after directly accessing the pixels.

surface

the SDL_Surface structure to be unlocked.

Thread safety

This function is not thread safe. The locking referred to by this function is making the pixels available for direct access, not thread-safe locking.

See also

sDL_LockSurface

C declaration

SDL_UnlockSurface, defined at SDL3/SDL_surface.h 510:34

Since: 3.2.0

Load a BMP or PNG image from a seekable SDL data stream.

The new surface should be freed with SDL_DestroySurface(). Not doing so will result in a memory leak.

src

the data stream for the surface.

closeio

if true, calls SDL_CloseIO() on src before returning, even in the case of an error.

Returns

a pointer to a new SDL_Surface structure or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DestroySurface, sDL_LoadSurface

C declaration

SDL_LoadSurface_IO, defined at SDL3/SDL_surface.h 531:43

Since: 3.4.0

Load a BMP or PNG image from a file.

The new surface should be freed with SDL_DestroySurface(). Not doing so will result in a memory leak.

file

the file to load.

Returns

a pointer to a new SDL_Surface structure or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DestroySurface, sDL_LoadSurface_IO

C declaration

SDL_LoadSurface, defined at SDL3/SDL_surface.h 550:43

Since: 3.4.0

Load a BMP image from a seekable SDL data stream.

The new surface should be freed with SDL_DestroySurface(). Not doing so will result in a memory leak.

src

the data stream for the surface.

closeio

if true, calls SDL_CloseIO() on src before returning, even in the case of an error.

Returns

a pointer to a new SDL_Surface structure or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DestroySurface, sDL_LoadBMP, sDL_SaveBMP_IO

C declaration

SDL_LoadBMP_IO, defined at SDL3/SDL_surface.h 572:43

Since: 3.2.0

Load a BMP image from a file.

The new surface should be freed with SDL_DestroySurface(). Not doing so will result in a memory leak.

file

the BMP file to load.

Returns

a pointer to a new SDL_Surface structure or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DestroySurface, sDL_LoadBMP_IO, sDL_SaveBMP

C declaration

SDL_LoadBMP, defined at SDL3/SDL_surface.h 592:43

Since: 3.2.0

Save a surface to a seekable SDL data stream in BMP format.

Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the BMP directly. Other RGB formats with 8-bit or higher get converted to a 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit surface before they are saved. YUV and paletted 1-bit and 4-bit formats are not supported.

surface

the SDL_Surface structure containing the image to be saved.

dst

a data stream to save to.

closeio

if true, calls SDL_CloseIO() on dst before returning, even in the case of an error.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_LoadBMP_IO, sDL_SaveBMP

C declaration

SDL_SaveBMP_IO, defined at SDL3/SDL_surface.h 618:34

Since: 3.2.0

Save a surface to a file in BMP format.

Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the BMP directly. Other RGB formats with 8-bit or higher get converted to a 24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit surface before they are saved. YUV and paletted 1-bit and 4-bit formats are not supported.

surface

the SDL_Surface structure containing the image to be saved.

file

a file to save to.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_LoadBMP, sDL_SaveBMP_IO

C declaration

SDL_SaveBMP, defined at SDL3/SDL_surface.h 642:34

Since: 3.2.0

Load a PNG image from a seekable SDL data stream.

This is intended as a convenience function for loading images from trusted sources. If you want to load arbitrary images you should use libpng or another image loading library designed with security in mind.

The new surface should be freed with SDL_DestroySurface(). Not doing so will result in a memory leak.

src

the data stream for the surface.

closeio

if true, calls SDL_CloseIO() on src before returning, even in the case of an error.

Returns

a pointer to a new SDL_Surface structure or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DestroySurface, sDL_LoadPNG, sDL_SavePNG_IO

C declaration

SDL_LoadPNG_IO, defined at SDL3/SDL_surface.h 668:43

Since: 3.4.0

Load a PNG image from a file.

This is intended as a convenience function for loading images from trusted sources. If you want to load arbitrary images you should use libpng or another image loading library designed with security in mind.

The new surface should be freed with SDL_DestroySurface(). Not doing so will result in a memory leak.

file

the PNG file to load.

Returns

a pointer to a new SDL_Surface structure or NULL on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DestroySurface, sDL_LoadPNG_IO, sDL_SavePNG

C declaration

SDL_LoadPNG, defined at SDL3/SDL_surface.h 692:43

Since: 3.4.0

Save a surface to a seekable SDL data stream in PNG format.

surface

the SDL_Surface structure containing the image to be saved.

dst

a data stream to save to.

closeio

if true, calls SDL_CloseIO() on dst before returning, even in the case of an error.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_LoadPNG_IO, sDL_SavePNG

C declaration

SDL_SavePNG_IO, defined at SDL3/SDL_surface.h 712:34

Since: 3.4.0

Save a surface to a file in PNG format.

surface

the SDL_Surface structure containing the image to be saved.

file

a file to save to.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_LoadPNG, sDL_SavePNG_IO

C declaration

SDL_SavePNG, defined at SDL3/SDL_surface.h 730:34

Since: 3.4.0

Set the RLE acceleration hint for a surface.

If RLE is enabled, color key and alpha blending blits are much faster, but the surface must be locked before directly accessing the pixels.

surface

the SDL_Surface structure to optimize.

enabled

true to enable RLE acceleration, false to disable it.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_BlitSurface, sDL_LockSurface, sDL_UnlockSurface

C declaration

SDL_SetSurfaceRLE, defined at SDL3/SDL_surface.h 752:34

Since: 3.2.0

Returns whether the surface is RLE enabled.

It is safe to pass a NULL surface here; it will return false.

surface

the SDL_Surface structure to query.

Returns

true if the surface is RLE enabled, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetSurfaceRLE

C declaration

SDL_SurfaceHasRLE, defined at SDL3/SDL_surface.h 768:34

Since: 3.2.0

Set the color key (transparent pixel) in a surface.

The color key defines a pixel value that will be treated as transparent in a blit. For example, one can use this to specify that cyan pixels should be considered transparent, and therefore not rendered.

It is a pixel of the format used by the surface, as generated by SDL_MapRGB().

surface

the SDL_Surface structure to update.

enabled

true to enable color key, false to disable color key.

key

the transparent pixel.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_GetSurfaceColorKey, sDL_SetSurfaceRLE, sDL_SurfaceHasColorKey

C declaration

SDL_SetSurfaceColorKey, defined at SDL3/SDL_surface.h 795:34

Since: 3.2.0

Returns whether the surface has a color key.

It is safe to pass a NULL surface here; it will return false.

surface

the SDL_Surface structure to query.

Returns

true if the surface has a color key, false otherwise.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetSurfaceColorKey, sDL_GetSurfaceColorKey

C declaration

SDL_SurfaceHasColorKey, defined at SDL3/SDL_surface.h 812:34

Since: 3.2.0

Get the color key (transparent pixel) for a surface.

The color key is a pixel of the format used by the surface, as generated by SDL_MapRGB().

If the surface doesn't have color key enabled this function returns false.

surface

the SDL_Surface structure to query.

key

a pointer filled in with the transparent pixel.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetSurfaceColorKey, sDL_SurfaceHasColorKey

C declaration

SDL_GetSurfaceColorKey, defined at SDL3/SDL_surface.h 834:34

Since: 3.2.0

Set an additional color value multiplied into blit operations.

When this surface is blitted, during the blit operation each source color channel is modulated by the appropriate color value according to the following formula:

srcC = srcC * (color / 255)

surface

the SDL_Surface structure 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

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_GetSurfaceColorMod, sDL_SetSurfaceAlphaMod

C declaration

SDL_SetSurfaceColorMod, defined at SDL3/SDL_surface.h 860:34

Since: 3.2.0

Get the additional color value multiplied into blit operations.

surface

the SDL_Surface structure 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

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_GetSurfaceAlphaMod, sDL_SetSurfaceColorMod

C declaration

SDL_GetSurfaceColorMod, defined at SDL3/SDL_surface.h 881:34

Since: 3.2.0

Set an additional alpha value used in blit operations.

When this surface is blitted, during the blit operation the source alpha value is modulated by this alpha value according to the following formula:

srcA = srcA * (alpha / 255)

surface

the SDL_Surface structure to update.

alpha

the alpha value multiplied into blit operations.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_GetSurfaceAlphaMod, sDL_SetSurfaceColorMod

C declaration

SDL_SetSurfaceAlphaMod, defined at SDL3/SDL_surface.h 904:34

Since: 3.2.0

Get the additional alpha value used in blit operations.

surface

the SDL_Surface structure to query.

alpha

a pointer filled in with the current alpha value.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetSurfaceColorMod, sDL_SetSurfaceAlphaMod

C declaration

SDL_GetSurfaceAlphaMod, defined at SDL3/SDL_surface.h 921:34

Since: 3.2.0

Set the blend mode used for blit operations.

To copy a surface to another surface (or texture) without blending with the existing data, the blendmode of the SOURCE surface should be set to SDL_BLENDMODE_NONE.

surface

the SDL_Surface structure to update.

blendMode

the SDL_BlendMode to use for blit blending.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_GetSurfaceBlendMode

C declaration

SDL_SetSurfaceBlendMode, defined at SDL3/SDL_surface.h 942:34

Since: 3.2.0

Get the blend mode used for blit operations.

surface

the SDL_Surface structure to query.

blendMode

a pointer filled in with the current SDL_BlendMode.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_SetSurfaceBlendMode

C declaration

SDL_GetSurfaceBlendMode, defined at SDL3/SDL_surface.h 958:34

Since: 3.2.0

Set the clipping rectangle for a surface.

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

Note that blits are automatically clipped to the edges of the source and destination surfaces.

surface

the SDL_Surface structure to be clipped.

rect

the SDL_Rect structure representing the clipping rectangle, or NULL to disable clipping.

Returns

true if the rectangle intersects the surface, otherwise false and blits will be completely clipped.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_GetSurfaceClipRect

C declaration

SDL_SetSurfaceClipRect, defined at SDL3/SDL_surface.h 982:34

Since: 3.2.0

Get the clipping rectangle for a surface.

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

surface

the SDL_Surface structure representing the surface to be clipped.

rect

an SDL_Rect structure filled in with the clipping rectangle for the surface.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_SetSurfaceClipRect

C declaration

SDL_GetSurfaceClipRect, defined at SDL3/SDL_surface.h 1004:34

Since: 3.2.0

Flip a surface vertically or horizontally.

surface

the surface to flip.

flip

the direction to flip.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

C declaration

SDL_FlipSurface, defined at SDL3/SDL_surface.h 1019:34

Since: 3.2.0

Return a copy of a surface rotated clockwise a number of degrees.

The angle of rotation can be negative for counter-clockwise rotation.

When the rotation isn't a multiple of 90 degrees, the resulting surface is larger than the original, with the background filled in with the colorkey, if available, or RGBA 255/255/255/0 if not.

If surface has the SDL_PROP_SURFACE_ROTATION_FLOAT property set on it, the new copy will have the adjusted value set: if the rotation property is 90 and angle was 30, the new surface will have a property value of 60 (that is: to be upright vs gravity, this surface needs to rotate 60 more degrees). However, note that further rotations on the new surface in this example will produce unexpected results, since the image will have resized and padded to accommodate the not-90 degree angle.

surface

the surface to rotate.

angle

the rotation angle, in degrees.

Returns

a rotated copy of the surface or NULL on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

C declaration

SDL_RotateSurface, defined at SDL3/SDL_surface.h 1048:43

Since: 3.4.0

Creates a new surface identical to the existing surface.

If the original surface has alternate images, the new surface will have a reference to them as well.

The returned surface should be freed with SDL_DestroySurface().

surface

the surface to duplicate.

Returns

a copy of the surface or NULL on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_DestroySurface

C declaration

SDL_DuplicateSurface, defined at SDL3/SDL_surface.h 1069:43

Since: 3.2.0

Creates a new surface identical to the existing surface, scaled to the desired size.

The returned surface should be freed with SDL_DestroySurface().

surface

the surface to duplicate and scale.

width

the width of the new surface.

height

the height of the new surface.

scaleMode

the SDL_ScaleMode to be used.

Returns

a copy of the surface or NULL on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_DestroySurface

C declaration

SDL_ScaleSurface, defined at SDL3/SDL_surface.h 1091:43

Since: 3.2.0

Copy an existing surface to a new surface of the specified format.

This function is used to optimize images for faster repeat blitting. This is accomplished by converting the original and storing the result as a new surface. The new, optimized surface can then be used as the source for future blits, making them faster.

If you are converting to an indexed surface and want to map colors to a palette, you can use SDL_ConvertSurfaceAndColorspace() instead.

If the original surface has alternate images, the new surface will have a reference to them as well.

surface

the existing SDL_Surface structure to convert.

format

the new pixel format.

Returns

the new SDL_Surface structure that is created or NULL on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_ConvertSurfaceAndColorspace, sDL_DestroySurface

C declaration

SDL_ConvertSurface, defined at SDL3/SDL_surface.h 1120:43

Since: 3.2.0

Copy an existing surface to a new surface of the specified format and colorspace.

This function converts an existing surface to a new format and colorspace and returns the new surface. This will perform any pixel format and colorspace conversion needed.

If the original surface has alternate images, the new surface will have a reference to them as well.

surface

the existing SDL_Surface structure to convert.

format

the new pixel format.

palette

an optional palette to use for indexed formats, may be NULL.

colorspace

the new colorspace.

props

an SDL_PropertiesID with additional color properties, or 0.

Returns

the new SDL_Surface structure that is created or NULL on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_ConvertSurface, sDL_DestroySurface

C declaration

SDL_ConvertSurfaceAndColorspace, defined at SDL3/SDL_surface.h 1149:43

Since: 3.2.0

Copy a block of pixels of one format to another format.

width

the width of the block to copy, in pixels.

height

the height of the block to copy, in pixels.

src_format

an SDL_PixelFormat value of the src pixels format.

src

a pointer to the source pixels.

src_pitch

the pitch of the source pixels, in bytes.

dst_format

an SDL_PixelFormat value of the dst pixels format.

dst

a pointer to be filled in with new pixel data.

dst_pitch

the pitch of the destination pixels, in bytes.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

The same destination pixels should not be used from two threads at once. It is safe to use the same source pixels from multiple threads.

See also

sDL_ConvertPixelsAndColorspace

C declaration

SDL_ConvertPixels, defined at SDL3/SDL_surface.h 1173:34

Since: 3.2.0

Copy a block of pixels of one format and colorspace to another format and colorspace.

width

the width of the block to copy, in pixels.

height

the height of the block to copy, in pixels.

src_format

an SDL_PixelFormat value of the src pixels format.

src_colorspace

an SDL_Colorspace value describing the colorspace of the src pixels.

src_properties

an SDL_PropertiesID with additional source color properties, or 0.

src

a pointer to the source pixels.

src_pitch

the pitch of the source pixels, in bytes.

dst_format

an SDL_PixelFormat value of the dst pixels format.

dst_colorspace

an SDL_Colorspace value describing the colorspace of the dst pixels.

dst_properties

an SDL_PropertiesID with additional destination color properties, or 0.

dst

a pointer to be filled in with new pixel data.

dst_pitch

the pitch of the destination pixels, in bytes.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

The same destination pixels should not be used from two threads at once. It is safe to use the same source pixels from multiple threads.

See also

sDL_ConvertPixels

C declaration

SDL_ConvertPixelsAndColorspace, defined at SDL3/SDL_surface.h 1206:34

Since: 3.2.0

Premultiply the alpha on a block of pixels.

This is safe to use with src == dst, but not for other overlapping areas.

width

the width of the block to convert, in pixels.

height

the height of the block to convert, in pixels.

src_format

an SDL_PixelFormat value of the src pixels format.

src

a pointer to the source pixels.

src_pitch

the pitch of the source pixels, in bytes.

dst_format

an SDL_PixelFormat value of the dst pixels format.

dst

a pointer to be filled in with premultiplied pixel data.

dst_pitch

the pitch of the destination pixels, in bytes.

linear

true to convert from sRGB to linear space for the alpha multiplication, false to do multiplication in sRGB space.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

The same destination pixels should not be used from two threads at once. It is safe to use the same source pixels from multiple threads.

C declaration

SDL_PremultiplyAlpha, defined at SDL3/SDL_surface.h 1232:34

Since: 3.2.0

Premultiply the alpha in a surface.

This is safe to use with src == dst, but not for other overlapping areas.

surface

the surface to modify.

linear

true to convert from sRGB to linear space for the alpha multiplication, false to do multiplication in sRGB space.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

C declaration

SDL_PremultiplySurfaceAlpha, defined at SDL3/SDL_surface.h 1250:34

Since: 3.2.0

Clear a surface with a specific color, with floating point precision.

This function handles all surface formats, and ignores any clip rectangle.

If the surface is YUV, the color is assumed to be in the sRGB colorspace, otherwise the color is assumed to be in the colorspace of the surface.

surface

the SDL_Surface to clear.

r

the red component of the pixel, normally in the range 0-1.

g

the green component of the pixel, normally in the range 0-1.

b

the blue component of the pixel, normally in the range 0-1.

a

the alpha component of the pixel, normally in the range 0-1.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

C declaration

SDL_ClearSurface, defined at SDL3/SDL_surface.h 1273:34

Since: 3.2.0

Perform a fast fill of a rectangle with a specific color.

color should be a pixel of the format used by the surface, and can be generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an alpha component then the destination is simply filled with that alpha information, no blending takes place.

If there is a clip rectangle set on the destination (set via SDL_SetSurfaceClipRect()), then this function will fill based on the intersection of the clip rectangle and rect.

dst

the SDL_Surface structure that is the drawing target.

rect

the SDL_Rect structure representing the rectangle to fill, or NULL to fill the entire surface.

color

the color to fill with.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_FillSurfaceRects

C declaration

SDL_FillSurfaceRect, defined at SDL3/SDL_surface.h 1301:34

Since: 3.2.0

Perform a fast fill of a set of rectangles with a specific color.

color should be a pixel of the format used by the surface, and can be generated by SDL_MapRGB() or SDL_MapRGBA(). If the color value contains an alpha component then the destination is simply filled with that alpha information, no blending takes place.

If there is a clip rectangle set on the destination (set via SDL_SetSurfaceClipRect()), then this function will fill based on the intersection of the clip rectangle and rect.

dst

the SDL_Surface structure that is the drawing target.

rects

an array of SDL_Rects representing the rectangles to fill.

count

the number of rectangles in the array.

color

the color to fill with.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_FillSurfaceRect

C declaration

SDL_FillSurfaceRects, defined at SDL3/SDL_surface.h 1329:34

Since: 3.2.0

Performs a fast blit from the source surface to the destination surface with clipping.

If either srcrect or dstrect are NULL, the entire surface (src or dst) is copied while ensuring clipping to dst->clip_rect.

The blit function should not be called on a locked surface.

The blit semantics for surfaces with and without blending and colorkey are defined as follows:

     RGBA->RGB:
       Source surface blend mode set to SDL_BLENDMODE_BLEND:
        alpha-blend (using the source alpha-channel and per-surface alpha)
        SDL_SRCCOLORKEY ignored.
      Source surface blend mode set to SDL_BLENDMODE_NONE:
        copy RGB.
        if SDL_SRCCOLORKEY set, only copy the pixels that do not match the
        RGB values of the source color key, ignoring alpha in the
        comparison.

    RGB->RGBA:
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
        alpha-blend (using the source per-surface alpha)
      Source surface blend mode set to SDL_BLENDMODE_NONE:
        copy RGB, set destination alpha to source per-surface alpha value.
      both:
        if SDL_SRCCOLORKEY set, only copy the pixels that do not match the
        source color key.

    RGBA->RGBA:
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
        alpha-blend (using the source alpha-channel and per-surface alpha)
        SDL_SRCCOLORKEY ignored.
      Source surface blend mode set to SDL_BLENDMODE_NONE:
        copy all of RGBA to the destination.
        if SDL_SRCCOLORKEY set, only copy the pixels that do not match the
        RGB values of the source color key, ignoring alpha in the
        comparison.

    RGB->RGB:
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
        alpha-blend (using the source per-surface alpha)
      Source surface blend mode set to SDL_BLENDMODE_NONE:
        copy RGB.
      both:
        if SDL_SRCCOLORKEY set, only copy the pixels that do not match the
        source color key.
    

src

the SDL_Surface structure to be copied from.

srcrect

the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface.

dst

the SDL_Surface structure that is the blit target.

dstrect

the SDL_Rect structure representing the x and y position in the destination surface, or NULL for (0,0). The width and height are ignored, and are copied from srcrect. If you want a specific width and height, you should use SDL_BlitSurfaceScaled().

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

Only one thread should be using the src and dst surfaces at any given time.

See also

sDL_BlitSurfaceScaled

C declaration

SDL_BlitSurface, defined at SDL3/SDL_surface.h 1402:34

Since: 3.2.0

Perform low-level surface blitting only.

This is a semi-private blit function and it performs low-level surface blitting, assuming the input rectangles have already been clipped.

src

the SDL_Surface structure to be copied from.

srcrect

the SDL_Rect structure representing the rectangle to be copied, may not be NULL.

dst

the SDL_Surface structure that is the blit target.

dstrect

the SDL_Rect structure representing the target rectangle in the destination surface, may not be NULL.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

Only one thread should be using the src and dst surfaces at any given time.

See also

sDL_BlitSurface

C declaration

SDL_BlitSurfaceUnchecked, defined at SDL3/SDL_surface.h 1426:34

Since: 3.2.0

Perform a scaled blit to a destination surface, which may be of a different format.

src

the SDL_Surface structure to be copied from.

srcrect

the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface.

dst

the SDL_Surface structure that is the blit target.

dstrect

the SDL_Rect structure representing the target rectangle in the destination surface, or NULL to fill the entire destination surface.

scaleMode

the SDL_ScaleMode to be used.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

Only one thread should be using the src and dst surfaces at any given time.

See also

sDL_BlitSurface

C declaration

SDL_BlitSurfaceScaled, defined at SDL3/SDL_surface.h 1450:34

Since: 3.2.0

Perform low-level surface scaled blitting only.

This is a semi-private function and it performs low-level surface blitting, assuming the input rectangles have already been clipped.

src

the SDL_Surface structure to be copied from.

srcrect

the SDL_Rect structure representing the rectangle to be copied, may not be NULL.

dst

the SDL_Surface structure that is the blit target.

dstrect

the SDL_Rect structure representing the target rectangle in the destination surface, may not be NULL.

scaleMode

the SDL_ScaleMode to be used.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

Only one thread should be using the src and dst surfaces at any given time.

See also

sDL_BlitSurfaceScaled

C declaration

SDL_BlitSurfaceUncheckedScaled, defined at SDL3/SDL_surface.h 1475:34

Since: 3.2.0

Perform a stretched pixel copy from one surface to another.

src

the SDL_Surface structure to be copied from.

srcrect

the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface.

dst

the SDL_Surface structure that is the blit target.

dstrect

the SDL_Rect structure representing the target rectangle in the destination surface, or NULL to fill the entire destination surface.

scaleMode

the SDL_ScaleMode to be used.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

Only one thread should be using the src and dst surfaces at any given time.

See also

sDL_BlitSurfaceScaled

C declaration

SDL_StretchSurface, defined at SDL3/SDL_surface.h 1498:34

Since: 3.4.0

Perform a tiled blit to a destination surface, which may be of a different format.

The pixels in srcrect will be repeated as many times as needed to completely fill dstrect.

src

the SDL_Surface structure to be copied from.

srcrect

the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface.

dst

the SDL_Surface structure that is the blit target.

dstrect

the SDL_Rect structure representing the target rectangle in the destination surface, or NULL to fill the entire surface.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

Only one thread should be using the src and dst surfaces at any given time.

See also

sDL_BlitSurface

C declaration

SDL_BlitSurfaceTiled, defined at SDL3/SDL_surface.h 1523:34

Since: 3.2.0

Perform a scaled and tiled blit to a destination surface, which may be of a different format.

The pixels in srcrect will be scaled and repeated as many times as needed to completely fill dstrect.

src

the SDL_Surface structure to be copied from.

srcrect

the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface.

scale

the scale used to transform srcrect into the destination rectangle, e.g. a 32x32 texture with a scale of 2 would fill 64x64 tiles.

scaleMode

scale algorithm to be used.

dst

the SDL_Surface structure that is the blit target.

dstrect

the SDL_Rect structure representing the target rectangle in the destination surface, or NULL to fill the entire surface.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

Only one thread should be using the src and dst surfaces at any given time.

See also

sDL_BlitSurface

C declaration

SDL_BlitSurfaceTiledWithScale, defined at SDL3/SDL_surface.h 1552:34

Since: 3.2.0

Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.

The pixels in the source surface are split into a 3x3 grid, using the different corner sizes for each corner, and the sides and center making up the remaining pixels. The corners are then scaled using scale and fit into the corners of the destination rectangle. The sides and center are then stretched into place to cover the remaining destination rectangle.

src

the SDL_Surface structure to be copied from.

srcrect

the SDL_Rect structure representing the rectangle to be used for the 9-grid, or NULL to use the entire surface.

left_width

the width, in pixels, of the left corners in srcrect.

right_width

the width, in pixels, of the right corners in srcrect.

top_height

the height, in pixels, of the top corners in srcrect.

bottom_height

the height, in pixels, of the bottom corners in srcrect.

scale

the scale used to transform the corner of srcrect into the corner of dstrect, or 0.0f for an unscaled blit.

scaleMode

scale algorithm to be used.

dst

the SDL_Surface structure that is the blit target.

dstrect

the SDL_Rect structure representing the target rectangle in the destination surface, or NULL to fill the entire surface.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

Only one thread should be using the src and dst surfaces at any given time.

See also

sDL_BlitSurface

C declaration

SDL_BlitSurface9Grid, defined at SDL3/SDL_surface.h 1588:34

Since: 3.2.0

Map an RGB triple to an opaque pixel value for a surface.

This function maps the RGB color value to the specified pixel format and returns the pixel value best approximating the given RGB color value for the given pixel format.

If the surface has a palette, the index of the closest matching color in the palette will be returned.

If the surface pixel format has an alpha component it will be returned as all 1 bits (fully opaque).

If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).

surface

the surface to use for the pixel format and palette.

r

the red component of the pixel in the range 0-255.

g

the green component of the pixel in the range 0-255.

b

the blue component of the pixel in the range 0-255.

Returns

a pixel value.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_MapSurfaceRGBA

C declaration

SDL_MapSurfaceRGB, defined at SDL3/SDL_surface.h 1621:36

Since: 3.2.0

Map an RGBA quadruple to a pixel value for a surface.

This function maps the RGBA color value to the specified pixel format and returns the pixel value best approximating the given RGBA color value for the given pixel format.

If the surface pixel format has no alpha component the alpha value will be ignored (as it will be in formats with a palette).

If the surface has a palette, the index of the closest matching color in the palette will be returned.

If the pixel format bpp (color depth) is less than 32-bpp then the unused upper bits of the return value can safely be ignored (e.g., with a 16-bpp format the return value can be assigned to a Uint16, and similarly a Uint8 for an 8-bpp format).

surface

the surface to use for the pixel format and palette.

r

the red component of the pixel in the range 0-255.

g

the green component of the pixel in the range 0-255.

b

the blue component of the pixel in the range 0-255.

a

the alpha component of the pixel in the range 0-255.

Returns

a pixel value.

Thread safety

This function can be called on different threads with different surfaces.

See also

sDL_MapSurfaceRGB

C declaration

SDL_MapSurfaceRGBA, defined at SDL3/SDL_surface.h 1655:36

Since: 3.2.0

Retrieves a single pixel from a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

Like SDL_GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

surface

the surface to read.

x

the horizontal coordinate, 0 <= x < width.

y

the vertical coordinate, 0 <= y < height.

r

a pointer filled in with the red channel, 0-255, or NULL to ignore this channel.

g

a pointer filled in with the green channel, 0-255, or NULL to ignore this channel.

b

a pointer filled in with the blue channel, 0-255, or NULL to ignore this channel.

a

a pointer filled in with the alpha channel, 0-255, or NULL to ignore this channel.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

C declaration

SDL_ReadSurfacePixel, defined at SDL3/SDL_surface.h 1685:34

Since: 3.2.0

Retrieves a single pixel from a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

surface

the surface to read.

x

the horizontal coordinate, 0 <= x < width.

y

the vertical coordinate, 0 <= y < height.

r

a pointer filled in with the red channel, normally in the range 0-1, or NULL to ignore this channel.

g

a pointer filled in with the green channel, normally in the range 0-1, or NULL to ignore this channel.

b

a pointer filled in with the blue channel, normally in the range 0-1, or NULL to ignore this channel.

a

a pointer filled in with the alpha channel, normally in the range 0-1, or NULL to ignore this channel.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

C declaration

SDL_ReadSurfacePixelFloat, defined at SDL3/SDL_surface.h 1712:34

Since: 3.2.0

Writes a single pixel to a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

Like SDL_MapRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

surface

the surface to write.

x

the horizontal coordinate, 0 <= x < width.

y

the vertical coordinate, 0 <= y < height.

r

the red channel value, 0-255.

g

the green channel value, 0-255.

b

the blue channel value, 0-255.

a

the alpha channel value, 0-255.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

C declaration

SDL_WriteSurfacePixel, defined at SDL3/SDL_surface.h 1738:34

Since: 3.2.0

Writes a single pixel to a surface.

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

surface

the surface to write.

x

the horizontal coordinate, 0 <= x < width.

y

the vertical coordinate, 0 <= y < height.

r

the red channel value, normally in the range 0-1.

g

the green channel value, normally in the range 0-1.

b

the blue channel value, normally in the range 0-1.

a

the alpha channel value, normally in the range 0-1.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

This function can be called on different threads with different surfaces.

C declaration

SDL_WriteSurfacePixelFloat, defined at SDL3/SDL_surface.h 1761:34

Since: 3.2.0