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

Namespaces
namespace	SDL::prop
	Constants for Properties keys.
namespace	SDL::prop::Surface
	Properties for Surface.

Classes
struct	SDL::Surface
	A collection of pixels used in software blitting. More...
class	SDL::SurfaceLock
	Set up a surface for directly accessing the pixels. More...

Typedefs
using	SDL::SurfaceRaw = SDL_Surface*
	Alias to raw representation for Surface.
using	SDL::SurfaceRawConst = const SDL_Surface*
	Alias to const raw representation for Surface.
using	SDL::SurfaceRef = ResourceRef<Surface>
	Reference for Surface.
using	SDL::SurfaceConstRef = ResourceConstRef<SurfaceRaw, SurfaceRawConst>
	Safely wrap Surface for non owning const parameters.
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
constexpr bool	SDL::MustLock (SurfaceConstRef S)
	Evaluates to true if the surface needs to be locked before access.
Surface	SDL::CreateSurface (const PointRaw &size, PixelFormat format)
	Allocate a new surface with a specific pixel format.
Surface	SDL::CreateSurfaceFrom (const PointRaw &size, PixelFormat format, void *pixels, int pitch)
	Allocate a new surface with a specific pixel format and existing pixel data.
void	SDL::DestroySurface (SurfaceRaw surface)
	Free a surface.
PropertiesRef	SDL::GetSurfaceProperties (SurfaceConstRef surface)
	Get the properties associated with a surface.
void	SDL::SetSurfaceColorspace (SurfaceRef surface, Colorspace colorspace)
	Set the colorspace used by a surface.
Colorspace	SDL::GetSurfaceColorspace (SurfaceConstRef surface)
	Get the colorspace used by a surface.
Palette	SDL::CreateSurfacePalette (SurfaceRef surface)
	Create a palette and associate it with a surface.
void	SDL::SetSurfacePalette (SurfaceRef surface, PaletteRef palette)
	Set the palette used by a surface.
Palette	SDL::GetSurfacePalette (SurfaceConstRef surface)
	Get the palette used by a surface.
void	SDL::AddSurfaceAlternateImage (SurfaceRef surface, SurfaceRef image)
	Add an alternate version of a surface.
bool	SDL::SurfaceHasAlternateImages (SurfaceConstRef surface)
	Return whether a surface has alternate versions available.
OwnArray< SurfaceRaw >	SDL::GetSurfaceImages (SurfaceConstRef surface)
	Get an array including all versions of a surface.
void	SDL::RemoveSurfaceAlternateImages (SurfaceRef surface)
	Remove all alternate versions of a surface.
void	SDL::LockSurface (SurfaceRef surface)
	Set up a surface for directly accessing the pixels.
void	SDL::UnlockSurface (SurfaceRef surface)
	Release a surface after directly accessing the pixels.
Surface	SDL::LoadBMP_IO (IOStreamRef src, bool closeio=false)
	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_IO (SurfaceConstRef surface, IOStreamRef dst, bool closeio=false)
	Save a surface to a seekable SDL data stream in BMP format.
void	SDL::SaveBMP (SurfaceConstRef surface, StringParam file)
	Save a surface to a file in BMP format.
Surface	SDL::LoadTrustedPNG_IO (IOStreamRef src, bool closeio=false)
	Load a PNG image from a seekable SDL data stream.
Surface	SDL::LoadTrustedPNG (StringParam file)
	Load a PNG image from a file.
void	SDL::SaveTrustedPNG_IO (SurfaceConstRef surface, IOStreamRef dst, bool closeio=false)
	Save a surface to a seekable SDL data stream in PNG format.
void	SDL::SaveTrustedPNG (SurfaceConstRef surface, StringParam file)
	Save a surface to a file in PNG format.
void	SDL::SetSurfaceRLE (SurfaceRef surface, bool enabled)
	Set the RLE acceleration hint for a surface.
bool	SDL::SurfaceHasRLE (SurfaceConstRef surface)
	Returns whether the surface is RLE enabled.
void	SDL::SetSurfaceColorKey (SurfaceRef surface, std::optional< Uint32 > key)
	Set the color key (transparent pixel) in a surface.
void	SDL::ClearSurfaceColorKey (SurfaceRef surface)
	Unset the color key (transparent pixel) in a surface.
bool	SDL::SurfaceHasColorKey (SurfaceConstRef surface)
	Returns whether the surface has a color key.
std::optional< Uint32 >	SDL::GetSurfaceColorKey (SurfaceConstRef surface)
	Get the color key (transparent pixel) for a surface.
void	SDL::SetSurfaceColorMod (SurfaceRef surface, Uint8 r, Uint8 g, Uint8 b)
	Set an additional color value multiplied into blit operations.
void	SDL::GetSurfaceColorMod (SurfaceConstRef surface, Uint8 r, Uint8 g, Uint8 *b)
	Get the additional color value multiplied into blit operations.
void	SDL::SetSurfaceAlphaMod (SurfaceRef surface, Uint8 alpha)
	Set an additional alpha value used in blit operations.
Uint8	SDL::GetSurfaceAlphaMod (SurfaceConstRef surface)
	Get the additional alpha value used in blit operations.
void	SDL::SetSurfaceMod (SurfaceRef surface, Color color)
	Set an additional color and alpha value multiplied into blit operations.
Color	SDL::GetSurfaceMod (SurfaceConstRef surface)
	Get the additional color and alpha value multiplied into blit operations.
void	SDL::SetSurfaceBlendMode (SurfaceRef surface, BlendMode blendMode)
	Set the blend mode used for blit operations.
BlendMode	SDL::GetSurfaceBlendMode (SurfaceConstRef surface)
	Get the blend mode used for blit operations.
bool	SDL::SetSurfaceClipRect (SurfaceRef surface, OptionalRef< const RectRaw > rect)
	Set the clipping rectangle for a surface.
void	SDL::ResetSurfaceClipRect (SurfaceRef surface)
	Disable the clipping rectangle for a surface.
Rect	SDL::GetSurfaceClipRect (SurfaceConstRef surface)
	Get the clipping rectangle for a surface.
void	SDL::FlipSurface (SurfaceRef surface, FlipMode flip)
	Flip a surface vertically or horizontally.
Surface	SDL::RotateSurface (SurfaceRef surface, float angle)
	Return a copy of a surface rotated clockwise a number of degrees.
Surface	SDL::DuplicateSurface (SurfaceConstRef surface)
	Creates a new surface identical to the existing surface.
Surface	SDL::ScaleSurface (SurfaceConstRef surface, const PointRaw &size, ScaleMode scaleMode)
	Creates a new surface identical to the existing surface, scaled to the desired size.
Surface	SDL::ConvertSurface (SurfaceConstRef surface, PixelFormat format)
	Copy an existing surface to a new surface of the specified format.
Surface	SDL::ConvertSurfaceAndColorspace (SurfaceConstRef surface, PixelFormat format, PaletteRef palette, Colorspace colorspace, PropertiesRef props)
	Copy an existing surface to a new surface of the specified format and colorspace.
