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

Inheritance diagram for SDL::SurfaceBase:

[legend]

Public Member Functions
	SurfaceBase (StringParam file)
	Load an image from a filesystem path into a software surface.

	SurfaceBase (IOStreamBase &src)
	Load an image from a IOStreamBase into a software surface.

	SurfaceBase (const SDL_Point &size, PixelFormat format)
	Allocate a new surface with a specific pixel format.

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

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

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

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

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

void	SetPalette (PaletteBase &palette)
	Set the palette used by a surface.

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

void	AddAlternateImage (SurfaceBase &image)
	Add an alternate version of a surface.

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

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

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

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

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

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

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

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

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

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

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

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

void	GetColorKey (Color *key) const
	Get the color key (transparent pixel) for a surface.

void	GetColorKey (Uint32 *key) const
	Get the color key (transparent pixel) for a surface.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void	Clear (SDL_FColor color)
	Clear a surface with a specific color, with floating point precision.

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

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

void	FillRect (const SDL_Rect &rect, SDL_Color color)
	Perform a fast fill of a rectangle with a specific color.

void	FillRect (const SDL_Rect &rect, Uint32 color)
	Perform a fast fill of a rectangle with a specific color.

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

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

void	Blit (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, const SDL_Point &dstpos)
	Performs a fast blit from the source surface to the destination surface with clipping.

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

void	BlitUnchecked (const SurfaceBase &src, const SDL_Rect &srcrect, const SDL_Rect &dstrect)
	Perform low-level surface blitting only.

void	BlitScaled (const SurfaceBase &src, OptionalRef< const SDL_Rect > srcrect, OptionalRef< const SDL_Rect > dstrect, ScaleMode scaleMode)
	Perform a scaled blit to a destination surface, which may be of a different format.

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

void	Stretch (const SurfaceBase &src, const SDL_Rect &srcrect, const SDL_Rect &dstrect, ScaleMode scaleMode)
	Perform a stretched pixel copy from one surface to another.

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

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

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

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

Uint32	MapColor (SDL_Color color) const
	Map an RGBA quadruple to a pixel value for a surface.

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

Uint32	MapColor (Uint8 r, Uint8 g, Uint8 b, Uint8 a) const
	Map an RGBA quadruple to a pixel value for a surface.

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

void	ReadPixel (const SDL_Point &p, SDL_Color *c) const
	This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

void	ReadPixel (const SDL_Point &p, SDL_FColor *c) const
	Retrieves a single pixel from a surface.

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

void	ReadPixel (const SDL_Point &p, float r, float g, float b, float a) const
	Retrieves a single pixel from a surface.

void	WritePixel (const SDL_Point &p, SDL_Color c)
	Writes a single pixel to a surface.

void	WritePixel (const SDL_Point &p, SDL_FColor c)
	Writes a single pixel to a surface.

int	GetWidth () const
	Get the width in pixels.

int	GetHeight () const
	Get the height in pixels.

Point	GetSize () const
	Get the size in pixels.

PixelFormat	GetFormat () const
	Get the pixel format.

