Handle to an owned texture. More...

Inheritance diagram for SDL::Texture:

[legend]

Public Member Functions
void	Destroy ()
	Destroy the specified texture.

TextureShared	share ()
	Move this texture into a TextureShared.

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< TextureRef >
constexpr	ResourceUnique (std::nullptr_t=nullptr)
	Default constructor.

constexpr	ResourceUnique (base::value_type value, DefaultDeleter< TextureRef > 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 Texture	Load (RendererRef renderer, StringParam file)
	Load an image from a filesystem path into a software surface.

static Texture	Load (RendererRef renderer, IOStreamRef src)
	Load an image from a filesystem path into a software surface.

static Texture	LoadBMP (RendererRef renderer, StringParam file)
	Load a BMP texture from a file.

static Texture	LoadBMP (RendererRef renderer, IOStreamRef src)
	Load a BMP texture from a seekable SDL data stream.

static Texture	Create (RendererRef renderer, PixelFormat format, TextureAccess access, const SDL_Point &size)
	Create a texture for a rendering context.

static Texture	CreateFromSurface (RendererRef renderer, SurfaceRef surface)
	Create a texture from an existing surface.

static Texture	CreateWithProperties (RendererRef renderer, PropertiesRef props)
	Create a texture for a rendering context with the specified properties.

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: TextureRef

Member Function Documentation

◆ Create()

static Texture SDL::Texture::Create	(	RendererRef	renderer,
		PixelFormat	format,
		TextureAccess	access,
		const SDL_Point &	size
	)

inlinestatic

The contents of a texture when first created are not defined.

Parameters

renderer	the rendering context.
format	one of the enumerated values in PixelFormat.
access	one of the enumerated values in TextureAccess.
size	the width and height of the texture in pixels.

Returns: the created texture on success

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Texture.CreateFromSurface; Texture.CreateWithProperties; Texture.Destroy; TextureRef.Update

◆ CreateFromSurface()

static Texture SDL::Texture::CreateFromSurface	(	RendererRef	renderer,
		SurfaceRef	surface
	)

inlinestatic

The surface is not modified or freed by this function.

The TextureAccess hint for the created texture is TEXTUREACCESS_STATIC.

The pixel format of the created texture may be different from the pixel format of the surface, and can be queried using the prop::Texture.FORMAT_NUMBER property.

Parameters

renderer	the rendering context.
surface	the SurfaceRef structure containing pixel data used to fill the texture.

Returns: the created texture is convertible to true on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Texture.Create; Texture.CreateWithProperties; Texture.Destroy

◆ CreateWithProperties()

static Texture SDL::Texture::CreateWithProperties	(	RendererRef	renderer,
		PropertiesRef	props
	)

inlinestatic

These are the supported properties:

prop::Texture.CREATE_COLORSPACE_NUMBER: an Colorspace value describing the texture colorspace, defaults to COLORSPACE_SRGB_LINEAR for floating point textures, COLORSPACE_HDR10 for 10-bit textures, COLORSPACE_SRGB for other RGB textures and COLORSPACE_JPEG for YUV textures.
prop::Texture.CREATE_FORMAT_NUMBER: one of the enumerated values in PixelFormat, defaults to the best RGBA format for the renderer
prop::Texture.CREATE_ACCESS_NUMBER: one of the enumerated values in TextureAccess, defaults to TEXTUREACCESS_STATIC
prop::Texture.CREATE_WIDTH_NUMBER: the width of the texture in pixels, required
prop::Texture.CREATE_HEIGHT_NUMBER: the height of the texture in pixels, required
prop::Texture.CREATE_SDR_WHITE_POINT_FLOAT: for HDR10 and floating point textures, this defines the value of 100% diffuse white, with higher values being displayed in the High Dynamic Range headroom. This defaults to 100 for HDR10 textures and 1.0 for floating point textures.
prop::Texture.CREATE_HDR_HEADROOM_FLOAT: for HDR10 and floating point textures, this defines the maximum dynamic range used by the content, in terms of the SDR white point. This would be equivalent to maxCLL / prop::Texture.CREATE_SDR_WHITE_POINT_FLOAT for HDR10 content. If this is defined, any values outside the range supported by the display will be scaled into the available HDR headroom, otherwise they are clipped.

With the direct3d11 renderer:

prop::Texture.CREATE_D3D11_TEXTURE_POINTER: the ID3D11Texture2D associated with the texture, if you want to wrap an existing texture.
prop::Texture.CREATE_D3D11_TEXTURE_U_POINTER: the ID3D11Texture2D associated with the U plane of a YUV texture, if you want to wrap an existing texture.
prop::Texture.CREATE_D3D11_TEXTURE_V_POINTER: the ID3D11Texture2D associated with the V plane of a YUV texture, if you want to wrap an existing texture.

With the direct3d12 renderer:

prop::Texture.CREATE_D3D12_TEXTURE_POINTER: the ID3D12Resource associated with the texture, if you want to wrap an existing texture.
prop::Texture.CREATE_D3D12_TEXTURE_U_POINTER: the ID3D12Resource associated with the U plane of a YUV texture, if you want to wrap an existing texture.
prop::Texture.CREATE_D3D12_TEXTURE_V_POINTER: the ID3D12Resource associated with the V plane of a YUV texture, if you want to wrap an existing texture.

With the metal renderer:

prop::Texture.CREATE_METAL_PIXELBUFFER_POINTER: the CVPixelBufferRef associated with the texture, if you want to create a texture from an existing pixel buffer.

With the opengl renderer:

prop::Texture.CREATE_OPENGL_TEXTURE_NUMBER: the GLuint texture associated with the texture, if you want to wrap an existing texture.
prop::Texture.CREATE_OPENGL_TEXTURE_UV_NUMBER: the GLuint texture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.
prop::Texture.CREATE_OPENGL_TEXTURE_U_NUMBER: the GLuint texture associated with the U plane of a YUV texture, if you want to wrap an existing texture.
prop::Texture.CREATE_OPENGL_TEXTURE_V_NUMBER: the GLuint texture associated with the V plane of a YUV texture, if you want to wrap an existing texture.

With the opengles2 renderer:

prop::Texture.CREATE_OPENGLES2_TEXTURE_NUMBER: the GLuint texture associated with the texture, if you want to wrap an existing texture.
prop::Texture.CREATE_OPENGLES2_TEXTURE_NUMBER: the GLuint texture associated with the texture, if you want to wrap an existing texture.
prop::Texture.CREATE_OPENGLES2_TEXTURE_UV_NUMBER: the GLuint texture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.
prop::Texture.CREATE_OPENGLES2_TEXTURE_U_NUMBER: the GLuint texture associated with the U plane of a YUV texture, if you want to wrap an existing texture.
prop::Texture.CREATE_OPENGLES2_TEXTURE_V_NUMBER: the GLuint texture associated with the V plane of a YUV texture, if you want to wrap an existing texture.

With the vulkan renderer:

prop::Texture.CREATE_VULKAN_TEXTURE_NUMBER: the VkImage with layout VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL associated with the texture, if you want to wrap an existing texture.

Parameters

renderer	the rendering context.
props	the properties to use.

Returns: the created texture is convertible to true on success.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Properties.Create; Texture.Create; Texture.CreateFromSurface; Texture.Destroy; TextureRef.GetSize; TextureRef.Update

◆ Destroy()

void SDL::Texture::Destroy ( )

inline

Passing nullptr or an otherwise invalid texture will set the SDL error message to "Invalid texture".

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Texture.Create; Texture.CreateFromSurface

◆ Load() [1/2]

Texture SDL::Texture::Load	(	RendererRef	renderer,
		IOStreamRef	src
	)

inlinestatic

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

Parameters

renderer	the rendering context.
src	an IOStreamRef to load an image from.

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

See also: Texture.Texture(RendererRef, IOStreamRef); LoadTexture(RendererRef, IOStreamRef); Texture.LoadBMP(RendererRef, IOStreamRef)

◆ Load() [2/2]

Texture SDL::Texture::Load	(	RendererRef	renderer,
		StringParam	file
	)

inlinestatic

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

Parameters

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

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

See also: Texture.Texture(RendererRef, StringParam); LoadTexture(RendererRef, StringParam); Texture.LoadBMP(RendererRef, StringParam)

◆ LoadBMP() [1/2]

static Texture SDL::Texture::LoadBMP	(	RendererRef	renderer,
		IOStreamRef	src
	)

inlinestatic

Parameters

renderer	the renderer to create texture
src	the data stream for the surface.

Returns: a Texture with loaded content or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ LoadBMP() [2/2]

static Texture SDL::Texture::LoadBMP	(	RendererRef	renderer,
		StringParam	file
	)

inlinestatic

Parameters

renderer	the renderer to create texture
file	the BMP file to load.

Returns: a Texture with loaded content or nullptr on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

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

SDL3pp/SDL3pp_render.h
SDL3pp/SDL3pp_image.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ Create()

◆ CreateFromSurface()

◆ CreateWithProperties()

◆ Destroy()

◆ Load() [1/2]

◆ Load() [2/2]

◆ LoadBMP() [1/2]

◆ LoadBMP() [2/2]