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

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

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

struct	SDL::SurfaceUnsafe
	Unsafe Handle to surface. More...

struct	SDL::SurfaceLock
	Locks a Surface. More...

Typedefs
using	SDL::SurfaceShared = ResourceShared< Surface >
	Handle to a shared surface.

using	SDL::SurfaceWeak = ResourceWeak< Surface >
	Weak handle to a shared surface.

using	SDL::SurfaceFlags = Uint32
	The flags on an Surface.

using	SDL::ScaleMode = SDL_ScaleMode
	The scaling mode.

using	SDL::FlipMode = SDL_FlipMode
	The flip mode.

Functions
void	SDL::SaveBMP (SurfaceRef surface, IOStreamRef dst)
	Save a surface to a seekable SDL data stream in BMP format.

void	SDL::SaveBMP (SurfaceRef 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, PropertiesRef src_properties, const void src, int src_pitch, PixelFormat dst_format, Colorspace dst_colorspace, PropertiesRef 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.

SurfaceShared	SDL::Surface::share ()
	Move this surface into a SurfaceShared.

SurfaceLock	SDL::SurfaceRef::Lock () &
	Set up a surface for directly accessing the pixels.

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

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

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

Surface	SDL::SurfaceRef::Convert (PixelFormat format, PaletteRef palette, Colorspace colorspace, PropertiesRef 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
	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.

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, Surface.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.

◆ SurfaceShared

using SDL::SurfaceShared = typedef ResourceShared<Surface>

Category:: Resource

See also: SurfaceRef; Surface

◆ SurfaceWeak

using SDL::SurfaceWeak = typedef ResourceWeak<Surface>

Category:: Resource

See also: SurfaceShared; SurfaceRef

Function Documentation

◆ Convert() [1/2]

Surface SDL::SurfaceRef::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 SurfaceRef.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 SurfaceRef 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: SurfaceRef.Convert; Surface.Destroy

◆ Convert() [2/2]

Surface SDL::SurfaceRef::Convert	(	PixelFormat	format,
		PaletteRef	palette,
		Colorspace	colorspace,
		PropertiesRef	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 PropertiesRef with additional color properties, or 0.

Returns: the new SurfaceRef 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: SurfaceRef.Convert; Surface.Destroy

◆ 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,
		PropertiesRef	src_properties,
		const void *	src,
		int	src_pitch,
		PixelFormat	dst_format,
		Colorspace	dst_colorspace,
		PropertiesRef	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 Properties 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 Properties 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::SurfaceRef::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: Surface.Destroy

◆ Lock()

SurfaceLock SDL::SurfaceRef::Lock ( ) &

inline

Between calls to SurfaceRef.Lock() / SurfaceLock.Unlock(), 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 SurfaceLock.Unlock() to release it or let the destructor take care of this for you.

Not all surfaces require locking. If SurfaceRef.MustLock(surface) evaluates to false, then you can read and write to the surface at any time, and the pixel format of the surface will not change.

Returns: SurfaceLock object on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SurfaceRef.MustLock; SurfaceLock.Unlock

◆ 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	(	SurfaceRef	surface,
		IOStreamRef	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 Surface 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: Surface.LoadBMP; SaveBMP

◆ SaveBMP() [2/2]

void SDL::SaveBMP	(	SurfaceRef	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 Surface 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: Surface.LoadBMP; SaveBMP

◆ Scale()

Surface SDL::SurfaceRef::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: Surface.Destroy

SDL_SURFACE_PREALLOCATED

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ FlipMode

◆ ScaleMode

◆ SurfaceFlags

◆ SurfaceShared

◆ SurfaceWeak

Function Documentation

◆ Convert() [1/2]

◆ Convert() [2/2]

◆ ConvertPixels()

◆ ConvertPixelsAndColorspace()

◆ Duplicate()

◆ Lock()

◆ PremultiplyAlpha()

◆ SaveBMP() [1/2]

◆ SaveBMP() [2/2]

◆ Scale()

Variable Documentation

◆ SCALEMODE_LINEAR

◆ SCALEMODE_NEAREST

◆ SURFACE_LOCK_NEEDED

◆ SURFACE_LOCKED

◆ SURFACE_PREALLOCATED