Documentation

Allocate a new surface with a specific pixel format.

The pixels of the new surface are initialized to zero.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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().

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.

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.

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)

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.

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)

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.

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.

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.

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.

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.

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.

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.

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().

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().

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.
    

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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