void	SDL::ConvertPixels (const PointRaw &size, 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 (const PointRaw &size, 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 (const PointRaw &size, 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.
void	SDL::PremultiplySurfaceAlpha (SurfaceRef surface, bool linear)
	Premultiply the alpha in a surface.
void	SDL::ClearSurface (SurfaceRef surface, const FColorRaw &c)
	Clear a surface with a specific color, with floating point precision.
void	SDL::FillSurfaceRect (SurfaceRef dst, OptionalRef< const RectRaw > rect, Uint32 color)
	Perform a fast fill of a rectangle with a specific color.
void	SDL::FillSurface (SurfaceRef dst, Uint32 color)
	Perform a fast fill of a rectangle with a specific color.
void	SDL::FillSurfaceRects (SurfaceRef dst, SpanRef< const RectRaw > rects, Uint32 color)
	Perform a fast fill of a set of rectangles with a specific color.
void	SDL::BlitSurface (SurfaceRef src, OptionalRef< const RectRaw > srcrect, SurfaceRef dst, OptionalRef< const RectRaw > dstrect)
	Performs a fast blit from the source surface to the destination surface with clipping.
void	SDL::BlitSurfaceAt (SurfaceRef src, OptionalRef< const RectRaw > srcrect, SurfaceRef dst, const PointRaw &dstpos)
	Performs a fast blit from the source surface to the destination surface with clipping.
void	SDL::BlitSurfaceUnchecked (SurfaceRef src, const RectRaw &srcrect, SurfaceRef dst, const RectRaw &dstrect)
	Perform low-level surface blitting only.
void	SDL::BlitSurfaceScaled (SurfaceRef src, OptionalRef< const RectRaw > srcrect, SurfaceRef dst, OptionalRef< const RectRaw > dstrect, ScaleMode scaleMode)
	Perform a scaled blit to a destination surface, which may be of a different format.
void	SDL::BlitSurfaceUncheckedScaled (SurfaceRef src, const RectRaw &srcrect, SurfaceRef dst, const RectRaw &dstrect, ScaleMode scaleMode)
	Perform low-level surface scaled blitting only.
void	SDL::StretchSurface (SurfaceRef src, OptionalRef< RectRaw > srcrect, SurfaceRef dst, OptionalRef< RectRaw > dstrect, ScaleMode scaleMode)
	Perform a stretched pixel copy from one surface to another.
void	SDL::BlitSurfaceTiled (SurfaceRef src, OptionalRef< const RectRaw > srcrect, SurfaceRef dst, OptionalRef< const RectRaw > dstrect)
	Perform a tiled blit to a destination surface, which may be of a different format.
void	SDL::BlitSurfaceTiledWithScale (SurfaceRef src, OptionalRef< const RectRaw > srcrect, float scale, ScaleMode scaleMode, SurfaceRef dst, OptionalRef< const RectRaw > dstrect)
	Perform a scaled and tiled blit to a destination surface, which may be of a different format.
void	SDL::BlitSurface9Grid (SurfaceRef src, OptionalRef< const RectRaw > srcrect, int left_width, int right_width, int top_height, int bottom_height, SurfaceRef dst, OptionalRef< const RectRaw > dstrect, float scale=1, ScaleMode scaleMode=SCALEMODE_NEAREST)
	Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.
Uint32	SDL::MapSurfaceRGB (SurfaceConstRef surface, Uint8 r, Uint8 g, Uint8 b)
	Map an RGB triple to an opaque pixel value for a surface.
Uint32	SDL::MapSurfaceRGBA (SurfaceConstRef surface, ColorRaw c)
	Map an RGBA quadruple to a pixel value for a surface.
void	SDL::ReadSurfacePixel (SurfaceConstRef surface, const PointRaw &p, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
	Retrieves a single pixel from a surface.
Color	SDL::ReadSurfacePixel (SurfaceConstRef surface, const PointRaw &p)
	Retrieves a single pixel from a surface.
void	SDL::ReadSurfacePixel (const SurfaceLock &lock, const PointRaw &p, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
	Retrieves a single pixel from a surface.
Color	SDL::ReadSurfacePixel (const SurfaceLock &lock, const PointRaw &p)
	Retrieves a single pixel from a surface.
void	SDL::ReadSurfacePixelFloat (SurfaceConstRef surface, const PointRaw &p, float r, float g, float b, float a)
	Retrieves a single pixel from a surface.
FColor	SDL::ReadSurfacePixelFloat (SurfaceConstRef surface, const PointRaw &p)
	Retrieves a single pixel from a surface.
void	SDL::ReadSurfacePixelFloat (const SurfaceLock &lock, const PointRaw &p, float r, float g, float b, float a)
	Retrieves a single pixel from a surface.
FColor	SDL::ReadSurfacePixelFloat (const SurfaceLock &lock, const PointRaw &p)
	Retrieves a single pixel from a surface.
void	SDL::WriteSurfacePixel (SurfaceRef surface, const PointRaw &p, ColorRaw c)
	Writes a single pixel to a surface.
void	SDL::WriteSurfacePixel (SurfaceLock &lock, const PointRaw &p, ColorRaw c)
	Writes a single pixel to a surface.
void	SDL::WriteSurfacePixelFloat (SurfaceRef surface, const PointRaw &p, const FColorRaw &c)
	Writes a single pixel to a surface.
void	SDL::WriteSurfacePixelFloat (SurfaceLock &lock, const PointRaw &p, const FColorRaw &c)
	Writes a single pixel to a surface.
constexpr int	SDL::GetSurfaceWidth (SurfaceConstRef surface)
	Get the width in pixels.
constexpr int	SDL::GetSurfaceWidth (const SurfaceLock &lock)
	Get the width in pixels.
constexpr int	SDL::GetSurfaceHeight (SurfaceConstRef surface)
	Get the height in pixels.
constexpr int	SDL::GetSurfaceHeight (const SurfaceLock &lock)
	Get the height in pixels.
constexpr Point	SDL::GetSurfaceSize (SurfaceConstRef surface)
	Get the size in pixels.
constexpr Point	SDL::GetSurfaceSize (const SurfaceLock &lock)
	Get the size in pixels.
constexpr int	SDL::GetSurfacePitch (SurfaceConstRef surface)
	Get pitch in bytes.
constexpr int	SDL::GetSurfacePitch (const SurfaceLock &lock)
	Get pitch in bytes.
constexpr PixelFormat	SDL::GetSurfaceFormat (SurfaceConstRef surface)
	Get the pixel format.
constexpr PixelFormat	SDL::GetSurfaceFormat (const SurfaceLock &lock)
	Get the pixel format.
constexpr void *	SDL::GetSurfacePixels (SurfaceConstRef surface)
	Get the pixels.
constexpr void *	SDL::GetSurfacePixels (const SurfaceLock &lock)
	Get the pixels.
	SDL::Surface::Surface (const PointRaw &size, PixelFormat format)
	Allocate a new surface with a specific pixel format.
	SDL::Surface::Surface (const PointRaw &size, PixelFormat format, void *pixels, int pitch)
	Allocate a new surface with a specific pixel format and existing pixel data.
void	SDL::Surface::Destroy ()
	Free this surface.
PropertiesRef	SDL::Surface::GetProperties () const
	Get the properties associated with a surface.
void	SDL::Surface::SetColorspace (Colorspace colorspace)
	Set the colorspace used by a surface.
Colorspace	SDL::Surface::GetColorspace () const
	Get the colorspace used by a surface.
Palette	SDL::Surface::CreatePalette ()
	Create a palette and associate it with a surface.
void	SDL::Surface::SetPalette (PaletteRef palette)
	Set the palette used by a surface.
Palette	SDL::Surface::GetPalette () const
	Get the palette used by a surface.
void	SDL::Surface::AddAlternateImage (SurfaceRef image)
	Add an alternate version of a surface.
bool	SDL::Surface::HasAlternateImages () const
	Return whether a surface has alternate versions available.
OwnArray< SurfaceRaw >	SDL::Surface::GetImages () const
	Get an array including all versions of a surface.
void	SDL::Surface::RemoveAlternateImages ()
	Remove all alternate versions of a surface.
SurfaceLock	SDL::Surface::Lock ()
	Set up a surface for directly accessing the pixels.
	SDL::SurfaceLock::SurfaceLock (SurfaceRef resource)
	Set up a surface for directly accessing the pixels.
void	SDL::Surface::Unlock (SurfaceLock &&lock)
	Release a surface after directly accessing the pixels.
void	SDL::SurfaceLock::reset ()
	Release a surface after directly accessing the pixels.
void	SDL::Surface::SaveBMP_IO (IOStreamRef dst, bool closeio=false) const
	Save a surface to a seekable SDL data stream in BMP format.
void	SDL::Surface::SaveBMP (StringParam file) const
	Save a surface to a file in BMP format.
void	SDL::Surface::SetRLE (bool enabled)
	Set the RLE acceleration hint for a surface.
bool	SDL::Surface::HasRLE () const
	Returns whether the surface is RLE enabled.
void	SDL::Surface::SetColorKey (std::optional< Uint32 > key)
	Set the color key (transparent pixel) in a surface.
void	SDL::Surface::ClearColorKey ()
	Unset the color key (transparent pixel) in a surface.
bool	SDL::Surface::HasColorKey () const
	Returns whether the surface has a color key.
std::optional< Uint32 >	SDL::Surface::GetColorKey () const
	Get the color key (transparent pixel) for a surface.
void	SDL::Surface::SetColorMod (Uint8 r, Uint8 g, Uint8 b)
	Set an additional color value multiplied into blit operations.
void	SDL::Surface::GetColorMod (Uint8 r, Uint8 g, Uint8 *b) const
	Get the additional color value multiplied into blit operations.
void	SDL::Surface::SetAlphaMod (Uint8 alpha)
	Set an additional alpha value used in blit operations.
Uint8	SDL::Surface::GetAlphaMod () const
	Get the additional alpha value used in blit operations.
void	SDL::Surface::SetMod (Color color)
	Set an additional color and alpha value multiplied into blit operations.
Color	SDL::Surface::GetMod () const
	Get the additional color and alpha value multiplied into blit operations.
void	SDL::Surface::SetBlendMode (BlendMode blendMode)
	Set the blend mode used for blit operations.
BlendMode	SDL::Surface::GetBlendMode () const
	Get the blend mode used for blit operations.
bool	SDL::Surface::SetClipRect (OptionalRef< const RectRaw > rect)
	Set the clipping rectangle for a surface.
void	SDL::Surface::ResetClipRect ()
	Disable the clipping rectangle for a surface.
Rect	SDL::Surface::GetClipRect () const
	Get the clipping rectangle for a surface.
void	SDL::Surface::Flip (FlipMode flip)
	Flip a surface vertically or horizontally.
Surface	SDL::Surface::Rotate (float angle)
	Return a copy of a surface rotated clockwise a number of degrees.
Surface	SDL::Surface::Duplicate () const
	Creates a new surface identical to the existing surface.
Surface	SDL::Surface::Scale (const PointRaw &size, ScaleMode scaleMode) const
	Creates a new surface identical to the existing surface, scaled to the desired size.
Surface	SDL::Surface::Convert (PixelFormat format) const
	Copy an existing surface to a new surface of the specified format.
Surface	SDL::Surface::Convert (PixelFormat format, PaletteRef palette, Colorspace colorspace, PropertiesRef props) const
	Copy an existing surface to a new surface of the specified format and colorspace.
void	SDL::Surface::PremultiplyAlpha (bool linear)
	Premultiply the alpha in a surface.
void	SDL::Surface::Clear (const FColorRaw &c)
	Clear a surface with a specific color, with floating point precision.
void	SDL::Surface::FillRect (OptionalRef< const RectRaw > rect, Uint32 color)
	Perform a fast fill of a rectangle with a specific color.
void	SDL::Surface::Fill (Uint32 color)
	Perform a fast fill of a rectangle with a specific color.
void	SDL::Surface::FillRects (SpanRef< const RectRaw > rects, Uint32 color)
	Perform a fast fill of a set of rectangles with a specific color.
void	SDL::Surface::Blit (SurfaceRef src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect)
	Performs a fast blit from the source surface to the destination surface with clipping.
void	SDL::Surface::BlitAt (SurfaceRef src, OptionalRef< const RectRaw > srcrect, const PointRaw &dstpos)
	Performs a fast blit from the source surface to the destination surface with clipping.
void	SDL::Surface::BlitUnchecked (SurfaceRef src, const RectRaw &srcrect, const RectRaw &dstrect)
	Perform low-level surface blitting only.
void	SDL::Surface::BlitScaled (SurfaceRef src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect, ScaleMode scaleMode)
	Perform a scaled blit to a destination surface, which may be of a different format.
void	SDL::Surface::BlitUncheckedScaled (SurfaceRef src, const RectRaw &srcrect, const RectRaw &dstrect, ScaleMode scaleMode)
	Perform low-level surface scaled blitting only.
void	SDL::Surface::Stretch (SurfaceRef src, OptionalRef< RectRaw > srcrect, OptionalRef< RectRaw > dstrect, ScaleMode scaleMode)
	Perform a stretched pixel copy from one surface to another.
void	SDL::Surface::BlitTiled (SurfaceRef src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect)
	Perform a tiled blit to a destination surface, which may be of a different format.
void	SDL::Surface::BlitTiledWithScale (SurfaceRef src, OptionalRef< const RectRaw > srcrect, float scale, ScaleMode scaleMode, OptionalRef< const RectRaw > dstrect)
	Perform a scaled and tiled blit to a destination surface, which may be of a different format.
void	SDL::Surface::Blit9Grid (SurfaceRef src, OptionalRef< const RectRaw > srcrect, int left_width, int right_width, int top_height, int bottom_height, OptionalRef< const RectRaw > dstrect, float scale=1, ScaleMode scaleMode=SCALEMODE_NEAREST)
	Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format.
Uint32	SDL::Surface::MapRGB (Uint8 r, Uint8 g, Uint8 b) const
	Map an RGB triple to an opaque pixel value for a surface.
Uint32	SDL::Surface::MapRGBA (ColorRaw c) const
	Map an RGBA quadruple to a pixel value for a surface.
void	SDL::Surface::ReadPixel (const PointRaw &p, Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
	Retrieves a single pixel from a surface.
Color	SDL::Surface::ReadPixel (const PointRaw &p) const
	Retrieves a single pixel from a surface.
void	SDL::Surface::ReadPixelFloat (const PointRaw &p, float r, float g, float b, float a) const
	Retrieves a single pixel from a surface.
FColor	SDL::Surface::ReadPixelFloat (const PointRaw &p) const
	Retrieves a single pixel from a surface.
void	SDL::Surface::WritePixel (const PointRaw &p, ColorRaw c)
	Writes a single pixel to a surface.
void	SDL::Surface::WritePixelFloat (const PointRaw &p, const FColorRaw &c)
	Writes a single pixel to a surface.
constexpr int	SDL::Surface::GetWidth () const
	Get the width in pixels.
constexpr int	SDL::Surface::GetHeight () const
	Get the height in pixels.
constexpr Point	SDL::Surface::GetSize () const
	Get the size in pixels.
constexpr int	SDL::Surface::GetPitch () const
	Get pitch in bytes.
constexpr PixelFormat	SDL::Surface::GetFormat () const
	Get the pixel format.
constexpr void *	SDL::Surface::GetPixels () const
	Get the pixels.

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 ScaleMode	SDL::SCALEMODE_PIXELART = SDL_SCALEMODE_PIXELART
	nearest pixel sampling with improved scaling for pixel art, available since SDL 3.4.0
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
constexpr FlipMode	SDL::FLIP_HORIZONTAL_AND_VERTICAL
	flip horizontally and vertically (not a diagonal flip)

Detailed Description

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.

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, LoadBMP(), and a simple .png loader, LoadTrustedPNG(). SDL itself does not provide loaders for other file formats, but there are several excellent external libraries that do, including its own satellite library, SDL_image .

In general these functions are thread-safe in that they can be called on different threads with different surfaces. You should not try to modify any surface from two threads simultaneously.

Typedef Documentation

◆ FlipMode

using SDL::FlipMode = SDL_FlipMode

The flip mode.

Since: This enum is available since SDL 3.2.0.

◆ ScaleMode

using SDL::ScaleMode = SDL_ScaleMode

The scaling mode.

Since: This enum is available since SDL 3.2.0.

◆ SurfaceFlags

using SDL::SurfaceFlags = Uint32

The flags on an Surface.

These are generally considered read-only.

Since: This datatype is available since SDL 3.2.0.

◆ SurfaceRef

using SDL::SurfaceRef = ResourceRef<Surface>

Reference for Surface.

This does not take ownership!

Function Documentation

◆ AddAlternateImage()

void SDL::Surface::AddAlternateImage ( SurfaceRef image )

inline

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 Surface.Destroy() on the image after this call.

Parameters

image an alternate Surface to associate with this surface.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.RemoveAlternateImages; Surface.GetImages; Surface.HasAlternateImages

◆ AddSurfaceAlternateImage()

void SDL::AddSurfaceAlternateImage	(	SurfaceRef	surface,
		SurfaceRef	image )

inline

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 Surface.Destroy() on the image after this call.

Parameters

surface	the Surface structure to update.
image	a pointer to an alternate Surface to associate with this surface.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.RemoveAlternateImages; Surface.GetImages; Surface.HasAlternateImages

◆ Blit()

void SDL::Surface::Blit	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		OptionalRef< const RectRaw >	dstrect )

inline

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

If either srcrect or dstrect are nullptr, 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 BLENDMODE_BLEND:
    alpha-blend (using the source alpha-channel and per-surface alpha)
    SDL_SRCCOLORKEY ignored.
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source per-surface alpha)
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source alpha-channel and per-surface alpha)
    SDL_SRCCOLORKEY ignored.
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source per-surface alpha)
  Source surface blend mode set to BLENDMODE_NONE:
    copy RGB.
  both:
    if SDL_SRCCOLORKEY set, only copy the pixels that do not match the
    source color key.

Parameters

src	the SurfaceRaw structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dstrect	the Rect structure representing the x and y position in the destination surface, or nullptr 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 Surface.BlitScaled().

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.BlitScaled

◆ Blit9Grid()

void SDL::Surface::Blit9Grid	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		int	left_width,
		int	right_width,
		int	top_height,
		int	bottom_height,
		OptionalRef< const RectRaw >	dstrect,
		float	scale = 1,
		ScaleMode	scaleMode = SCALEMODE_NEAREST )

inline

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.

Parameters

src	the SDL_Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be used for the 9-grid, or nullptr 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.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire surface.
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.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitAt()

void SDL::Surface::BlitAt	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		const PointRaw &	dstpos )

