SDL surfaces are buffers of pixels in system RAM. More...

Classes
struct	SDL::SurfaceBase
	A collection of pixels used in software blitting. More...

struct	SDL::SurfaceRef
	Handle to a non owned surface. More...

struct	SDL::Surface
	Handle to an owned surface. More...

class	SDL::SurfaceLock
	Locks a Surface for access to its pixels. More...

Typedefs
using	SDL::SurfaceFlags = Uint32
	The flags on an SurfaceBase.

using	SDL::ScaleMode = SDL_ScaleMode
	The scaling mode.

using	SDL::FlipMode = SDL_FlipMode
	The flip mode.

Functions
Surface	SDL::LoadBMP (IOStreamBase &src)
	Load a BMP image from a seekable SDL data stream.

Surface	SDL::LoadBMP (StringParam file)
	Load a BMP image from a file.

void	SDL::SaveBMP (SurfaceBase &surface, IOStreamBase &dst)
	Save a surface to a seekable SDL data stream in BMP format.

void	SDL::SaveBMP (SurfaceBase &surface, StringParam file)
	Save a surface to a file.

void	SDL::ConvertPixels (int width, int height, PixelFormat src_format, const void src, int src_pitch, PixelFormat dst_format, void dst, int dst_pitch)
	Copy a block of pixels of one format to another format.

void	SDL::ConvertPixelsAndColorspace (int width, int height, PixelFormat src_format, Colorspace src_colorspace, PropertiesBase &src_properties, const void src, int src_pitch, PixelFormat dst_format, Colorspace dst_colorspace, PropertiesBase &dst_properties, void dst, int dst_pitch)
	Copy a block of pixels of one format and colorspace to another format and colorspace.

void	SDL::PremultiplyAlpha (int width, int height, PixelFormat src_format, const void src, int src_pitch, PixelFormat dst_format, void dst, int dst_pitch, bool linear)
	Premultiply the alpha on a block of pixels.

Surface	SDL::SurfaceBase::Duplicate () const
	Creates a new surface identical to the existing surface.

Surface	SDL::SurfaceBase::Scale (int width, int height, ScaleMode scaleMode) const
	Creates a new surface identical to the existing surface, scaled to the desired size.

Surface	SDL::SurfaceBase::Convert (PixelFormat format) const
	Copy an existing surface to a new surface of the specified format.

Surface	SDL::SurfaceBase::Convert (PixelFormat format, PaletteBase &palette, Colorspace colorspace, PropertiesBase &props) const
	Copy an existing surface to a new surface of the specified format and colorspace.

Variables
constexpr SurfaceFlags	SDL::SURFACE_PREALLOCATED
	Surface uses preallocated pixel memory.

constexpr SurfaceFlags	SDL::SURFACE_LOCK_NEEDED
	Surface needs to be locked to access pixels.

constexpr SurfaceFlags	SDL::SURFACE_LOCKED
	Surface is currently locked.

constexpr SurfaceFlags	SDL::SURFACE_SIMD_ALIGNED = SDL_SURFACE_SIMD_ALIGNED
	Surface uses pixel memory allocated with aligned_alloc()

constexpr ScaleMode	SDL::SCALEMODE_INVALID = SDL_SCALEMODE_INVALID

constexpr ScaleMode	SDL::SCALEMODE_NEAREST
	nearest pixel sampling

constexpr ScaleMode	SDL::SCALEMODE_LINEAR
	linear filtering

constexpr FlipMode	SDL::FLIP_NONE = SDL_FLIP_NONE
	Do not flip.

constexpr FlipMode	SDL::FLIP_HORIZONTAL = SDL_FLIP_HORIZONTAL
	flip horizontally

constexpr FlipMode	SDL::FLIP_VERTICAL = SDL_FLIP_VERTICAL
	flip vertically

Detailed Description

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

Typedef Documentation

◆ FlipMode

using SDL::FlipMode = typedef SDL_FlipMode

Since: This enum is available since SDL 3.2.0.

◆ ScaleMode

using SDL::ScaleMode = typedef SDL_ScaleMode

Since: This enum is available since SDL 3.2.0.

◆ SurfaceFlags

using SDL::SurfaceFlags = typedef Uint32

These are generally considered read-only.

Since: This datatype is available since SDL 3.2.0.

Function Documentation

◆ Convert() [1/2]

Surface SDL::SurfaceBase::Convert ( PixelFormat format ) const

inline

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 SurfaceBase.Convert() instead.

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

Parameters

format the new pixel format.

Returns: the new SurfaceBase structure that is created or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.Convert; SurfaceRef.reset

◆ Convert() [2/2]

Surface SDL::SurfaceBase::Convert	(	PixelFormat	format,
		PaletteBase &	palette,
		Colorspace	colorspace,
		PropertiesBase &	props
	)		const

inline

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.

Parameters

format	the new pixel format.
palette	an optional palette to use for indexed formats, may be nullptr.
colorspace	the new colorspace.
props	an PropertiesBase with additional color properties, or 0.

Returns: the new SurfaceBase structure that is created or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.Convert; SurfaceRef.reset

◆ ConvertPixels()

void SDL::ConvertPixels	(	int	width,
		int	height,
		PixelFormat	src_format,
		const void *	src,
		int	src_pitch,
		PixelFormat	dst_format,
		void *	dst,
		int	dst_pitch
	)

