An efficient driver-specific representation of pixel data. More...

Inheritance diagram for SDL::TextureRef:

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

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

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 RendererRef.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 from the underlying resource.

constexpr	Resource (const ResourceHandle< Resource< T > > auto &resource)
	Constructs from pointer like.

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

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

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

constexpr	Resource (const ResourceHandle< Resource< SDL_Texture * > > auto &resource)
	Constructs from pointer like.

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

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

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

constexpr	operator value_type () const
	Converts back to underlying type.

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 const SDL_Texture *	operator-> () const
	Access to fields.

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

Static Public Member Functions
static void	reset (SDL_Texture *resource)
	Destroy the specified texture.

Additional Inherited Members
Public Types inherited from SDL::Resource< SDL_Texture * >
using	value_type = SDL_Texture *
	The raw resource type.

Detailed Description

Since: This struct is available since SDL 3.2.0.

Category:: Resource

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

Member Function Documentation

◆ GetAlphaMod() [1/3]

float SDL::TextureRef::GetAlphaMod ( ) const

inline

Returns: the current alpha value on success.

Exceptions

Error on failure.

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

◆ GetAlphaMod() [2/3]

void SDL::TextureRef::GetAlphaMod ( float * alpha ) const

inline

Parameters

alpha a pointer filled in with the current alpha value.

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

◆ GetAlphaMod() [3/3]

void SDL::TextureRef::GetAlphaMod ( Uint8 * alpha ) const

inline

Parameters

alpha a pointer filled in with the current alpha value.

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

◆ GetBlendMode()

BlendMode SDL::TextureRef::GetBlendMode ( ) const

inline

Returns: the current SDL_BlendMode 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: TextureRef.SetBlendMode

◆ GetColorMod() [1/2]