inline

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

If either srcrect or dstrect are nullptr, 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 BLENDMODE_BLEND:
    alpha-blend (using the source alpha-channel and per-surface alpha)
    SDL_SRCCOLORKEY ignored.
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source per-surface alpha)
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source alpha-channel and per-surface alpha)
    SDL_SRCCOLORKEY ignored.
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source per-surface alpha)
  Source surface blend mode set to BLENDMODE_NONE:
    copy RGB.
  both:
    if SDL_SRCCOLORKEY set, only copy the pixels that do not match the
    source color key.

Parameters

src	the SurfaceRaw structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dstpos	the Point structure representing the x and y position in the destination surface, or nullptr 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 Surface.BlitScaled().

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit; Surface.BlitScaled

◆ BlitScaled()

void SDL::Surface::BlitScaled	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		OptionalRef< const RectRaw >	dstrect,
		ScaleMode	scaleMode )

inline

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

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire destination surface.
scaleMode	the ScaleMode to be used.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitSurface()

void SDL::BlitSurface	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		SurfaceRef	dst,
		OptionalRef< const RectRaw >	dstrect )

inline

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

If either srcrect or dstrect are nullptr, 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 BLENDMODE_BLEND:
    alpha-blend (using the source alpha-channel and per-surface alpha)
    SDL_SRCCOLORKEY ignored.
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source per-surface alpha)
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source alpha-channel and per-surface alpha)
    SDL_SRCCOLORKEY ignored.
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source per-surface alpha)
  Source surface blend mode set to BLENDMODE_NONE:
    copy RGB.
  both:
    if SDL_SRCCOLORKEY set, only copy the pixels that do not match the
    source color key.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dst	the Surface structure that is the blit target.
