A collection of pixels used in software blitting. More...

Public Member Functions
constexpr	Surface ()=default
	Default ctor.

constexpr	Surface (const SurfaceRaw resource)
	Constructs from SurfaceParam. More...

constexpr	Surface (const Surface &other)
	Copy constructor.

constexpr	Surface (Surface &&other)
	Move constructor.

	Surface (const PointRaw &size, PixelFormat format)
	Allocate a new surface with a specific pixel format. More...

	Surface (const PointRaw &size, PixelFormat format, void *pixels, int pitch)
	Allocate a new surface with a specific pixel format and existing pixel data. More...

	Surface (StringParam file)
	Load an image from a filesystem path into a software surface. More...

	Surface (IOStreamParam src, bool closeio=false)
	Load an image from an SDL data source into a software surface. More...

	~Surface ()
	Destructor.

Surface &	operator= (Surface other)
	Assignment operator.

constexpr SurfaceRaw	get () const
	Retrieves underlying SurfaceRaw.

constexpr SurfaceRaw	release ()
	Retrieves underlying SurfaceRaw and clear this.

constexpr auto	operator<=> (const Surface &other) const =default
	Comparison.

constexpr bool	operator== (std::nullptr_t _) const
	Comparison.

constexpr	operator bool () const
	Converts to bool.

constexpr	operator SurfaceParam () const
	Converts to SurfaceParam.

void	Destroy ()
	Free a surface. More...

PropertiesRef	GetProperties () const
	Get the properties associated with a surface. More...

void	SetColorspace (Colorspace colorspace)
	Set the colorspace used by a surface. More...

Colorspace	GetColorspace () const
	Get the colorspace used by a surface. More...

Palette	CreatePalette ()
	Create a palette and associate it with a surface. More...

void	SetPalette (PaletteParam palette)
	Set the palette used by a surface. More...

Palette	GetPalette () const
	Get the palette used by a surface. More...

void	AddAlternateImage (SurfaceParam image)
	Add an alternate version of a surface. More...

bool	HasAlternateImages () const
	Return whether a surface has alternate versions available. More...

OwnArray< SurfaceRaw >	GetImages () const
	Get an array including all versions of a surface. More...

void	RemoveAlternateImages ()
	Remove all alternate versions of a surface. More...

constexpr bool	MustLock () const
	Evaluates to true if the surface needs to be locked before access. More...

void	Lock ()
	Set up a surface for directly accessing the pixels. More...

void	Unlock ()
	Release a surface after directly accessing the pixels. More...

void	SaveBMP (IOStreamParam dst, bool closeio=false) const
	Save a surface to a seekable SDL data stream in BMP format. More...

void	SaveBMP (StringParam file) const
	Save a surface to a file. More...

void	SetRLE (bool enabled)
	Set the RLE acceleration hint for a surface. More...

bool	HasRLE () const
	Returns whether the surface is RLE enabled. More...

void	SetColorKey (std::optional< Uint32 > key)
	Set the color key (transparent pixel) in a surface. More...

void	ClearColorKey ()
	Unset the color key (transparent pixel) in a surface. More...

bool	HasColorKey () const
	Returns whether the surface has a color key. More...

std::optional< Uint32 >	GetColorKey () const
	Get the color key (transparent pixel) for a surface. More...

void	SetColorMod (Uint8 r, Uint8 g, Uint8 b)
	Set an additional color value multiplied into blit operations. More...

void	GetColorMod (Uint8 r, Uint8 g, Uint8 *b) const
	Get the additional color value multiplied into blit operations. More...

void	SetAlphaMod (Uint8 alpha)
	Set an additional alpha value used in blit operations. More...

Uint8	GetAlphaMod () const
	Get the additional alpha value used in blit operations. More...

void	SetMod (Color color)
	Set an additional color and alpha value multiplied into blit operations. More...

Color	GetMod () const
	Get the additional color and alpha value multiplied into blit operations. More...

void	SetBlendMode (BlendMode blendMode)
	Set the blend mode used for blit operations. More...

BlendMode	GetBlendMode () const
	Get the blend mode used for blit operations. More...

bool	SetClipRect (OptionalRef< const RectRaw > rect)
	Set the clipping rectangle for a surface. More...