inline

Parameters

width	the width of the block to copy, in pixels.
height	the height of the block to copy, in pixels.
src_format	an 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 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.

Exceptions

Error on failure.

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.

Since: This function is available since SDL 3.2.0.

See also: ConvertPixelsAndColorspace

◆ ConvertPixelsAndColorspace()

void SDL::ConvertPixelsAndColorspace	(	int	width,
		int	height,
		PixelFormat	src_format,
		Colorspace	src_colorspace,
		PropertiesBase &	src_properties,
		const void *	src,
		int	src_pitch,
		PixelFormat	dst_format,
		Colorspace	dst_colorspace,
		PropertiesBase &	dst_properties,
		void *	dst,
		int	dst_pitch
	)

inline

Parameters

width	the width of the block to copy, in pixels.
height	the height of the block to copy, in pixels.
src_format	an PixelFormat value of the `src` pixels format.
src_colorspace	an Colorspace value describing the colorspace of the `src` pixels.
src_properties	an PropertiesBase 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 PixelFormat value of the `dst` pixels format.
dst_colorspace	an Colorspace value describing the colorspace of the `dst` pixels.
dst_properties	an PropertiesBase 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.

Exceptions

Error on failure.

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.

Since: This function is available since SDL 3.2.0.

See also: ConvertPixels

◆ Duplicate()

Surface SDL::SurfaceBase::Duplicate ( ) const

inline

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

Returns: a copy of the surface or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SurfaceRef.reset

◆ LoadBMP() [1/2]

Surface SDL::LoadBMP ( IOStreamBase & src )

inline

Parameters

src	the data stream for the surface.

Returns: a Surface with the loaded content or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SaveBMP

◆ LoadBMP() [2/2]

Surface SDL::LoadBMP ( StringParam file )

inline

Parameters

file	the BMP file to load.

Returns: a Surface with the loaded content or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SaveBMP

◆ PremultiplyAlpha()

void SDL::PremultiplyAlpha	(	int	width,
		int	height,
		PixelFormat	src_format,
		const void *	src,
		int	src_pitch,
		PixelFormat	dst_format,
		void *	dst,
		int	dst_pitch,
		bool	linear
	)

inline

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

Parameters

width	the width of the block to convert, in pixels.
height	the height of the block to convert, in pixels.
src_format	an 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 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.

Exceptions

Error on failure.

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.

Since: This function is available since SDL 3.2.0.

◆ SaveBMP() [1/2]

void SDL::SaveBMP	(	SurfaceBase &	surface,
		IOStreamBase &	dst
	)

inline

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.

Parameters

surface	the SurfaceBase structure containing the image to be saved.
dst	a data stream to save to.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: LoadBMP

◆ SaveBMP() [2/2]

void SDL::SaveBMP	(	SurfaceBase &	surface,
		StringParam	file
	)

inline

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.

Parameters

surface	the SurfaceBase structure containing the image to be saved.
file	a file to save to.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: LoadBMP

◆ Scale()

Surface SDL::SurfaceBase::Scale	(	int	width,
		int	height,
		ScaleMode	scaleMode
	)		const

inline

Parameters

width	the width of the new surface.
height	the height of the new surface.
scaleMode	the ScaleMode to be used.

Returns: a copy of the surface or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SurfaceRef.reset

Variable Documentation

◆ SCALEMODE_INVALID

constexpr ScaleMode SDL::SCALEMODE_INVALID = SDL_SCALEMODE_INVALID

constexpr

Since: SDL 3.2.10

◆ SCALEMODE_LINEAR

constexpr ScaleMode SDL::SCALEMODE_LINEAR

constexpr

Initial value:

=

SDL_SCALEMODE_LINEAR

◆ SCALEMODE_NEAREST

constexpr ScaleMode SDL::SCALEMODE_NEAREST

constexpr

Initial value:

=

SDL_SCALEMODE_NEAREST

◆ SURFACE_LOCK_NEEDED

constexpr SurfaceFlags SDL::SURFACE_LOCK_NEEDED

constexpr

Initial value:

=

SDL_SURFACE_LOCK_NEEDED

◆ SURFACE_LOCKED

constexpr SurfaceFlags SDL::SURFACE_LOCKED

constexpr

Initial value:

=

SDL_SURFACE_LOCKED

◆ SURFACE_PREALLOCATED

constexpr SurfaceFlags SDL::SURFACE_PREALLOCATED

constexpr

Initial value:

=

SDL_SURFACE_PREALLOCATED

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ FlipMode

◆ ScaleMode

◆ SurfaceFlags

Function Documentation

◆ Convert() [1/2]

◆ Convert() [2/2]

◆ ConvertPixels()

◆ ConvertPixelsAndColorspace()

◆ Duplicate()

◆ LoadBMP() [1/2]

◆ LoadBMP() [2/2]

◆ PremultiplyAlpha()

◆ SaveBMP() [1/2]

◆ SaveBMP() [2/2]

◆ Scale()

Variable Documentation

◆ SCALEMODE_INVALID

◆ SCALEMODE_LINEAR

◆ SCALEMODE_NEAREST

◆ SURFACE_LOCK_NEEDED

◆ SURFACE_LOCKED

◆ SURFACE_PREALLOCATED