dstrect	the Rect structure representing the x and y position in the destination surface, or nullptr 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 Surface.BlitScaled().

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.BlitScaled

◆ BlitSurface9Grid()

void SDL::BlitSurface9Grid	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		int	left_width,
		int	right_width,
		int	top_height,
		int	bottom_height,
		SurfaceRef	dst,
		OptionalRef< const RectRaw >	dstrect,
		float	scale = 1,
		ScaleMode	scaleMode = SCALEMODE_NEAREST )

inline

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.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be used for the 9-grid, or nullptr 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.
dst	the Surface structure that is the blit target.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire surface.
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.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitSurfaceAt()

void SDL::BlitSurfaceAt	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		SurfaceRef	dst,
		const PointRaw &	dstpos )

inline

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

If either srcrect or dstrect are nullptr, 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 BLENDMODE_BLEND:
    alpha-blend (using the source alpha-channel and per-surface alpha)
    SDL_SRCCOLORKEY ignored.
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source per-surface alpha)
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source alpha-channel and per-surface alpha)
    SDL_SRCCOLORKEY ignored.
  Source surface blend mode set to 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 BLENDMODE_BLEND:
    alpha-blend (using the source per-surface alpha)
  Source surface blend mode set to BLENDMODE_NONE:
    copy RGB.
  both:
    if SDL_SRCCOLORKEY set, only copy the pixels that do not match the
    source color key.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dst	the Surface structure that is the blit target.
dstpos	the Point structure representing the x and y position in the destination surface.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.BlitSurface

◆ BlitSurfaceScaled()

void SDL::BlitSurfaceScaled	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		SurfaceRef	dst,
		OptionalRef< const RectRaw >	dstrect,
		ScaleMode	scaleMode )

inline

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

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dst	the Surface structure that is the blit target.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire destination surface.
scaleMode	the ScaleMode to be used.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitSurfaceTiled()

void SDL::BlitSurfaceTiled	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		SurfaceRef	dst,
		OptionalRef< const RectRaw >	dstrect )

inline

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.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dst	the Surface structure that is the blit target.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire surface.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitSurfaceTiledWithScale()

void SDL::BlitSurfaceTiledWithScale	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		float	scale,
		ScaleMode	scaleMode,
		SurfaceRef	dst,
		OptionalRef< const RectRaw >	dstrect )

inline

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.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr 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 Surface structure that is the blit target.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire surface.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitSurfaceUnchecked()

void SDL::BlitSurfaceUnchecked	(	SurfaceRef	src,
		const RectRaw &	srcrect,
		SurfaceRef	dst,
		const RectRaw &	dstrect )

inline

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.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, may not be nullptr.
dst	the Surface structure that is the blit target.
dstrect	the Rect structure representing the target rectangle in the destination surface, may not be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitSurfaceUncheckedScaled()

void SDL::BlitSurfaceUncheckedScaled	(	SurfaceRef	src,
		const RectRaw &	srcrect,
		SurfaceRef	dst,
		const RectRaw &	dstrect,
		ScaleMode	scaleMode )

inline

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.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, may not be nullptr.
dst	the Surface structure that is the blit target.
dstrect	the Rect structure representing the target rectangle in the destination surface, may not be nullptr.
scaleMode	the ScaleMode to be used.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.BlitScaled

◆ BlitTiled()

void SDL::Surface::BlitTiled	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		OptionalRef< const RectRaw >	dstrect )

inline

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.

Parameters

src	the SDL_Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire surface.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitTiledWithScale()

void SDL::Surface::BlitTiledWithScale	(	SurfaceRef	src,
		OptionalRef< const RectRaw >	srcrect,
		float	scale,
		ScaleMode	scaleMode,
		OptionalRef< const RectRaw >	dstrect )

inline

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.

Parameters

src	the SDL_Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr 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.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire surface.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitUnchecked()

void SDL::Surface::BlitUnchecked	(	SurfaceRef	src,
		const RectRaw &	srcrect,
		const RectRaw &	dstrect )

inline

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.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, may not be nullptr.
dstrect	the Rect structure representing the target rectangle in the destination surface, may not be nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit

◆ BlitUncheckedScaled()

void SDL::Surface::BlitUncheckedScaled	(	SurfaceRef	src,
		const RectRaw &	srcrect,
		const RectRaw &	dstrect,
		ScaleMode	scaleMode )

inline

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.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, may not be nullptr.
dstrect	the Rect structure representing the target rectangle in the destination surface, may not be nullptr.
scaleMode	the ScaleMode to be used.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.BlitScaled

◆ Clear()

void SDL::Surface::Clear ( const FColorRaw & c )

inline

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.

Parameters

c	the color components of the pixel, normally in the range 0-1.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ClearColorKey()

void SDL::Surface::ClearColorKey ( )

inline

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

Exceptions

Error on failure.

◆ ClearSurface()

void SDL::ClearSurface	(	SurfaceRef	surface,
		const FColorRaw &	c )

inline

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.

Parameters

surface	the Surface to clear.
c	the color components of the pixel, normally in the range 0-1.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ClearSurfaceColorKey()

void SDL::ClearSurfaceColorKey ( SurfaceRef surface )

inline

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

Parameters

surface the Surface structure to update.

Exceptions

Error on failure.

◆ Convert() [1/2]

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

inline

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 Surface.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 Surface structure that is created or nullptr on failure; call GetError() for more information.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Convert; Surface.Destroy

◆ Convert() [2/2]

Surface SDL::Surface::Convert	(	PixelFormat	format,
		PaletteRef	palette,
		Colorspace	colorspace,
		PropertiesRef	props ) const

inline

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.

Parameters

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

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

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Convert; Surface.Destroy

◆ ConvertPixels()

void SDL::ConvertPixels	(	const PointRaw &	size,
		PixelFormat	src_format,
		const void *	src,
		int	src_pitch,
		PixelFormat	dst_format,
		void *	dst,
		int	dst_pitch )

inline

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

Parameters

size	the width and height of the surface.
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	(	const PointRaw &	size,
		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

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

Parameters

size	the width and 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

◆ ConvertSurface()

Surface SDL::ConvertSurface	(	SurfaceConstRef	surface,
		PixelFormat	format )

inline

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

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

Parameters

surface	the existing Surface structure to convert.
format	the new pixel format.

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

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Convert; Surface.Destroy

◆ ConvertSurfaceAndColorspace()

Surface SDL::ConvertSurfaceAndColorspace	(	SurfaceConstRef	surface,
		PixelFormat	format,
		PaletteRef	palette,
		Colorspace	colorspace,
		PropertiesRef	props )

inline

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.

Parameters

surface	the existing Surface structure to convert.
format	the new pixel format.
palette	an optional palette to use for indexed formats, may be nullptr.
colorspace	the new colorspace.
props	an Properties with additional color properties, or 0.

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

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Convert; Surface.Destroy

◆ CreatePalette()

Palette SDL::Surface::CreatePalette ( )

inline

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 PIXELFORMAT_INDEX1LSB or 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 Palette structure on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Palette.SetColors

◆ CreateSurface()

Surface SDL::CreateSurface	(	const PointRaw &	size,
		PixelFormat	format )

inline

Allocate a new surface with a specific pixel format.

The pixels of the new surface are initialized to zero.

Parameters

size	the width and height of the surface.
format	the PixelFormat for the new surface's pixel format.

Returns: the new Surface structure that is created 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: CreateSurfaceFrom; Surface.Destroy

◆ CreateSurfaceFrom()

Surface SDL::CreateSurfaceFrom	(	const PointRaw &	size,
		PixelFormat	format,
		void *	pixels,
		int	pitch )

inline

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

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

Parameters

size	the width and height of the surface.
format	the 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 Surface structure that is created 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: CreateSurface; Surface.Destroy

◆ CreateSurfacePalette()

Palette SDL::CreateSurfacePalette ( SurfaceRef surface )

inline

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 PIXELFORMAT_INDEX1LSB or 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.

Parameters

surface the Surface structure to update.

Returns: a new Palette structure on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Palette.SetColors

◆ Destroy()

void SDL::Surface::Destroy ( )

inline

Free this surface.

It is safe to call on a nullptr surface.

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

Since: This function is available since SDL 3.2.0.

See also: CreateSurface; CreateSurfaceFrom

◆ DestroySurface()

void SDL::DestroySurface ( SurfaceRaw surface )

inline

Free a surface.

It is safe to pass nullptr to this function.

Parameters

surface the Surface to free.

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

Since: This function is available since SDL 3.2.0.

See also: CreateSurface; CreateSurfaceFrom

◆ Duplicate()

Surface SDL::Surface::Duplicate ( ) const

inline

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.

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

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Destroy

◆ DuplicateSurface()

Surface SDL::DuplicateSurface ( SurfaceConstRef surface )

inline

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

Parameters

surface the surface to duplicate.

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

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Destroy

◆ Fill()

void SDL::Surface::Fill ( Uint32 color )

inline

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

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

Parameters

color the color to fill with.

Exceptions

Error on failure.

◆ FillRect()

void SDL::Surface::FillRect	(	OptionalRef< const RectRaw >	rect,
		Uint32	color )

inline

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 MapRGB() or MapColor(). 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 Surface.SetClipRect()), then this function will fill based on the intersection of the clip rectangle and rect.