void	ResetClipRect ()
	Disable the clipping rectangle for a surface. More...

Rect	GetClipRect () const
	Get the clipping rectangle for a surface. More...

void	Flip (FlipMode flip)
	Flip a surface vertically or horizontally. More...

Surface	Duplicate () const
	Creates a new surface identical to the existing surface. More...

Surface	Scale (const PointRaw &size, ScaleMode scaleMode) const
	Creates a new surface identical to the existing surface, scaled to the desired size. More...

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

Surface	Convert (PixelFormat format, PaletteParam palette, Colorspace colorspace, PropertiesParam props) const
	Copy an existing surface to a new surface of the specified format and colorspace. More...

void	PremultiplyAlpha (bool linear)
	Premultiply the alpha in a surface. More...

void	Clear (const FColorRaw &color)
	Clear a surface with a specific color, with floating point precision. More...

void	Fill (Uint32 color)
	Perform a fast fill of a rectangle with a specific color. More...

void	FillRect (OptionalRef< const RectRaw > rect, Uint32 color)
	Perform a fast fill of a rectangle with a specific color. More...

void	FillRects (SpanRef< const RectRaw > rects, Uint32 color)
	Perform a fast fill of a set of rectangles with a specific color. More...

void	Blit (SurfaceParam src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect)
	Performs a fast blit from the source surface to the destination surface with clipping. More...

void	BlitAt (SurfaceParam src, OptionalRef< const RectRaw > srcrect, const PointRaw &dstpos)
	Performs a fast blit from the source surface to the destination surface with clipping. More...

void	BlitUnchecked (SurfaceParam src, const RectRaw &srcrect, const RectRaw &dstrect)
	Perform low-level surface blitting only. More...

