Module surface

Available on crate feature dep_sdl3 only.

SDL surfaces are buffers of pixels in system RAM. These are useful for passing around and manipulating images that are not stored in GPU memory.

SDL_Surface makes serious efforts to manage images in various formats, and provides a reasonable toolbox for transforming the data, including copying between surfaces, filling rectangles in the image data, etc.

There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not provide loaders for various other file formats, but there are several excellent external libraries that do, including its own satellite library, SDL_image:

https://github.com/libsdl-org/SDL_image

Structs

SDL_FlipMode

The flip mode.

SDL_ScaleMode

The scaling mode.

SDL_Surface

A collection of pixels used in software blitting.

Constants

SDL_FLIP_HORIZONTAL

flip horizontally

SDL_FLIP_NONE

Do not flip

SDL_FLIP_VERTICAL

flip vertically

SDL_PROP_SURFACE_HDR_HEADROOM_FLOAT

SDL_PROP_SURFACE_SDR_WHITE_POINT_FLOAT

SDL_PROP_SURFACE_TONEMAP_OPERATOR_STRING

SDL_SCALEMODE_LINEAR

linear filtering

SDL_SCALEMODE_NEAREST

nearest pixel sampling

SDL_SURFACE_LOCKED

Surface is currently locked

SDL_SURFACE_LOCK_NEEDED

Surface needs to be locked to access pixels

SDL_SURFACE_PREALLOCATED

Surface uses preallocated pixel memory

SDL_SURFACE_SIMD_ALIGNED

Surface uses pixel memory allocated with SDL_aligned_alloc()

Functions

SDL_AddSurfaceAlternateImage^⚠

Add an alternate version of a surface.

SDL_BlitSurface^⚠

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

SDL_BlitSurface9Grid^⚠

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

SDL_BlitSurfaceScaled^⚠

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

SDL_BlitSurfaceTiled^⚠

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

SDL_BlitSurfaceTiledWithScale^⚠

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

SDL_BlitSurfaceUnchecked^⚠

Perform low-level surface blitting only.

SDL_BlitSurfaceUncheckedScaled^⚠

Perform low-level surface scaled blitting only.

SDL_ClearSurface^⚠

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

SDL_ConvertPixels^⚠

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

SDL_ConvertPixelsAndColorspace^⚠

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

SDL_ConvertSurface^⚠

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

SDL_ConvertSurfaceAndColorspace^⚠

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

SDL_CreateSurface^⚠

Allocate a new surface with a specific pixel format.

SDL_CreateSurfaceFrom^⚠

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

SDL_CreateSurfacePalette^⚠

Create a palette and associate it with a surface.

SDL_DestroySurface^⚠

Free a surface.

SDL_DuplicateSurface^⚠

Creates a new surface identical to the existing surface.

SDL_FillSurfaceRect^⚠

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

SDL_FillSurfaceRects^⚠

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

SDL_FlipSurface^⚠

Flip a surface vertically or horizontally.

SDL_GetSurfaceAlphaMod^⚠

Get the additional alpha value used in blit operations.

SDL_GetSurfaceBlendMode^⚠

Get the blend mode used for blit operations.

SDL_GetSurfaceClipRect^⚠

Get the clipping rectangle for a surface.

SDL_GetSurfaceColorKey^⚠

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

SDL_GetSurfaceColorMod^⚠

Get the additional color value multiplied into blit operations.

SDL_GetSurfaceColorspace^⚠

Get the colorspace used by a surface.

SDL_GetSurfaceImages^⚠

Get an array including all versions of a surface.

SDL_GetSurfacePalette^⚠

Get the palette used by a surface.

SDL_GetSurfaceProperties^⚠

Get the properties associated with a surface.

SDL_LoadBMP^⚠

Load a BMP image from a file.

SDL_LoadBMP_IO^⚠

Load a BMP image from a seekable SDL data stream.

SDL_LockSurface^⚠

Set up a surface for directly accessing the pixels.

SDL_MUSTLOCK^⚠

Evaluates to true if the surface needs to be locked before access.

SDL_MapSurfaceRGB^⚠

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

SDL_MapSurfaceRGBA^⚠

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

SDL_PremultiplyAlpha^⚠

Premultiply the alpha on a block of pixels.

SDL_PremultiplySurfaceAlpha^⚠

Premultiply the alpha in a surface.

SDL_ReadSurfacePixel^⚠

Retrieves a single pixel from a surface.

SDL_ReadSurfacePixelFloat^⚠

Retrieves a single pixel from a surface.

SDL_RemoveSurfaceAlternateImages^⚠

Remove all alternate versions of a surface.

SDL_SaveBMP^⚠

Save a surface to a file.

SDL_SaveBMP_IO^⚠

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

SDL_ScaleSurface^⚠

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

SDL_SetSurfaceAlphaMod^⚠

Set an additional alpha value used in blit operations.

SDL_SetSurfaceBlendMode^⚠

Set the blend mode used for blit operations.

SDL_SetSurfaceClipRect^⚠

Set the clipping rectangle for a surface.

SDL_SetSurfaceColorKey^⚠

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

SDL_SetSurfaceColorMod^⚠

Set an additional color value multiplied into blit operations.

SDL_SetSurfaceColorspace^⚠

Set the colorspace used by a surface.

SDL_SetSurfacePalette^⚠

Set the palette used by a surface.

SDL_SetSurfaceRLE^⚠

Set the RLE acceleration hint for a surface.

SDL_StretchSurface^⚠

Perform a stretched pixel copy from one surface to another.

SDL_SurfaceHasAlternateImages^⚠

Return whether a surface has alternate versions available.

SDL_SurfaceHasColorKey^⚠

Returns whether the surface has a color key.

SDL_SurfaceHasRLE^⚠

Returns whether the surface is RLE enabled.

SDL_UnlockSurface^⚠

Release a surface after directly accessing the pixels.

SDL_WriteSurfacePixel^⚠

Writes a single pixel to a surface.

SDL_WriteSurfacePixelFloat^⚠

Writes a single pixel to a surface.

Type Aliases

SDL_SurfaceFlags

The flags on an SDL_Surface.