Handle to a non owned texture. More...

Inheritance diagram for SDL::TextureRef:

[legend]

Public Member Functions
constexpr	TextureRef (const TextureRef &other)
	Copy constructor.

constexpr	TextureRef (TextureRef &&other)
	Move constructor.

constexpr	~TextureRef ()=default
	Default constructor.

TextureRef &	operator= (TextureRef other)
	Assignment operator.

void	reset (SDL_Texture *newResource={})
	Destroy the specified texture.

	TextureBase (RendererBase &renderer, StringParam file)
	Load an image from a filesystem path into a software surface.

	TextureBase (RendererBase &renderer, IOStream &src)
	Load an image from a IOStreamBase into a software surface.

	TextureBase (RendererBase &renderer, PixelFormat format, TextureAccess access, const SDL_Point &size)
	Create a texture for a rendering context.

	TextureBase (RendererBase &renderer, SurfaceBase &surface)
	Create a texture from an existing surface.

	TextureBase (RendererBase &renderer, PropertiesBase &props)
	Create a texture for a rendering context with the specified properties.

Public Member Functions inherited from SDL::TextureBase
	TextureBase (RendererBase &renderer, StringParam file)
	Load an image from a filesystem path into a software surface.

	TextureBase (RendererBase &renderer, IOStream &src)
	Load an image from a IOStreamBase into a software surface.

	TextureBase (RendererBase &renderer, PixelFormat format, TextureAccess access, const SDL_Point &size)
	Create a texture for a rendering context.

	TextureBase (RendererBase &renderer, SurfaceBase &surface)
	Create a texture from an existing surface.

	TextureBase (RendererBase &renderer, PropertiesBase &props)
	Create a texture for a rendering context with the specified properties.

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

RendererRef	GetRenderer () const
	Get the renderer that created an TextureBase.

void	SetMod (Color c)
	Set an additional color and alpha values multiplied into render copy operations.

void	SetMod (FColor c)
	Set an additional color and alpha values multiplied into render copy operations.

FColor	GetMod () const
	Get the additional color value multiplied into render copy operations.

void	GetMod (Color *c) const
	Get the additional color value multiplied into render copy operations.

void	GetMod (FColor *c) const
	Get the additional color value multiplied into render copy operations.

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

void	SetColorMod (float r, float g, float b)
	Set an additional color value multiplied into render copy operations.

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

void	GetColorMod (float r, float g, float *b) const
	Get the additional color value multiplied into render copy operations.

void	SetAlphaMod (Uint8 alpha)
	Set an additional alpha value multiplied into render copy operations.

void	SetAlphaMod (float alpha)
	Set an additional alpha value multiplied into render copy operations.

float	GetAlphaMod () const
	Get the additional alpha value multiplied into render copy operations.

void	GetAlphaMod (Uint8 *alpha) const
	Get the additional alpha value multiplied into render copy operations.

void	GetAlphaMod (float *alpha) const
	Get the additional alpha value multiplied into render copy operations.

void	SetBlendMode (BlendMode blendMode)
	Set the blend mode for a texture, used by RendererBase.RenderTexture().

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

void	SetScaleMode (ScaleMode scaleMode)
	Set the scale mode used for texture scale operations.

ScaleMode	GetScaleMode () const
	Get the scale mode used for texture scale operations.

void	Update (OptionalRef< const SDL_Rect > rect, const void *pixels, int pitch)
	Update the given texture rectangle with new pixel data.

void	UpdateYUV (OptionalRef< const SDL_Rect > rect, const Uint8 Yplane, int Ypitch, const Uint8 Uplane, int Upitch, const Uint8 *Vplane, int Vpitch)
	Update a rectangle within a planar YV12 or IYUV texture with new pixel data.

void	UpdateNV (OptionalRef< const SDL_Rect > rect, const Uint8 Yplane, int Ypitch, const Uint8 UVplane, int UVpitch)
	Update a rectangle within a planar NV12 or NV21 texture with new pixels.

TextureLock	Lock (OptionalRef< const SDL_Rect > rect={}) &
	Lock a portion of the texture for write-only pixel access.

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_Texture * >
constexpr	Resource (SDL_Texture * 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_Texture *	get () const
	Return contained resource;.

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

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

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

Detailed Description

Category:: Resource

See also: TextureBase; Texture

Member Function Documentation

◆ reset()

void SDL::TextureRef::reset ( SDL_Texture * newResource = {} )

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

◆ TextureBase() [1/5]

SDL::TextureBase::TextureBase	(	RendererBase &	renderer,
		IOStream &	src
	)

inline

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

Parameters

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

Postcondition: the new Texture with loaded contents on success.

Exceptions

Error on failure.

See also: LoadTexture(RendererBase&StringParam); LoadTextureBMP(RendererBase&, StringParam)

◆ TextureBase() [2/5]

SDL::TextureBase::TextureBase	(	RendererBase &	renderer,
		PixelFormat	format,
		TextureAccess	access,
		const SDL_Point &	size
	)

inline

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.

Postcondition: 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: TextureBase.GetSize; TextureBase.Update

◆ TextureBase() [3/5]

SDL::TextureBase::TextureBase	(	RendererBase &	renderer,
		PropertiesBase &	props
	)

inline

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.

Postcondition: 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.Properties; TextureBase.TextureBase; TextureBase.TextureBase; TextureRef.reset; TextureBase.GetSize; TextureBase.Update

◆ TextureBase() [4/5]

SDL::TextureBase::TextureBase	(	RendererBase &	renderer,
		StringParam	file
	)

inline

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.

Postcondition: the new Texture with loaded contents on success.

Exceptions

Error on failure.

See also: LoadTexture(RendererBase&, StringParam)

◆ TextureBase() [5/5]

SDL::TextureBase::TextureBase	(	RendererBase &	renderer,
		SurfaceBase &	surface
	)

inline

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 SurfaceBase structure containing pixel data used to fill the texture.

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

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

SDL3pp/SDL3pp_render.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ reset()

◆ TextureBase() [1/5]

◆ TextureBase() [2/5]

◆ TextureBase() [3/5]

◆ TextureBase() [4/5]

◆ TextureBase() [5/5]