void	BlitScaled (SurfaceParam 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. More...

void	BlitUncheckedScaled (SurfaceParam src, const RectRaw &srcrect, const RectRaw &dstrect, ScaleMode scaleMode)
	Perform low-level surface scaled blitting only. More...

void	Stretch (SurfaceParam src, OptionalRef< RectRaw > srcrect, OptionalRef< RectRaw > dstrect, ScaleMode scaleMode)
	Perform a stretched pixel copy from one surface to another. More...

void	BlitTiled (SurfaceParam src, OptionalRef< const RectRaw > srcrect, OptionalRef< const RectRaw > dstrect)
	Perform a tiled blit to a destination surface, which may be of a different format. More...

void	BlitTiledWithScale (SurfaceParam src, OptionalRef< const RectRaw > srcrect, float scale, SDL_ScaleMode scaleMode, OptionalRef< const RectRaw > dstrect)
	Perform a scaled and tiled blit to a destination surface, which may be of a different format. More...

void	Blit9Grid (SurfaceParam src, OptionalRef< const RectRaw > srcrect, int left_width, int right_width, int top_height, int bottom_height, OptionalRef< const RectRaw > dstrect)
	Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format. More...

void	Blit9Grid (SurfaceParam src, OptionalRef< const RectRaw > srcrect, int left_width, int right_width, int top_height, int bottom_height, float scale, SDL_ScaleMode scaleMode, OptionalRef< const RectRaw > dstrect)
	Perform a scaled blit using the 9-grid algorithm to a destination surface, which may be of a different format. More...

Uint32	MapRGB (Uint8 r, Uint8 g, Uint8 b) const
	Map an RGB triple to an opaque pixel value for a surface. More...

Uint32	MapRGBA (ColorRaw c) const
	Map an RGBA quadruple to a pixel value for a surface. More...

Color	ReadPixel (const PointRaw &p) const
	This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine. More...

void	ReadPixel (const PointRaw &p, Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
	Retrieves a single pixel from a surface. More...

FColor	ReadPixelFloat (const PointRaw &p) const
	Retrieves a single pixel from a surface. More...

void	ReadPixelFloat (const PointRaw &p, float r, float g, float b, float a) const
	Retrieves a single pixel from a surface. More...

void	WritePixel (const PointRaw &p, ColorRaw c)
	Writes a single pixel to a surface. More...

void	WritePixelFloat (const PointRaw &p, const FColorRaw &c)
	Writes a single pixel to a surface. More...

constexpr int	GetWidth () const
	Get the width in pixels.

constexpr int	GetHeight () const
	Get the height in pixels.

constexpr Point	GetSize () const
	Get the size in pixels.

constexpr int	GetPitch () const
	Get pitch in bytes.

constexpr PixelFormat	GetFormat () const
	Get the pixel format.

constexpr void *	GetPixels () const
	Get the pixels.

Static Public Member Functions
static constexpr Surface	Borrow (SurfaceParam resource)
	Safely borrows the from SurfaceParam. More...

static Surface	LoadBMP (IOStreamParam src, bool closeio=false)
	Load a BMP image from a seekable SDL data stream. More...

static Surface	LoadBMP (StringParam file)
	Load a BMP image from a file. More...

Detailed Description

Pixels are arranged in memory in rows, with the top row first. Each row occupies an amount of memory given by the pitch (sometimes known as the row stride in non-SDL APIs).

Within each row, pixels are arranged from left to right until the width is reached. Each pixel occupies a number of bits appropriate for its format, with most formats representing each pixel as one or more whole bytes (in some indexed formats, instead multiple pixels are packed into each byte), and a byte order given by the format. After encoding all pixels, any remaining bytes to reach the pitch are used as padding to reach a desired alignment, and have undefined contents.

When a surface holds YUV format data, the planes are assumed to be contiguous without padding between them, e.g. a 32x32 surface in NV12 format with a pitch of 32 would consist of 32x32 bytes of Y plane followed by 32x16 bytes of UV plane.

When a surface holds MJPG format data, pixels points at the compressed JPEG image and pitch is the length of that data.

Since: This struct is available since SDL 3.2.0.

Category:: Resource

See also: Surface.Surface; Surface.Destroy

Constructor & Destructor Documentation

◆ Surface() [1/3]

constexpr SDL::Surface::Surface ( const SurfaceRaw resource )

inlineexplicitconstexpr

Parameters

resource a SurfaceRaw to be wrapped.

This assumes the ownership, call release() if you need to take back.

◆ Surface() [2/3]

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

inline

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

◆ Surface() [3/3]

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

inline

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

Member Function Documentation

◆ Blit9Grid()

void SDL::Surface::Blit9Grid	(	SurfaceParam	src,
		OptionalRef< const RectRaw >	srcrect,
		int	left_width,
		int	right_width,
		int	top_height,
		int	bottom_height,
		OptionalRef< const RectRaw >	dstrect
	)

inline

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.

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	(	SurfaceParam	src,
		OptionalRef< const RectRaw >	srcrect,
		const PointRaw &	dstpos
	)

inline

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

◆ Borrow()

static constexpr Surface SDL::Surface::Borrow ( SurfaceParam resource )

inlinestaticconstexpr

Parameters

resource a SurfaceRaw or Surface.

This does not takes ownership!

◆ ClearColorKey()

void SDL::Surface::ClearColorKey ( )

inline

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.

◆ Fill()

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

inline

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.

◆ GetMod()

Color SDL::Surface::GetMod ( ) const

inline

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

◆ MustLock()

constexpr bool SDL::Surface::MustLock ( ) const

inlineconstexpr

Since: This function is available since SDL 3.2.0.

◆ ReadPixel()

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

inline

Like SDL_GetRGBA, this uses the entire 0..255 range when converting color components from pixel formats with less than 8 bits per RGB component.

Parameters

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

Returns: color on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

◆ ReadPixelFloat()

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

inline

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 is not thread safe.

◆ ResetClipRect()

void SDL::Surface::ResetClipRect ( )

inline

See also: SetClipRect()

◆ SetMod()

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

inline

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.

The documentation for this class was generated from the following files:

SDL3pp/SDL3pp_surface.h
SDL3pp/SDL3pp_image.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Surface() [1/3]

◆ Surface() [2/3]

◆ Surface() [3/3]

Member Function Documentation

◆ Blit9Grid()

◆ BlitAt()

◆ Borrow()

◆ ClearColorKey()

◆ Fill()

◆ GetMod()

◆ MustLock()

◆ ReadPixel()

◆ ReadPixelFloat()

◆ ResetClipRect()

◆ SetMod()