constexpr	Resource (T resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Public Member Functions inherited from SDL::Resource< SDL_Surface * >
constexpr	Resource (SDL_Surface * resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Resource &	operator= (const Resource &other)=delete

Resource &	operator= (Resource &&other)=delete

constexpr	operator bool () const
	True if contains a valid resource.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

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

constexpr SDL_Surface *	get () const
	Return contained resource;.

constexpr SDL_Surface *	release (SDL_Surface * newResource={})
	Return contained resource and empties or replace value.

constexpr const SDL_Surface *	operator-> () const
	Access to fields.

constexpr SDL_Surface *	operator-> ()
	Access to fields.

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.

See also: SurfaceBase.SurfaceBase; SurfaceRef.reset

Category:: Resource

See also: Surface; SurfaceRef

Constructor & Destructor Documentation

◆ SurfaceBase() [1/4]

SDL::SurfaceBase::SurfaceBase ( StringParam file )

inline

If available, this uses LoadSurface(StringParam), otherwise it uses LoadBMP(StringParam).

Parameters

file	a path on the filesystem to load an image from.

Postcondition: the new Surface with loaded contents on success.

Exceptions

Error on failure.

See also: LoadSurface(StringParam); LoadBMP(StringParam)

◆ SurfaceBase() [2/4]

SDL::SurfaceBase::SurfaceBase ( IOStreamBase & src )

inline

If available, this uses LoadSurface(IOStreamBase&), otherwise it uses LoadBMP(IOStreamBase&).

Parameters

src	an IOStreamBase to load an image from.

Postcondition: the new Surface with loaded contents on success.

Exceptions

Error on failure.

See also: LoadSurface(StringParam); LoadBMP(StringParam)

◆ SurfaceBase() [3/4]

SDL::SurfaceBase::SurfaceBase	(	const SDL_Point &	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.

Postcondition: the new SurfaceBase structure that is created.

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.

◆ SurfaceBase() [4/4]

SDL::SurfaceBase::SurfaceBase	(	const SDL_Point &	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.

Postcondition: the new SurfaceBase structure that is created.

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.

Member Function Documentation

◆ AddAlternateImage()

void SDL::SurfaceBase::AddAlternateImage ( SurfaceBase & image )

inline

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

Parameters

image an alternate SurfaceBase to associate with this surface.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

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

◆ Blit() [1/2]

void SDL::SurfaceBase::Blit	(	const SurfaceBase &	src,
		OptionalRef< const SDL_Rect >	srcrect,
		const SDL_Point &	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 SDL_Surface structure to be copied from.
srcrect	the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface.
dstpos	the SDL_Point structure representing the x and y position in the destination surface, or NULL 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 SurfaceBase.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: SurfaceBase.BlitScaled

◆ Blit() [2/2]

void SDL::SurfaceBase::Blit	(	const SurfaceBase &	src,
		OptionalRef< const SDL_Rect >	srcrect,
		OptionalRef< const SDL_Rect >	dstrect
	)

inline

If either srcrect or dstrect are nullptr, the entire surface (src or dst) is copied while ensuring clipping to dst->clip_rect.

The final blit rectangles are saved in srcrect and dstrect after all clipping is performed.

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 SDL_Surface structure to be copied from.
srcrect	the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface.
dstrect	the SDL_Rect structure representing the x and y position in the destination surface, or NULL 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 SurfaceBase.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: SurfaceBase.BlitScaled

◆ Blit9Grid()

void SDL::SurfaceBase::Blit9Grid	(	const SurfaceBase &	src,
		OptionalRef< const SDL_Rect >	srcrect,
		int	left_width,
		int	right_width,
		int	top_height,
		int	bottom_height,
		OptionalRef< const SDL_Rect >	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: SurfaceBase.Blit

◆ Blit9GridWithScale()

void SDL::SurfaceBase::Blit9GridWithScale	(	const SurfaceBase &	src,
		OptionalRef< const SDL_Rect >	srcrect,
		int	left_width,
		int	right_width,
		int	top_height,
		int	bottom_height,
		float	scale,
		SDL_ScaleMode	scaleMode,
		OptionalRef< const SDL_Rect >	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`.
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.
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: SurfaceBase.Blit

◆ BlitScaled()

void SDL::SurfaceBase::BlitScaled	(	const SurfaceBase &	src,
		OptionalRef< const SDL_Rect >	srcrect,
		OptionalRef< const SDL_Rect >	dstrect,
		ScaleMode	scaleMode
	)

inline

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: SurfaceBase.Blit

◆ BlitTiled()

void SDL::SurfaceBase::BlitTiled	(	const SurfaceBase &	src,
		OptionalRef< const SDL_Rect >	srcrect,
		OptionalRef< const SDL_Rect >	dstrect
	)

inline

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: SurfaceBase.Blit

◆ BlitTiledWithScale()

void SDL::SurfaceBase::BlitTiledWithScale	(	const SurfaceBase &	src,
		OptionalRef< const SDL_Rect >	srcrect,
		float	scale,
		SDL_ScaleMode	scaleMode,
		OptionalRef< const SDL_Rect >	dstrect
	)

inline

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: SurfaceBase.Blit

◆ BlitUnchecked()

void SDL::SurfaceBase::BlitUnchecked	(	const SurfaceBase &	src,
		const SDL_Rect &	srcrect,
		const SDL_Rect &	dstrect
	)

inline

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 SDL_Surface structure to be copied from.
srcrect	the SDL_Rect structure representing the rectangle to be copied, may not be NULL.
dstrect	the SDL_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: SurfaceBase.Blit

◆ BlitUncheckedScaled()

void SDL::SurfaceBase::BlitUncheckedScaled	(	const SurfaceBase &	src,
		const SDL_Rect &	srcrect,
		const SDL_Rect &	dstrect,
		ScaleMode	scaleMode
	)

inline

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 SDL_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: SurfaceBase.BlitScaled

◆ Clear()

void SDL::SurfaceBase::Clear ( SDL_FColor color )

inline

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

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

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ClearColorKey()

void SDL::SurfaceBase::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.

◆ CreatePalette()

PaletteRef SDL::SurfaceBase::CreatePalette ( )

inline

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 SDL_PIXELFORMAT_INDEX1LSB or SDL_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 SDL_Palette structure on success or NULL on failure (e.g. if the surface didn't have an index format); call GetError() for more information.

Since: This function is available since SDL 3.2.0.

See also: Palette.SetColors()

◆ Fill() [1/2]

void SDL::SurfaceBase::Fill ( SDL_Color color )

inline

If there is a clip rectangle set on the destination (set via SurfaceBase.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.

◆ Fill() [2/2]

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

inline

color should be a pixel of the format used by the surface, and can be generated by MapRGB() or MapRGBA(). 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 SurfaceBase.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() [1/2]

void SDL::SurfaceBase::FillRect	(	const SDL_Rect &	rect,
		SDL_Color	color
	)

inline

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

Parameters

rect	the SDL_Rect structure representing the rectangle to fill.
color	the color to fill with.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.FillRects

◆ FillRect() [2/2]

void SDL::SurfaceBase::FillRect	(	const SDL_Rect &	rect,
		Uint32	color
	)

inline

color should be a pixel of the format used by the surface, and can be generated by MapRGB() or MapRGBA(). 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 SurfaceBase.SetClipRect()), then this function will fill based on the intersection of the clip rectangle and rect.

Parameters

rect	the SDL_Rect structure representing the rectangle to fill.
color	the color to fill with.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.FillRects

◆ FillRects() [1/2]

void SDL::SurfaceBase::FillRects	(	SpanRef< const SDL_Rect >	rects,
		SDL_Color	color
	)

inline

If there is a clip rectangle set on the destination (set via SurfaceBase.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 is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: FillRect()

◆ FillRects() [2/2]

void SDL::SurfaceBase::FillRects	(	SpanRef< const SDL_Rect >	rects,
		Uint32	color
	)

inline

color should be a pixel of the format used by the surface, and can be generated by MapRGB() or MapRGBA(). 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 SurfaceBase.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 is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.FillRect

◆ Flip()

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

inline

Parameters

flip	the direction to flip.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetAlphaMod()

Uint8 SDL::SurfaceBase::GetAlphaMod ( ) const

inline

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: SurfaceBase.GetColorMod; SurfaceBase.SetAlphaMod

◆ GetBlendMode()

BlendMode SDL::SurfaceBase::GetBlendMode ( ) const

inline

Returns: the blendMode on success or BLENDMODE_INVALID on failure; call GetError() for more information.

◆ GetClipRect()

Rect SDL::SurfaceBase::GetClipRect ( ) const

inline

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, or false on failure; call GetError() for more information.

◆ GetColorKey() [1/3]

Color SDL::SurfaceBase::GetColorKey ( ) const

inline

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 std::nullopt.

Returns: the color key as Color or std::nullopt if it does not have one.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: SetColorKey(); HasColorKey()

◆ GetColorKey() [2/3]

void SDL::SurfaceBase::GetColorKey ( Color * key ) const

inline

The color key is a pixel of the format used by the surface, as generated by SDL_MapRGB().

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

Parameters

key	a pointer filled in with the transparent pixel.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SetColorKey(); HasColorKey()

◆ GetColorKey() [3/3]

void SDL::SurfaceBase::GetColorKey ( Uint32 * key ) const

inline

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

key	a pointer filled in with the transparent pixel.

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: SurfaceBase.SetColorKey; SurfaceBase.HasColorKey

◆ GetColorMod()

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

inline

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

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.GetAlphaMod; SurfaceBase.SetColorMod

◆ GetColorspace()

Colorspace SDL::SurfaceBase::GetColorspace ( ) const

inline

The colorspace defaults to SDL_COLORSPACE_SRGB_LINEAR for floating point formats, SDL_COLORSPACE_HDR10 for 10-bit formats, SDL_COLORSPACE_SRGB for other RGB surfaces and SDL_COLORSPACE_BT709_FULL for YUV textures.

Returns: the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if the surface is NULL.

◆ GetImages()

OwnArray< SurfaceRef > SDL::SurfaceBase::GetImages ( ) const

inline

This returns all versions of a surface, with the surface being queried as the first element in the returned array.

Returns: a NULL terminated array of SDL_Surface pointers or NULL on failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: AddAlternateImage(); RemoveAlternateImages(); HasAlternateImages()

◆ GetMod()

Color SDL::SurfaceBase::GetMod ( ) const

inline

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

◆ GetPalette()

PaletteRef SDL::SurfaceBase::GetPalette ( ) const

inline

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

◆ GetProperties()

PropertiesRef SDL::SurfaceBase::GetProperties ( ) const

inline

The following properties are understood by SDL:

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

Returns: a valid property ID on success or 0 on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ HasAlternateImages()

bool SDL::SurfaceBase::HasAlternateImages ( ) const

inline

Returns: true if alternate versions are available or false otherwise.

Since: This function is available since SDL 3.2.0.

See also: AddAlternateImage(); RemoveAlternateImages(); GetImages()

◆ HasColorKey()

bool SDL::SurfaceBase::HasColorKey ( ) const

inline

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

◆ HasRLE()

bool SDL::SurfaceBase::HasRLE ( ) const

inline

Returns: true if the surface is RLE enabled, false otherwise.

◆ Lock()

SurfaceLock SDL::SurfaceBase::Lock ( ) &

inline

Between calls to SurfaceBase.Lock() / Unlock(), you can write to and read from GetPixels(), using the pixel format stored in GetFormat(). Once you are done accessing the surface, you should use Unlock() to release it or let the destructor take care of this for you.

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

Returns: SurfaceLock object on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: MustLock(); SurfaceLock.Unlock()

◆ MapColor() [1/3]

Uint32 SDL::SurfaceBase::MapColor ( SDL_Color color ) const

inline

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

color the color components

Returns: a pixel value.

◆ MapColor() [2/3]

Uint32 SDL::SurfaceBase::MapColor	(	Uint8	r,
		Uint8	g,
		Uint8	b
	)		const

inline

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.

◆ MapColor() [3/3]

Uint32 SDL::SurfaceBase::MapColor	(	Uint8	r,
		Uint8	g,
		Uint8	b,
		Uint8	a
	)		const

inline

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

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.
a	the alpha component of the pixel in the range 0-255.

Returns: a pixel value.

◆ MustLock()

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

inlineconstexpr

Since: This macro is available since SDL 3.2.0.

◆ PremultiplyAlpha()

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

inline

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

Since: This function is available since SDL 3.2.0.

◆ ReadPixel() [1/5]

Color SDL::SurfaceBase::ReadPixel ( const SDL_Point & 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.

◆ ReadPixel() [2/5]

void SDL::SurfaceBase::ReadPixel	(	const SDL_Point &	p,
		float *	r,
		float *	g,
		float *	b,
		float *	a
	)		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.
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 is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadPixel() [3/5]

void SDL::SurfaceBase::ReadPixel	(	const SDL_Point &	p,
		SDL_Color *	c
	)		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.
c	a color pointer to be filled with the color information. Must not be nullptr.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

◆ ReadPixel() [4/5]

void SDL::SurfaceBase::ReadPixel	(	const SDL_Point &	p,
		SDL_FColor *	c
	)		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.
c	a color pointer to be filled with the color information. Must not be nullptr.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

◆ ReadPixel() [5/5]

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

inline

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

Since: This function is available since SDL 3.2.0.

◆ RemoveAlternateImages()

void SDL::SurfaceBase::RemoveAlternateImages ( )

inline

This function removes a reference from all the alternative versions, destroying them if this is the last reference to them.

Since: This function is available since SDL 3.2.0.

See also: AddAlternateImage(); GetImages(); HasAlternateImages()

◆ ResetClipRect()

void SDL::SurfaceBase::ResetClipRect ( )

inline

See also: SetClipRect()

◆ SetAlphaMod()

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

inline

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

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.GetAlphaMod; SurfaceBase.SetColorMod

◆ SetBlendMode()

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

inline

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

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.GetBlendMode

◆ SetClipRect()

bool SDL::SurfaceBase::SetClipRect ( OptionalRef< const SDL_Rect > rect )

inline

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 SDL_Rect structure representing the clipping rectangle or nullopt to disable it

Returns: true if the rectangle intersects the surface, otherwise false and blits will be completely clipped.

Since: This function is available since SDL 3.2.0.

See also: ResetClipRect()

◆ SetColorKey() [1/2]

void SDL::SurfaceBase::SetColorKey ( Color key )

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.

It is a pixel of the format used by the surface, as generated by SDL_MapRGB().

Parameters

key	the transparent pixel color.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: GetColorKey(); SetRLE(); HasColorKey()

◆ SetColorKey() [2/2]

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

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.

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

Since: This function is available since SDL 3.2.0.

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

◆ SetColorMod()

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

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)

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

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.GetColorMod; SurfaceBase.SetAlphaMod

◆ SetColorspace()

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

inline

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

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.GetColorspace

◆ SetMod()

void SDL::SurfaceBase::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.

◆ SetPalette()

void SDL::SurfaceBase::SetPalette ( PaletteBase & palette )

inline

A single palette can be shared with many surfaces.

Parameters

palette the PaletteBase structure to use.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: PaletteBase.PaletteBase; SurfaceBase.GetPalette

◆ SetRLE()

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

inline

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

Since: This function is available since SDL 3.2.0.

See also: SurfaceBase.Blit; SurfaceBase.Lock; SurfaceLock.Unlock

◆ Stretch()

void SDL::SurfaceBase::Stretch	(	const SurfaceBase &	src,
		const SDL_Rect &	srcrect,
		const SDL_Rect &	dstrect,
		ScaleMode	scaleMode
	)

inline

Parameters

src	the Surface structure to be copied from.
srcrect	the Rect structure representing the rectangle to be copied.
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.4.

See also: SurfaceBase.BlitScaled

◆ WritePixel() [1/2]

void SDL::SurfaceBase::WritePixel	(	const SDL_Point &	p,
		SDL_Color	c
	)

inline

This function prioritizes correctness over speed: it is suitable for unit tests, but is not intended for use in a game engine.

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

Since: This function is available since SDL 3.2.0.

◆ WritePixel() [2/2]

void SDL::SurfaceBase::WritePixel	(	const SDL_Point &	p,
		SDL_FColor	c
	)

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.
c	the color values, normally in the range 0-1.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

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

SDL3pp/SDL3pp_surface.h
SDL3pp/SDL3pp_image.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ SurfaceBase() [1/4]

◆ SurfaceBase() [2/4]

◆ SurfaceBase() [3/4]

◆ SurfaceBase() [4/4]

Member Function Documentation

◆ AddAlternateImage()

◆ Blit() [1/2]

◆ Blit() [2/2]

◆ Blit9Grid()

◆ Blit9GridWithScale()

◆ BlitScaled()

◆ BlitTiled()

◆ BlitTiledWithScale()

◆ BlitUnchecked()

◆ BlitUncheckedScaled()

◆ Clear()

◆ ClearColorKey()

◆ CreatePalette()

◆ Fill() [1/2]

◆ Fill() [2/2]

◆ FillRect() [1/2]

◆ FillRect() [2/2]

◆ FillRects() [1/2]

◆ FillRects() [2/2]

◆ Flip()

◆ GetAlphaMod()

◆ GetBlendMode()

◆ GetClipRect()

◆ GetColorKey() [1/3]

◆ GetColorKey() [2/3]

◆ GetColorKey() [3/3]

◆ GetColorMod()

◆ GetColorspace()

◆ GetImages()

◆ GetMod()

◆ GetPalette()

◆ GetProperties()

◆ HasAlternateImages()

◆ HasColorKey()

◆ HasRLE()

◆ Lock()

◆ MapColor() [1/3]

◆ MapColor() [2/3]

◆ MapColor() [3/3]

◆ MustLock()

◆ PremultiplyAlpha()

◆ ReadPixel() [1/5]

◆ ReadPixel() [2/5]

◆ ReadPixel() [3/5]

◆ ReadPixel() [4/5]

◆ ReadPixel() [5/5]

◆ RemoveAlternateImages()

◆ ResetClipRect()

◆ SetAlphaMod()

◆ SetBlendMode()

◆ SetClipRect()

◆ SetColorKey() [1/2]

◆ SetColorKey() [2/2]

◆ SetColorMod()

◆ SetColorspace()

◆ SetMod()

◆ SetPalette()

◆ SetRLE()

◆ Stretch()

◆ WritePixel() [1/2]

◆ WritePixel() [2/2]