Parameters

rect	the Rect structure representing the rectangle to fill, or nullptr to fill the entire surface.
color	the color to fill with.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.FillRects

◆ FillRects()

void SDL::Surface::FillRects	(	SpanRef< const RectRaw >	rects,
		Uint32	color )

inline

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 MapRGB() or MapColor(). 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 Surface.SetClipRect()), then this function will fill based on the intersection of the clip rectangle and rect.

Parameters

rects	an array of SDL_Rects representing the rectangles to fill.
color	the color to fill with.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.FillRect

◆ FillSurface()

void SDL::FillSurface	(	SurfaceRef	dst,
		Uint32	color )

inline

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

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

Parameters

dst	the Surface structure that is the drawing target.
color	the color to fill with.

Exceptions

Error on failure.

◆ FillSurfaceRect()

void SDL::FillSurfaceRect	(	SurfaceRef	dst,
		OptionalRef< const RectRaw >	rect,
		Uint32	color )

inline

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 MapRGB() or MapColor(). 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 Surface.SetClipRect()), then this function will fill based on the intersection of the clip rectangle and rect.

Parameters

dst	the Surface structure that is the drawing target.
rect	the Rect structure representing the rectangle to fill, or nullptr to fill the entire surface.
color	the color to fill with.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.FillRects

◆ FillSurfaceRects()

void SDL::FillSurfaceRects	(	SurfaceRef	dst,
		SpanRef< const RectRaw >	rects,
		Uint32	color )

inline

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 MapRGB() or MapColor(). 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 Surface.SetClipRect()), then this function will fill based on the intersection of the clip rectangle and rect.

Parameters

dst	the Surface structure that is the drawing target.
rects	an array of SDL_Rects representing the rectangles to fill.
color	the color to fill with.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.FillRect

◆ Flip()

void SDL::Surface::Flip ( FlipMode flip )

inline

Flip a surface vertically or horizontally.

Parameters

flip	the direction to flip.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ FlipSurface()

void SDL::FlipSurface	(	SurfaceRef	surface,
		FlipMode	flip )

inline

Flip a surface vertically or horizontally.

Parameters

surface	the surface to flip.
flip	the direction to flip.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ GetAlphaMod()

Uint8 SDL::Surface::GetAlphaMod ( ) const

inline

Get the additional alpha value used in blit operations.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.GetColorMod; Surface.SetAlphaMod

◆ GetBlendMode()

BlendMode SDL::Surface::GetBlendMode ( ) const

inline

Get the blend mode used for blit operations.

Returns: the current BlendMode.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.SetBlendMode

◆ GetClipRect()

Rect SDL::Surface::GetClipRect ( ) const

inline

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: the Rect structure filled in with the clipping rectangle for the surface on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.SetClipRect

◆ GetColorKey()

std::optional< Uint32 > SDL::Surface::GetColorKey ( ) const

inline

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

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

Returns: the transparent pixel or nullopt if none.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.SetColorKey; Surface.HasColorKey

◆ GetColorMod()

void SDL::Surface::GetColorMod	(	Uint8 *	r,
		Uint8 *	g,
		Uint8 *	b ) const

inline

Get the additional color value multiplied into blit operations.

Parameters

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.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetAlphaMod; Surface.SetColorMod

◆ GetColorspace()

Colorspace SDL::Surface::GetColorspace ( ) const

inline

Get the colorspace used by a surface.

The colorspace defaults to COLORSPACE_SRGB_LINEAR for floating point formats, COLORSPACE_HDR10 for 10-bit formats, COLORSPACE_SRGB for other RGB surfaces and COLORSPACE_BT709_FULL for YUV textures.

Returns: the colorspace used by the surface, or COLORSPACE_UNKNOWN if the surface is nullptr.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.SetColorspace

◆ GetImages()

OwnArray< SurfaceRaw > SDL::Surface::GetImages ( ) const

inline

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.

Returns: a nullptr terminated array of Surface pointers or nullptr on failure; call GetError() for more information.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.AddAlternateImage; Surface.RemoveAlternateImages; Surface.HasAlternateImages

◆ GetMod()

Color SDL::Surface::GetMod ( ) const

inline

Get the additional color and alpha value multiplied into blit operations.

Returns: a Color containing RGBA value on success or std::nullopt on failure; call GetError() for more information.

◆ GetPalette()

Palette SDL::Surface::GetPalette ( ) const

inline

Get the palette used by a surface.

Returns: a pointer to the palette used by the surface, or nullptr if there is no palette used.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.SetPalette

◆ GetProperties()

PropertiesRef SDL::Surface::GetProperties ( ) const

inline

Get the properties associated with a surface.

The following properties are understood by 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.
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.
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".
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.
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.
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 0. 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.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ GetSurfaceAlphaMod()

Uint8 SDL::GetSurfaceAlphaMod ( SurfaceConstRef surface )

inline

Get the additional alpha value used in blit operations.

Parameters

surface the Surface structure to query.

Returns: the current alpha value.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.GetColorMod; Surface.SetAlphaMod

◆ GetSurfaceBlendMode()

BlendMode SDL::GetSurfaceBlendMode ( SurfaceConstRef surface )

inline

Get the blend mode used for blit operations.

Parameters

surface the Surface structure to query.

Returns: the current BlendMode.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.SetBlendMode

◆ GetSurfaceClipRect()

Rect SDL::GetSurfaceClipRect ( SurfaceConstRef surface )

inline

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.

Parameters

surface the Surface structure representing the surface to be clipped.

Returns: the Rect structure filled in with the clipping rectangle for the surface.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.SetClipRect

◆ GetSurfaceColorKey()

std::optional< Uint32 > SDL::GetSurfaceColorKey ( SurfaceConstRef surface )

inline

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

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

Parameters

surface the Surface structure to query.

Returns: the transparent pixel or nullopt if none.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.SetColorKey; Surface.HasColorKey

◆ GetSurfaceColorMod()

void SDL::GetSurfaceColorMod	(	SurfaceConstRef	surface,
		Uint8 *	r,
		Uint8 *	g,
		Uint8 *	b )

inline

Get the additional color value multiplied into blit operations.

Parameters

surface	the 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.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetAlphaMod; Surface.SetColorMod

◆ GetSurfaceColorspace()

Colorspace SDL::GetSurfaceColorspace ( SurfaceConstRef surface )

inline

Get the colorspace used by a surface.

The colorspace defaults to COLORSPACE_SRGB_LINEAR for floating point formats, COLORSPACE_HDR10 for 10-bit formats, COLORSPACE_SRGB for other RGB surfaces and COLORSPACE_BT709_FULL for YUV textures.

Parameters

surface the Surface structure to query.

Returns: the colorspace used by the surface, or COLORSPACE_UNKNOWN if the surface is nullptr.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.SetColorspace

◆ GetSurfaceImages()

OwnArray< SurfaceRaw > SDL::GetSurfaceImages ( SurfaceConstRef surface )

inline

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.

Parameters

surface the Surface structure to query.

Returns: a nullptr terminated array of Surface pointers or nullptr on failure; call GetError() for more information.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.AddAlternateImage; Surface.RemoveAlternateImages; Surface.HasAlternateImages

◆ GetSurfaceMod()

Color SDL::GetSurfaceMod ( SurfaceConstRef surface )

inline

Get the additional color and alpha value multiplied into blit operations.

Parameters

surface the Surface structure to query.

Returns: a Color containing RGBA value on success or std::nullopt on failure; call GetError() for more information.

◆ GetSurfacePalette()

Palette SDL::GetSurfacePalette ( SurfaceConstRef surface )

inline

Get the palette used by a surface.

Parameters

surface the Surface structure to query.

Returns: a pointer to the palette used by the surface, or nullptr if there is no palette used.

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

Since: This function is available since SDL 3.2.0.

See also: Surface.SetPalette

◆ GetSurfaceProperties()

