Handle to an owned surface. More...

Inheritance diagram for SDL::Surface:

[legend]

Public Member Functions
void	Destroy ()
	Free a surface.

SurfaceShared	share ()
	Move this surface into a SurfaceShared.

constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DELETER deleter={})
	Constructs from raw type.

constexpr	ResourceUnique (ResourceUnique &&other)
	Move constructor.

	ResourceUnique (const ResourceUnique &other)=delete

Public Member Functions inherited from SDL::ResourceUnique< SurfaceRef >
constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DefaultDeleter< SurfaceRef > deleter={})
	Constructs from raw type.

constexpr	ResourceUnique (ResourceUnique &&other)
	Move constructor.

	ResourceUnique (const ResourceUnique &other)=delete

	~ResourceUnique ()
	Destructor.

constexpr ResourceUnique &	operator= (ResourceUnique other)
	Assignment operator.

void	reset ()
	Resets the value, destroying the resource if not nullptr.

Public Member Functions inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
RESOURCE	release ()
	Returns reference and reset this.

Public Member Functions inherited from SDL::ResourcePtrBase< RESOURCE >
constexpr	operator bool () const
	Check if not null.

constexpr bool	operator== (const ResourcePtrBase &other) const
	Comparison.

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

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

constexpr reference	operator* () const
	Gets reference.

constexpr const reference *	operator-> () const
	Gets addressable reference.

constexpr reference *	operator-> ()
	Gets addressable reference.

reference	get () const
	Get reference.

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

static Surface	Load (IOStreamRef src)
	Load an image from a filesystem path into a software surface.

static Surface	LoadBMP (IOStreamRef src)
	Load a BMP image from a seekable SDL data stream.

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

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

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

Additional Inherited Members
Public Types inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
using	deleter = DELETER
	The deleter type.

Public Types inherited from SDL::ResourcePtrBase< RESOURCE >
using	reference = RESOURCE
	The reference resource type.

using	value_type = typename reference::value_type
	The raw resource type.

Protected Member Functions inherited from SDL::ResourceOwnerBase< RESOURCE, DELETER >
constexpr	ResourceOwnerBase (base::value_type value={}, DELETER deleter={})
	Constructs from raw type.

void	free ()
	Frees resource.

Protected Member Functions inherited from SDL::ResourcePtrBase< RESOURCE >
constexpr	ResourcePtrBase (value_type value={})
	Constructs from raw type.

reference &	get ()
	Get reference.

Detailed Description

Category:: Resource

See also: SurfaceRef

Member Function Documentation

◆ Create()

static Surface SDL::Surface::Create	(	const SDL_Point &	size,
		PixelFormat	format
	)

inlinestatic

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

See also: Surface.CreateFrom; Surface.Destroy

◆ CreateFrom()

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

inlinestatic

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

See also: Surface.Create; Surface.Destroy

◆ Destroy()

void SDL::Surface::Destroy ( )

inline

It is safe to pass nullptr to this function.

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

◆ Load() [1/2]

Surface SDL::Surface::Load ( IOStreamRef src )

inlinestatic

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

Parameters

src	an IOStreamRef to load an image from.

Returns: the new Surface with loaded contents on success or nullptr on failure; call GetError() for more information.

See also: LoadSurface(IOStreamRef); Surface.LoadBMP(IOStreamRef)

◆ Load() [2/2]

Surface SDL::Surface::Load ( StringParam file )

inlinestatic

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

Parameters

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

Returns: the new Surface with loaded contents on success or nullptr on failure; call GetError() for more information.

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

◆ LoadBMP() [1/2]

static Surface SDL::Surface::LoadBMP ( IOStreamRef src )

inlinestatic

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.

Returns: a pointer to a new SurfaceRef 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; Surface.LoadBMP; SaveBMP

◆ LoadBMP() [2/2]

static Surface SDL::Surface::LoadBMP ( StringParam file )

inlinestatic

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 SurfaceRef 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; Surface.LoadBMP; SaveBMP

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

SDL3pp/SDL3pp_surface.h
SDL3pp/SDL3pp_image.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Create()

◆ CreateFrom()

◆ Destroy()

◆ Load() [1/2]

◆ Load() [2/2]

◆ LoadBMP() [1/2]

◆ LoadBMP() [2/2]