Safe reference for Surface.

Inheritance diagram for SDL::SurfaceRef:

Collaboration diagram for SDL::SurfaceRef:

Public Member Functions
	SurfaceRef (SurfaceRaw resource) noexcept
	Constructs from SurfaceRaw. More...

constexpr	Surface (std::nullptr_t=nullptr) noexcept
	Default ctor.

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

constexpr	Surface (const Surface &other)
	Copy constructor.

constexpr	Surface (Surface &&other) noexcept
	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...

Public Member Functions inherited from SDL::Surface
constexpr	Surface (std::nullptr_t=nullptr) noexcept
	Default ctor.

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

constexpr	Surface (const Surface &other)
	Copy constructor.

constexpr	Surface (Surface &&other) noexcept
	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...

constexpr const SurfaceRaw	operator-> () const noexcept
	member access to underlying SurfaceRaw.

constexpr SurfaceRaw	operator-> () noexcept
	member access to underlying SurfaceRaw.

	~Surface ()
	Destructor.

constexpr Surface &	operator= (Surface &&other) noexcept
	Assignment operator.

constexpr Surface &	operator= (const Surface &other) noexcept=default
	Assignment operator.

constexpr SurfaceRaw	get () const noexcept
	Retrieves underlying SurfaceRaw.

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

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

constexpr	operator bool () const noexcept
	Converts to bool.

constexpr	operator SurfaceParam () const noexcept
	Converts to SurfaceParam.

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

constexpr bool	MustLock () const
	Evaluates to true if the surface needs to be locked before access. 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...

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 in BMP format. More...

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

void	SavePNG (StringParam file) const
	Save a surface to a file in PNG format. 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	Rotate (float angle)
	Return a copy of a surface rotated clockwise a number of degrees. 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 &c)
	Clear a surface with a specific color, with floating point precision. More...

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

void	Fill (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, 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, 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. 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...

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

Color	ReadPixel (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...

FColor	ReadPixelFloat (const PointRaw &p) 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.

Additional Inherited Members
Static Public Member Functions inherited from SDL::Surface
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...

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

static Surface	LoadPNG (StringParam file)
	Load a PNG image from a file. More...

Constructor & Destructor Documentation

◆ SurfaceRef()

SDL::SurfaceRef::SurfaceRef ( SurfaceRaw resource )

inlinenoexcept

Parameters

resource a SurfaceRaw.

This borrows the ownership, increments the refcount!

Member Function Documentation

◆ Surface() [1/5]

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() [2/5]

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

◆ Surface() [3/5]

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

inlineexplicitconstexprnoexcept

Parameters

resource a SurfaceRaw to be wrapped.

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

◆ Surface() [4/5]

SDL::Surface::Surface	(	IOStreamParam	src,
		bool	closeio = `false`
	)

inline

An Surface is a buffer of pixels in memory accessible by the CPU. Use this if you plan to hand the data to something else or manipulate it further in code.

There are no guarantees about what format the new Surface data will be; in many cases, SDL_image will attempt to supply a surface that exactly matches the provided image, but in others it might have to convert (either because the image is in a format that SDL doesn't directly support or because it's compressed data that could reasonably uncompress to various formats and SDL_image had to pick one). You can inspect an Surface for its specifics, and use Surface.Convert to then migrate to any supported format.

If the image format supports a transparent pixel, SDL will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling: Surface.SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

If closeio is true, src will be closed before returning, whether this function succeeds or not. SDL_image reads everything it needs from src during this call in any case.

There is a separate function to read files from disk without having to deal with IOStream: Surface.Surface("filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadSurfaceTyped(), which is equivalent to this function except a file extension (like "BMP", "JPG", etc) can be specified, in case SDL_image cannot autodetect the file format.

If you are using SDL's 2D rendering API, there is an equivalent call to load images directly into an Texture for use by the GPU without using a software surface: call Texture.Texture() instead.

Parameters

src	an IOStream that data will be read from.
closeio	true to close/free the IOStream before returning, false to leave it open.

Postcondition: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Surface.Surface; LoadSurfaceTyped; Surface.Destroy

◆ Surface() [5/5]

SDL::Surface::Surface ( StringParam file )

inline

An Surface is a buffer of pixels in memory accessible by the CPU. Use this if you plan to hand the data to something else or manipulate it further in code.

There are no guarantees about what format the new Surface data will be; in many cases, SDL_image will attempt to supply a surface that exactly matches the provided image, but in others it might have to convert (either because the image is in a format that SDL doesn't directly support or because it's compressed data that could reasonably uncompress to various formats and SDL_image had to pick one). You can inspect an Surface for its specifics, and use Surface.Convert to then migrate to any supported format.

If the image format supports a transparent pixel, SDL will set the colorkey for the surface. You can enable RLE acceleration on the surface afterwards by calling: Surface.SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);

There is a separate function to read files from an IOStream, if you need an i/o abstraction to provide data from anywhere instead of a simple filesystem read; that function is Surface.Surface().

If you are using SDL's 2D rendering API, there is an equivalent call to load images directly into an Texture for use by the GPU without using a software surface: call Texture.Texture() instead.

Parameters

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

Postcondition: a new SDL surface, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadSurfaceTyped; Surface.Surface; Surface.Destroy

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

SDL3pp/SDL3pp_surface.h

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ SurfaceRef()

Member Function Documentation

◆ Surface() [1/5]

◆ Surface() [2/5]

◆ Surface() [3/5]

◆ Surface() [4/5]

◆ Surface() [5/5]