PropertiesRef SDL::GetSurfaceProperties ( SurfaceConstRef surface )

inline

Get the properties associated with a surface.

The following properties are understood by 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.
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.
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".
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.
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.
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 0. 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.

Parameters

surface the Surface structure to query.

Returns: a valid property ID on success.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

◆ HasAlternateImages()

bool SDL::Surface::HasAlternateImages ( ) const

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Surface.AddAlternateImage; Surface.RemoveAlternateImages; Surface.GetImages

◆ HasColorKey()

bool SDL::Surface::HasColorKey ( ) const

inline

Returns whether the surface has a color key.

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

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

Since: This function is available since SDL 3.2.0.

See also: Surface.SetColorKey; Surface.GetColorKey

◆ HasRLE()

bool SDL::Surface::HasRLE ( ) const

inline

Returns whether the surface is RLE enabled.

It is safe to pass a nullptr 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.SetRLE

◆ LoadBMP()

Surface SDL::LoadBMP ( StringParam file )

inline

Load a BMP image from a file.

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

Parameters

file	the BMP file to load.

Returns: a pointer to a new Surface structure 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: Surface.Destroy; LoadBMP_IO; Surface.SaveBMP

◆ LoadBMP_IO()

Surface SDL::LoadBMP_IO	(	IOStreamRef	src,
		bool	closeio = false )

inline

Load a BMP image from a seekable SDL data stream.

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

Parameters

src	the data stream for the surface.
closeio	if true, calls IOStream.Close() on src before returning, even in the case of an error.

Returns: a pointer to a new Surface structure 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: Surface.Destroy; LoadBMP; Surface.SaveBMP_IO

◆ LoadTrustedPNG()

Surface SDL::LoadTrustedPNG ( StringParam file )

inline

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 Surface.Destroy(). Not doing so will result in a memory leak.

Parameters

file	the PNG file to load.

Returns: a new Surface structure on success 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.4.0.

See also: Surface.Destroy; LoadTrustedPNG_IO; Surface.SavePNG

◆ LoadTrustedPNG_IO()

Surface SDL::LoadTrustedPNG_IO	(	IOStreamRef	src,
		bool	closeio = false )

inline

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.

Parameters

src	the data stream for the surface.
closeio	if true, calls IOStream.Close() on src before returning, even in the case of an error.

Returns: a new Surface structure on success 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.4.0.

See also: Surface.Destroy; LoadTrustedPNG; Surface.SavePNG_IO

◆ Lock()

SurfaceLock SDL::Surface::Lock ( )

inline

Set up a surface for directly accessing the pixels.

Between calls to Surface.Lock() / Surface.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 Surface.Unlock() to release it.

Not all surfaces require locking. If Surface.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.

Exceptions

Error on failure.

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.

Since: This function is available since SDL 3.2.0.

See also: Surface.MustLock; Surface.Unlock

◆ LockSurface()

void SDL::LockSurface ( SurfaceRef surface )

inline

Set up a surface for directly accessing the pixels.

Between calls to Surface.Lock() / Surface.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 Surface.Unlock() to release it.

Not all surfaces require locking. If Surface.MustLock() 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.

Parameters

surface the Surface structure to be locked.

Exceptions

Error on failure.

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.

Since: This function is available since SDL 3.2.0.

See also: Surface.MustLock; Surface.Unlock

◆ MapRGB()

Uint32 SDL::Surface::MapRGB	(	Uint8	r,
		Uint8	g,
		Uint8	b ) const

inline

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

Parameters

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.

Since: This function is available since SDL 3.2.0.

See also: Surface.MapRGBA

◆ MapRGBA()

Uint32 SDL::Surface::MapRGBA ( ColorRaw c ) const

inline

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

Parameters

c	the color components 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.MapRGB

◆ MapSurfaceRGB()

Uint32 SDL::MapSurfaceRGB	(	SurfaceConstRef	surface,
		Uint8	r,
		Uint8	g,
		Uint8	b )

inline

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

Parameters

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.

Since: This function is available since SDL 3.2.0.

See also: Surface.MapRGBA

◆ MapSurfaceRGBA()

Uint32 SDL::MapSurfaceRGBA	(	SurfaceConstRef	surface,
		ColorRaw	c )

inline

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

Parameters

surface	the surface to use for the pixel format and palette.
c	the color components 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.MapRGB

◆ MustLock()

bool SDL::MustLock ( SurfaceConstRef S )

constexpr

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

Since: This function is available since SDL 3.2.0.

◆ PremultiplyAlpha() [1/2]

void SDL::PremultiplyAlpha	(	const PointRaw &	size,
		PixelFormat	src_format,
		const void *	src,
		int	src_pitch,
		PixelFormat	dst_format,
		void *	dst,
		int	dst_pitch,
		bool	linear )

inline

Premultiply the alpha on a block of pixels.

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

Parameters

size	the width and height of the surface.
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.

◆ PremultiplyAlpha() [2/2]

void SDL::Surface::PremultiplyAlpha ( bool linear )

inline

Premultiply the alpha in a surface.

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

Parameters

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:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ PremultiplySurfaceAlpha()

void SDL::PremultiplySurfaceAlpha	(	SurfaceRef	surface,
		bool	linear )

inline

Premultiply the alpha in a surface.

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

Parameters

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.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadPixel() [1/2]

Color SDL::Surface::ReadPixel ( const PointRaw & p ) const

inline

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.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.

Returns: color on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadPixel() [2/2]

void SDL::Surface::ReadPixel	(	const PointRaw &	p,
		Uint8 *	r,
		Uint8 *	g,
		Uint8 *	b,
		Uint8 *	a ) const

inline

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 GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.
r	a pointer filled in with the red channel, 0-255, or nullptr to ignore this channel.
g	a pointer filled in with the green channel, 0-255, or nullptr to ignore this channel.
b	a pointer filled in with the blue channel, 0-255, or nullptr to ignore this channel.
a	a pointer filled in with the alpha channel, 0-255, or nullptr to ignore this channel.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadPixelFloat() [1/2]

FColor SDL::Surface::ReadPixelFloat ( const PointRaw & p ) const

inline

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.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.

Returns: color on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadPixelFloat() [2/2]

void SDL::Surface::ReadPixelFloat	(	const PointRaw &	p,
		float *	r,
		float *	g,
		float *	b,
		float *	a ) const

inline

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.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.
r	a pointer filled in with the red channel, normally in the range 0-1, or nullptr to ignore this channel.
g	a pointer filled in with the green channel, normally in the range 0-1, or nullptr to ignore this channel.
b	a pointer filled in with the blue channel, normally in the range 0-1, or nullptr to ignore this channel.
a	a pointer filled in with the alpha channel, normally in the range 0-1, or nullptr to ignore this channel.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadSurfacePixel() [1/4]

Color SDL::ReadSurfacePixel	(	const SurfaceLock &	lock,
		const PointRaw &	p )

inline

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 GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

lock	the surface to read.
p	the coordinates, 0 <= x < width and 0 <= y < height.

Returns: color on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadSurfacePixel() [2/4]

void SDL::ReadSurfacePixel	(	const SurfaceLock &	lock,
		const PointRaw &	p,
		Uint8 *	r,
		Uint8 *	g,
		Uint8 *	b,
		Uint8 *	a )

inline

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 GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

lock	the surface to read.
p	the coordinates, 0 <= x < width and 0 <= y < height.
r	a pointer filled in with the red channel, 0-255, or nullptr to ignore this channel.
g	a pointer filled in with the green channel, 0-255, or nullptr to ignore this channel.
b	a pointer filled in with the blue channel, 0-255, or nullptr to ignore this channel.
a	a pointer filled in with the alpha channel, 0-255, or nullptr to ignore this channel.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadSurfacePixel() [3/4]

Color SDL::ReadSurfacePixel	(	SurfaceConstRef	surface,
		const PointRaw &	p )

inline

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 GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

surface	the surface to read.
p	the coordinates, 0 <= x < width and 0 <= y < height.

Returns: color on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadSurfacePixel() [4/4]

void SDL::ReadSurfacePixel	(	SurfaceConstRef	surface,
		const PointRaw &	p,
		Uint8 *	r,
		Uint8 *	g,
		Uint8 *	b,
		Uint8 *	a )

inline

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 GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

surface	the surface to read.
p	the coordinates, 0 <= x < width and 0 <= y < height.
r	a pointer filled in with the red channel, 0-255, or nullptr to ignore this channel.
g	a pointer filled in with the green channel, 0-255, or nullptr to ignore this channel.
b	a pointer filled in with the blue channel, 0-255, or nullptr to ignore this channel.
a	a pointer filled in with the alpha channel, 0-255, or nullptr to ignore this channel.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadSurfacePixelFloat() [1/4]

FColor SDL::ReadSurfacePixelFloat	(	const SurfaceLock &	lock,
		const PointRaw &	p )

inline

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.

Parameters

lock	the surface to read.
p	the coordinates, 0 <= x < width and 0 <= y < height.