void SDL::TextureRef::GetColorMod	(	float *	r,
		float *	g,
		float *	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 should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: TextureRef.GetAlphaMod; TextureRef.SetColorMod

◆ GetColorMod() [2/2]

void SDL::TextureRef::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 should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: TextureRef.GetAlphaMod; TextureRef.SetColorMod

◆ GetMod() [1/3]

FColor SDL::TextureRef::GetMod ( ) const

inline

Returns: the color channels (0-1) 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: GetAlphaMod(); SetColorMod()

◆ GetMod() [2/3]

void SDL::TextureRef::GetMod ( Color * c ) const

inline

Parameters

c	a pointer filled in with the current color and alpha mod values.

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: GetAlphaMod(); SetColorMod()

◆ GetMod() [3/3]

void SDL::TextureRef::GetMod ( FColor * c ) const

inline

Parameters

c	a pointer filled in with the current color and alpha mod values.

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: GetAlphaMod(); SetColorMod()

◆ GetProperties()

PropertiesRef SDL::TextureRef::GetProperties ( ) const

inline

The following read-only properties are provided by SDL:

prop::Texture.COLORSPACE_NUMBER: an Colorspace value describing the texture colorspace.
prop::Texture.FORMAT_NUMBER: one of the enumerated values in PixelFormat.
prop::Texture.ACCESS_NUMBER: one of the enumerated values in TextureAccess.
prop::Texture.WIDTH_NUMBER: the width of the texture in pixels.
prop::Texture.HEIGHT_NUMBER: the height of the texture in pixels.
prop::Texture.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 other textures.
prop::Texture.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. 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. This defaults to 1.0 for SDR textures, 4.0 for HDR10 textures, and no default for floating point textures.

With the direct3d11 renderer:

prop::Texture.D3D11_TEXTURE_POINTER: the ID3D11Texture2D associated with the texture
prop::Texture.D3D11_TEXTURE_U_POINTER: the ID3D11Texture2D associated with the U plane of a YUV texture
prop::Texture.D3D11_TEXTURE_V_POINTER: the ID3D11Texture2D associated with the V plane of a YUV texture

With the direct3d12 renderer:

prop::Texture.D3D12_TEXTURE_POINTER: the ID3D12Resource associated with the texture
prop::Texture.D3D12_TEXTURE_U_POINTER: the ID3D12Resource associated with the U plane of a YUV texture
prop::Texture.D3D12_TEXTURE_V_POINTER: the ID3D12Resource associated with the V plane of a YUV texture

With the vulkan renderer:

prop::Texture.VULKAN_TEXTURE_NUMBER: the VkImage associated with the texture

With the opengl renderer:

prop::Texture.OPENGL_TEXTURE_NUMBER: the GLuint texture associated with the texture
prop::Texture.OPENGL_TEXTURE_UV_NUMBER: the GLuint texture associated with the UV plane of an NV12 texture
prop::Texture.OPENGL_TEXTURE_U_NUMBER: the GLuint texture associated with the U plane of a YUV texture
prop::Texture.OPENGL_TEXTURE_V_NUMBER: the GLuint texture associated with the V plane of a YUV texture
prop::Texture.OPENGL_TEXTURE_TARGET_NUMBER: the GLenum for the texture target (GL_TEXTURE_2D, GL_TEXTURE_RECTANGLE_ARB, etc)
prop::Texture.OPENGL_TEX_W_FLOAT: the texture coordinate width of the texture (0.0 - 1.0)
prop::Texture.OPENGL_TEX_H_FLOAT: the texture coordinate height of the texture (0.0 - 1.0)

With the opengles2 renderer:

prop::Texture.OPENGLES2_TEXTURE_NUMBER: the GLuint texture associated with the texture
prop::Texture.OPENGLES2_TEXTURE_UV_NUMBER: the GLuint texture associated with the UV plane of an NV12 texture
prop::Texture.OPENGLES2_TEXTURE_U_NUMBER: the GLuint texture associated with the U plane of a YUV texture
prop::Texture.OPENGLES2_TEXTURE_V_NUMBER: the GLuint texture associated with the V plane of a YUV texture
prop::Texture.OPENGLES2_TEXTURE_TARGET_NUMBER: the GLenum for the texture target (GL_TEXTURE_2D, GL_TEXTURE_EXTERNAL_OES, etc)

Returns: a valid property 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.

◆ GetRenderer()

RendererRef SDL::TextureRef::GetRenderer ( ) const

inline

Returns: a pointer to the RendererRef that created the texture, 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.

◆ GetScaleMode()

ScaleMode SDL::TextureRef::GetScaleMode ( ) const

inline

Returns: the current scale mode 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: TextureRef.SetScaleMode

◆ reset()

static void SDL::TextureRef::reset ( SDL_Texture * resource )

inlinestatic

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

Parameters

resource the texture to destroy.

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

◆ SetAlphaMod() [1/2]

void SDL::TextureRef::SetAlphaMod ( float alpha )

inline

When this texture is rendered, during the copy operation the source alpha value is modulated by this alpha value according to the following formula:

srcA = srcA * alpha

Alpha modulation is not always supported by the renderer; it will return false if alpha modulation is not supported.

Parameters

alpha the source alpha value multiplied into copy operations.

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: TextureRef.GetAlphaMod; TextureRef.SetColorMod

◆ SetAlphaMod() [2/2]

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

inline

When this texture is rendered, during the copy operation the source alpha value is modulated by this alpha value according to the following formula:

srcA = srcA * (alpha / 255)

Alpha modulation is not always supported by the renderer; it will return false if alpha modulation is not supported.

Parameters

alpha the source alpha value multiplied into copy operations.

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: TextureRef.GetAlphaMod; TextureRef.SetColorMod

◆ SetBlendMode()

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

inline

If the blend mode is not supported, the closest supported mode is chosen and this function returns false.

Parameters

blendMode the BlendMode to use for texture blending.

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

◆ SetColorMod() [1/2]

void SDL::TextureRef::SetColorMod	(	float	r,
		float	g,
		float	b
	)

inline

When this texture is rendered, during the copy operation each source color channel is modulated by the appropriate color value according to the following formula:

srcC = srcC * color

Color modulation is not always supported by the renderer; it will return false if color modulation is not supported.

Parameters

r	the red color value multiplied into copy operations.
g	the green color value multiplied into copy operations.
b	the blue color value multiplied into copy operations.

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

◆ SetColorMod() [2/2]

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

inline

When this texture is rendered, during the copy operation each source color channel is modulated by the appropriate color value according to the following formula:

srcC = srcC * (color / 255)

Color modulation is not always supported by the renderer; it will return false if color modulation is not supported.

Parameters

r	the red color value multiplied into copy operations.
g	the green color value multiplied into copy operations.
b	the blue color value multiplied into copy operations.

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

◆ SetMod() [1/2]

void SDL::TextureRef::SetMod ( Color c )

inline

When this texture is rendered, during the copy operation each source color and alpha channels are modulated by the appropriate color value according to the following formula:

 srcC = srcC * (color / 255)
 srcA = srcA * (alpha / 255)

Color and alpha modulation is not always supported by the renderer; it will return false if either modulation is not supported.

Parameters

c	the color and alpha channel values multiplied into copy operations.

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.

◆ SetMod() [2/2]

void SDL::TextureRef::SetMod ( FColor c )

inline

When this texture is rendered, during the copy operation each source color and alpha channels are modulated by the appropriate color value according to the following formula:

 srcC = srcC * (color / 255)
 srcA = srcA * (alpha / 255)

Color and alpha modulation is not always supported by the renderer; it will return false if either modulation is not supported.

Parameters

c	the color and alpha channel values multiplied into copy operations.

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.

◆ SetScaleMode()

void SDL::TextureRef::SetScaleMode ( ScaleMode scaleMode )

inline

The default texture scale mode is SCALEMODE_LINEAR.

If the scale mode is not supported, the closest supported mode is chosen.

Parameters

scaleMode the ScaleMode to use for texture scaling.

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

◆ Update()

void SDL::TextureRef::Update	(	OptionalRef< const SDL_Rect >	rect,
		const void *	pixels,
		int	pitch
	)

inline

The pixel data must be in the pixel format of the texture, which can be queried using the prop::Texture.FORMAT_NUMBER property.

This is a fairly slow function, intended for use with static textures that do not change often.

If the texture is intended to be updated often, it is preferred to create the texture as streaming and use the locking functions referenced below. While this function will work with streaming textures, for optimization reasons you may not get the pixels back if you lock the texture afterward.

Parameters

rect	an Rect structure representing the area to update, or nullptr to update the entire texture.
pixels	the raw pixel data in the format of the texture.
pitch	the number of bytes in a row of pixel data, including padding between lines.

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: TextureRef.Lock; TextureLock.Unlock; TextureRef.UpdateNV; TextureRef.UpdateYUV

◆ UpdateNV()

void SDL::TextureRef::UpdateNV	(	OptionalRef< const SDL_Rect >	rect,
		const Uint8 *	Yplane,
		int	Ypitch,
		const Uint8 *	UVplane,
		int	UVpitch
	)

inline

You can use TextureRef.Update() as long as your pixel data is a contiguous block of NV12/21 planes in the proper order, but this function is available if your pixel data is not contiguous.

Parameters

rect	a pointer to the rectangle of pixels to update, or nullptr to update the entire texture.
Yplane	the raw pixel data for the Y plane.
Ypitch	the number of bytes between rows of pixel data for the Y plane.
UVplane	the raw pixel data for the UV plane.
UVpitch	the number of bytes between rows of pixel data for the UV plane.

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: TextureRef.Update; TextureRef.UpdateYUV

◆ UpdateYUV()

void SDL::TextureRef::UpdateYUV	(	OptionalRef< const SDL_Rect >	rect,
		const Uint8 *	Yplane,
		int	Ypitch,
		const Uint8 *	Uplane,
		int	Upitch,
		const Uint8 *	Vplane,
		int	Vpitch
	)

inline

You can use TextureRef.Update() as long as your pixel data is a contiguous block of Y and U/V planes in the proper order, but this function is available if your pixel data is not contiguous.

Parameters

rect	a pointer to the rectangle of pixels to update, or nullptr to update the entire texture.
Yplane	the raw pixel data for the Y plane.
Ypitch	the number of bytes between rows of pixel data for the Y plane.
Uplane	the raw pixel data for the U plane.
Upitch	the number of bytes between rows of pixel data for the U plane.
Vplane	the raw pixel data for the V plane.
Vpitch	the number of bytes between rows of pixel data for the V plane.

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: TextureRef.UpdateNV; TextureRef.Update

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

SDL3pp/SDL3pp_render.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ GetAlphaMod() [1/3]

◆ GetAlphaMod() [2/3]

◆ GetAlphaMod() [3/3]

◆ GetBlendMode()

◆ GetColorMod() [1/2]

◆ GetColorMod() [2/2]

◆ GetMod() [1/3]

◆ GetMod() [2/3]

◆ GetMod() [3/3]

◆ GetProperties()

◆ GetRenderer()

◆ GetScaleMode()

◆ reset()

◆ SetAlphaMod() [1/2]

◆ SetAlphaMod() [2/2]

◆ SetBlendMode()

◆ SetColorMod() [1/2]

◆ SetColorMod() [2/2]

◆ SetMod() [1/2]

◆ SetMod() [2/2]

◆ SetScaleMode()

◆ Update()

◆ UpdateNV()

◆ UpdateYUV()