Returns: color on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadSurfacePixelFloat() [2/4]

void SDL::ReadSurfacePixelFloat	(	const SurfaceLock &	lock,
		const PointRaw &	p,
		float *	r,
		float *	g,
		float *	b,
		float *	a )

inline

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.

Parameters

lock	the surface to read.
p	the coordinates, 0 <= x < width and 0 <= y < height.
r	a pointer filled in with the red channel, normally in the range 0-1, or nullptr to ignore this channel.
g	a pointer filled in with the green channel, normally in the range 0-1, or nullptr to ignore this channel.
b	a pointer filled in with the blue channel, normally in the range 0-1, or nullptr to ignore this channel.
a	a pointer filled in with the alpha channel, normally in the range 0-1, or nullptr to ignore this channel.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadSurfacePixelFloat() [3/4]

FColor SDL::ReadSurfacePixelFloat	(	SurfaceConstRef	surface,
		const PointRaw &	p )

inline

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.

Parameters

surface	the surface to read.
p	the coordinates, 0 <= x < width and 0 <= y < height.

Returns: color on success.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ ReadSurfacePixelFloat() [4/4]

void SDL::ReadSurfacePixelFloat	(	SurfaceConstRef	surface,
		const PointRaw &	p,
		float *	r,
		float *	g,
		float *	b,
		float *	a )

inline

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.

Parameters

surface	the surface to read.
p	the coordinates, 0 <= x < width and 0 <= y < height.
r	a pointer filled in with the red channel, normally in the range 0-1, or nullptr to ignore this channel.
g	a pointer filled in with the green channel, normally in the range 0-1, or nullptr to ignore this channel.
b	a pointer filled in with the blue channel, normally in the range 0-1, or nullptr to ignore this channel.
a	a pointer filled in with the alpha channel, normally in the range 0-1, or nullptr to ignore this channel.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ RemoveAlternateImages()

void SDL::Surface::RemoveAlternateImages ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Surface.AddAlternateImage; Surface.GetImages; Surface.HasAlternateImages

◆ RemoveSurfaceAlternateImages()

void SDL::RemoveSurfaceAlternateImages ( SurfaceRef surface )

inline

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.

Parameters

surface the Surface structure to update.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.AddAlternateImage; Surface.GetImages; Surface.HasAlternateImages

◆ reset()

void SDL::SurfaceLock::reset ( )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Surface.Lock

◆ ResetClipRect()

void SDL::Surface::ResetClipRect ( )

inline

Disable the clipping rectangle for a surface.

See also: SetClipRect()

◆ ResetSurfaceClipRect()

void SDL::ResetSurfaceClipRect ( SurfaceRef surface )

inline

Disable the clipping rectangle for a surface.

See also: SetSurfaceClipRect()

◆ Rotate()

Surface SDL::Surface::Rotate ( float angle )

inline

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

Parameters

angle the rotation angle, in degrees.

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

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.4.0.

◆ RotateSurface()

Surface SDL::RotateSurface	(	SurfaceRef	surface,
		float	angle )

inline

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

Parameters

surface	the surface to rotate.
angle	the rotation angle, in degrees.

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

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.4.0.

◆ SaveBMP() [1/2]

void SDL::SaveBMP	(	SurfaceConstRef	surface,
		StringParam	file )

inline

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.

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 can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: LoadBMP; Surface.SaveBMP_IO

◆ SaveBMP() [2/2]

void SDL::Surface::SaveBMP ( StringParam file ) const

inline

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.

Parameters

file	a file to save to.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: LoadBMP; Surface.SaveBMP_IO

◆ SaveBMP_IO() [1/2]

void SDL::SaveBMP_IO	(	SurfaceConstRef	surface,
		IOStreamRef	dst,
		bool	closeio = false )

inline

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.

Parameters

surface	the Surface structure containing the image to be saved.
dst	a data stream to save to.
closeio	if true, calls IOStream.Close() on dst before returning, even in the case of an error.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: LoadBMP_IO; Surface.SaveBMP

◆ SaveBMP_IO() [2/2]

void SDL::Surface::SaveBMP_IO	(	IOStreamRef	dst,
		bool	closeio = false ) const

inline

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.

Parameters

dst	a data stream to save to.
closeio	if true, calls IOStream.Close() on dst before returning, even in the case of an error.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: LoadBMP_IO; Surface.SaveBMP

◆ SaveTrustedPNG()

void SDL::SaveTrustedPNG	(	SurfaceConstRef	surface,
		StringParam	file )

inline

Save a surface to a file in PNG format.

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 can be called on different threads with different surfaces.

Since: This function is available since SDL 3.4.0.

See also: LoadTrustedPNG; Surface.SavePNG_IO

◆ SaveTrustedPNG_IO()

void SDL::SaveTrustedPNG_IO	(	SurfaceConstRef	surface,
		IOStreamRef	dst,
		bool	closeio = false )

inline

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

Parameters

surface	the Surface structure containing the image to be saved.
dst	a data stream to save to.
closeio	if true, calls IOStream.Close() on dst before returning, even in the case of an error.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.4.0.

See also: LoadTrustedPNG_IO; Surface.SavePNG

◆ Scale()

Surface SDL::Surface::Scale	(	const PointRaw &	size,
		ScaleMode	scaleMode ) const

inline

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

Parameters

size	the width and 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 can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Destroy

◆ ScaleSurface()

Surface SDL::ScaleSurface	(	SurfaceConstRef	surface,
		const PointRaw &	size,
		ScaleMode	scaleMode )

inline

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

The returned surface should be freed with Surface.Destroy().

Parameters

surface	the surface to duplicate and scale.
size	the width and height of the 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 can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Destroy

◆ SetAlphaMod()

void SDL::Surface::SetAlphaMod ( Uint8 alpha )

inline

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)

Parameters

alpha the alpha value multiplied into blit operations.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetAlphaMod; Surface.SetColorMod

◆ SetBlendMode()

void SDL::Surface::SetBlendMode ( BlendMode blendMode )

inline

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

Parameters

blendMode the BlendMode to use for blit blending.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetBlendMode

◆ SetClipRect()

bool SDL::Surface::SetClipRect ( OptionalRef< const RectRaw > rect )

inline

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.

Parameters

rect	the Rect structure representing the clipping rectangle, or nullptr 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.ResetClipRect(); Surface.GetClipRect

◆ SetColorKey()

void SDL::Surface::SetColorKey ( std::optional< Uint32 > key )

inline

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

Parameters

key	the transparent pixel or std::nullopt to disable it.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetColorKey; Surface.SetRLE; Surface.HasColorKey

◆ SetColorMod()

void SDL::Surface::SetColorMod	(	Uint8	r,
		Uint8	g,
		Uint8	b )

inline

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)

Parameters

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.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetColorMod; Surface.SetAlphaMod

◆ SetColorspace()

void SDL::Surface::SetColorspace ( Colorspace colorspace )

inline

Set the colorspace used by a surface.

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

Parameters

colorspace a Colorspace value describing the surface colorspace.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetColorspace

◆ SetMod()

void SDL::Surface::SetMod ( Color color )

inline

Set an additional color and alpha 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) srcA = srcA * (alpha / 255)

Parameters

color the color to be multiplied in blit operations

Exceptions

Error on failure.

◆ SetPalette()

void SDL::Surface::SetPalette ( PaletteRef palette )

inline

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.

Parameters

palette the Palette structure to use.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: CreatePalette; Surface.GetPalette

◆ SetRLE()

void SDL::Surface::SetRLE ( bool enabled )

inline

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.

Parameters

enabled true to enable RLE acceleration, false to disable it.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit; Surface.Lock; Surface.Unlock

◆ SetSurfaceAlphaMod()

void SDL::SetSurfaceAlphaMod	(	SurfaceRef	surface,
		Uint8	alpha )

inline

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)

Parameters

surface	the Surface structure to update.
alpha	the alpha value multiplied into blit operations.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetAlphaMod; Surface.SetColorMod

◆ SetSurfaceBlendMode()

void SDL::SetSurfaceBlendMode	(	SurfaceRef	surface,
		BlendMode	blendMode )

inline

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

Parameters

surface	the Surface structure to update.
blendMode	the BlendMode to use for blit blending.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetBlendMode

◆ SetSurfaceClipRect()

bool SDL::SetSurfaceClipRect	(	SurfaceRef	surface,
		OptionalRef< const RectRaw >	rect )

inline

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.

Parameters

surface	the Surface structure to be clipped.
rect	the Rect structure representing the clipping rectangle, or nullptr 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetClipRect

◆ SetSurfaceColorKey()

void SDL::SetSurfaceColorKey	(	SurfaceRef	surface,
		std::optional< Uint32 >	key )

inline

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

Parameters

surface	the Surface structure to update.
key	the transparent pixel or std::nullopt to disable it.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetColorKey; Surface.SetRLE; Surface.HasColorKey

◆ SetSurfaceColorMod()

void SDL::SetSurfaceColorMod	(	SurfaceRef	surface,
		Uint8	r,
		Uint8	g,
		Uint8	b )

inline

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)

Parameters

surface	the 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.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetColorMod; Surface.SetAlphaMod

◆ SetSurfaceColorspace()

void SDL::SetSurfaceColorspace	(	SurfaceRef	surface,
		Colorspace	colorspace )

inline

Set the colorspace used by a surface.

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

Parameters

surface	the Surface structure to update.
colorspace	an Colorspace value describing the surface colorspace.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.GetColorspace

◆ SetSurfaceMod()

void SDL::SetSurfaceMod	(	SurfaceRef	surface,
		Color	color )

inline

Set an additional color and alpha 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) srcA = srcA * (alpha / 255)

Parameters

surface	the Surface structure to query.
color	the color to be multiplied in blit operations

Exceptions

Error on failure.

◆ SetSurfacePalette()

void SDL::SetSurfacePalette	(	SurfaceRef	surface,
		PaletteRef	palette )

inline

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.

Parameters

surface	the Surface structure to update.
palette	the Palette structure to use.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: CreatePalette; Surface.GetPalette

◆ SetSurfaceRLE()

void SDL::SetSurfaceRLE	(	SurfaceRef	surface,
		bool	enabled )

inline

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.

Parameters

surface	the Surface structure to optimize.
enabled	true to enable RLE acceleration, false to disable it.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

See also: Surface.Blit; Surface.Lock; Surface.Unlock

◆ Stretch()

void SDL::Surface::Stretch	(	SurfaceRef	src,
		OptionalRef< RectRaw >	srcrect,
		OptionalRef< RectRaw >	dstrect,
		ScaleMode	scaleMode )

inline

Perform a stretched pixel copy from one surface to another.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire destination surface.
scaleMode	the ScaleMode to be used.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.4.0.

See also: Surface.BlitScaled

◆ StretchSurface()

void SDL::StretchSurface	(	SurfaceRef	src,
		OptionalRef< RectRaw >	srcrect,
		SurfaceRef	dst,
		OptionalRef< RectRaw >	dstrect,
		ScaleMode	scaleMode )

inline

Perform a stretched pixel copy from one surface to another.

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied, or nullptr to copy the entire surface.
dst	the Surface structure that is the blit target.
dstrect	the Rect structure representing the target rectangle in the destination surface, or nullptr to fill the entire destination surface.
scaleMode	the ScaleMode to be used.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.4.0.

See also: Surface.BlitScaled

◆ Surface() [1/2]

SDL::Surface::Surface	(	const PointRaw &	size,
		PixelFormat	format )

inline

Allocate a new surface with a specific pixel format.

The pixels of the new surface are initialized to zero.

Parameters

size	the width and height of the surface.
format	the PixelFormat for the new surface's pixel format.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: CreateSurfaceFrom; Surface.Destroy

◆ Surface() [2/2]

SDL::Surface::Surface	(	const PointRaw &	size,
		PixelFormat	format,
		void *	pixels,
		int	pitch )

inline

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

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

Parameters

size	the width and height of the surface.
format	the 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.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: CreateSurface; Surface.Destroy

◆ SurfaceHasAlternateImages()

bool SDL::SurfaceHasAlternateImages ( SurfaceConstRef surface )

inline

Return whether a surface has alternate versions available.

Parameters

surface the 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.AddAlternateImage; Surface.RemoveAlternateImages; Surface.GetImages

◆ SurfaceHasColorKey()

bool SDL::SurfaceHasColorKey ( SurfaceConstRef surface )

inline

Returns whether the surface has a color key.

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

Parameters

surface the 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.SetColorKey; Surface.GetColorKey

◆ SurfaceHasRLE()

bool SDL::SurfaceHasRLE ( SurfaceConstRef surface )

inline

Returns whether the surface is RLE enabled.

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

Parameters

surface the 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.SetRLE

◆ SurfaceLock()

SDL::SurfaceLock::SurfaceLock ( SurfaceRef resource )

inline

Set up a surface for directly accessing the pixels.

Between calls to Surface.Lock() / Surface.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 Surface.Unlock() to release it.

Not all surfaces require locking. If Surface.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.

Postcondition: true on success or false on failure; call 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.MustLock; Surface.Unlock

◆ Unlock()

void SDL::Surface::Unlock ( SurfaceLock && lock )

inline

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.

Since: This function is available since SDL 3.2.0.

See also: Surface.Lock

◆ UnlockSurface()

void SDL::UnlockSurface ( SurfaceRef surface )

inline

Release a surface after directly accessing the pixels.

Parameters

surface the 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.

Since: This function is available since SDL 3.2.0.

See also: Surface.Lock

◆ WritePixel()

void SDL::Surface::WritePixel	(	const PointRaw &	p,
		ColorRaw	c )

inline

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 MapColor, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.
c	the color values, 0-255.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ WritePixelFloat()

void SDL::Surface::WritePixelFloat	(	const PointRaw &	p,
		const FColorRaw &	c )

inline

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.

Parameters

p	the coordinates, 0 <= x < width and 0 <= y < height.
c	the color values, normally in the range 0-1.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ WriteSurfacePixel() [1/2]

void SDL::WriteSurfacePixel	(	SurfaceLock &	lock,
		const PointRaw &	p,
		ColorRaw	c )

inline

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 MapColor, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

lock	the surface to write.
p	the coordinates, 0 <= x < width, 0 <= y < height.
c	the color channels value, 0-255.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ WriteSurfacePixel() [2/2]

void SDL::WriteSurfacePixel	(	SurfaceRef	surface,
		const PointRaw &	p,
		ColorRaw	c )

inline

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 MapColor, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

surface	the surface to write.
p	the coordinates, 0 <= x < width, 0 <= y < height.
c	the color channels value, 0-255.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ WriteSurfacePixelFloat() [1/2]

void SDL::WriteSurfacePixelFloat	(	SurfaceLock &	lock,
		const PointRaw &	p,
		const FColorRaw &	c )

inline

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.

Parameters

lock	the surface to write.
p	the coordinates, 0 <= x < width, 0 <= y < height.
c	the color channels values, normally in the range 0-1.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

◆ WriteSurfacePixelFloat() [2/2]

void SDL::WriteSurfacePixelFloat	(	SurfaceRef	surface,
		const PointRaw &	p,
		const FColorRaw &	c )

inline

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.

Parameters

surface	the surface to write.
p	the coordinates, 0 <= x < width, 0 <= y < height.
c	the color channels values, normally in the range 0-1.

Exceptions

Error on failure.

Thread safety:: This function can be called on different threads with different surfaces.

Since: This function is available since SDL 3.2.0.

Surface uses preallocated pixel memory.

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ FlipMode

◆ ScaleMode

◆ SurfaceFlags

◆ SurfaceRef

Function Documentation

◆ AddAlternateImage()

◆ AddSurfaceAlternateImage()

◆ Blit()

◆ Blit9Grid()

◆ BlitAt()

◆ BlitScaled()

◆ BlitSurface()

◆ BlitSurface9Grid()

◆ BlitSurfaceAt()

◆ BlitSurfaceScaled()

◆ BlitSurfaceTiled()

◆ BlitSurfaceTiledWithScale()

◆ BlitSurfaceUnchecked()

◆ BlitSurfaceUncheckedScaled()

◆ BlitTiled()

◆ BlitTiledWithScale()

◆ BlitUnchecked()

◆ BlitUncheckedScaled()

◆ Clear()

◆ ClearColorKey()

◆ ClearSurface()

◆ ClearSurfaceColorKey()

◆ Convert() [1/2]

◆ Convert() [2/2]

◆ ConvertPixels()

◆ ConvertPixelsAndColorspace()

◆ ConvertSurface()

◆ ConvertSurfaceAndColorspace()

◆ CreatePalette()

◆ CreateSurface()

◆ CreateSurfaceFrom()

◆ CreateSurfacePalette()

◆ Destroy()

◆ DestroySurface()

◆ Duplicate()

◆ DuplicateSurface()

◆ Fill()

◆ FillRect()

◆ FillRects()

◆ FillSurface()

◆ FillSurfaceRect()

◆ FillSurfaceRects()

◆ Flip()

◆ FlipSurface()

◆ GetAlphaMod()

◆ GetBlendMode()

◆ GetClipRect()

◆ GetColorKey()

◆ GetColorMod()

◆ GetColorspace()

◆ GetImages()

◆ GetMod()

◆ GetPalette()

◆ GetProperties()

◆ GetSurfaceAlphaMod()

◆ GetSurfaceBlendMode()

◆ GetSurfaceClipRect()

◆ GetSurfaceColorKey()

◆ GetSurfaceColorMod()

◆ GetSurfaceColorspace()

◆ GetSurfaceImages()

◆ GetSurfaceMod()

◆ GetSurfacePalette()

◆ GetSurfaceProperties()

◆ HasAlternateImages()

◆ HasColorKey()

◆ HasRLE()

◆ LoadBMP()