Safe reference for Texture.

Inheritance diagram for SDL::TextureRef:

Collaboration diagram for SDL::TextureRef:

Public Member Functions
	TextureRef (TextureRaw resource) noexcept
	Constructs from TextureRaw. More...

	TextureRef (Texture resource) noexcept
	Constructs from Texture.

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

constexpr	Texture (const TextureRaw resource) noexcept
	Constructs from TextureParam. More...

constexpr	Texture (const Texture &other)
	Copy constructor.

constexpr	Texture (Texture &&other) noexcept
	Move constructor.

	Texture (RendererParam renderer, PixelFormat format, TextureAccess access, const PointRaw &size)
	Create a texture for a rendering context. More...

	Texture (RendererParam renderer, SurfaceParam surface)
	Create a texture from an existing surface. More...

	Texture (RendererParam renderer, PropertiesParam props)
	Create a texture for a rendering context with the specified properties. More...

	Texture (RendererParam renderer, StringParam file)
	Load an image from a filesystem path into a texture. More...

	Texture (RendererParam renderer, IOStreamParam src, bool closeio=false)
	Load an image from an SDL data source into a texture. More...

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

constexpr	Texture (const TextureRaw resource) noexcept
	Constructs from TextureParam. More...

constexpr	Texture (const Texture &other)
	Copy constructor.

constexpr	Texture (Texture &&other) noexcept
	Move constructor.

	Texture (RendererParam renderer, PixelFormat format, TextureAccess access, const PointRaw &size)
	Create a texture for a rendering context. More...

	Texture (RendererParam renderer, SurfaceParam surface)
	Create a texture from an existing surface. More...

	Texture (RendererParam renderer, PropertiesParam props)
	Create a texture for a rendering context with the specified properties. More...

	Texture (RendererParam renderer, StringParam file)
	Load an image from a filesystem path into a texture. More...

	Texture (RendererParam renderer, IOStreamParam src, bool closeio=false)
	Load an image from an SDL data source into a texture. More...

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

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

	~Texture ()
	Destructor.

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

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

constexpr TextureRaw	get () const noexcept
	Retrieves underlying TextureRaw.

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

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

constexpr	operator bool () const noexcept
	Converts to bool.

constexpr	operator TextureParam () const noexcept
	Converts to TextureParam.

void	Destroy ()
	Destroy the specified texture. More...

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

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

void	GetSize (float w, float h) const
	Get the size of a texture, as floating point values. More...

Point	GetSize () const
	Get the size of a texture.

FPoint	GetSizeFloat () const
	Get the size of a texture, as floating point values.

int	GetWidth () const
	Get the width in pixels.

int	GetHeight () const
	Get the height in pixels.

PixelFormat	GetFormat () const
	Get the pixel format.

void	SetPalette (PaletteParam palette)
	Set the palette used by a texture. More...

Palette	GetPalette ()
	Get the palette used by a texture. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void	Update (SurfaceConstParam surface, OptionalRef< const RectRaw > rect=std::nullopt)
	Update the given texture rectangle with new pixel data. More...

void	UpdateYUV (OptionalRef< const RectRaw > 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. More...

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

TextureLock	Lock (OptionalRef< const RectRaw > rect, void *pixels, int pitch)
	Lock a portion of the texture for write-only pixel access. More...

TextureSurfaceLock	LockToSurface (OptionalRef< const RectRaw > rect=std::nullopt)
	Lock a portion of the texture for write-only pixel access, and expose it as a SDL surface. More...

void	Unlock (TextureLock &&lock)
	Unlock a texture, uploading the changes to video memory, if needed. More...

void	Unlock (TextureSurfaceLock &&lock)
	Unlock a texture, uploading the changes to video memory, if needed. More...

Additional Inherited Members
Static Public Member Functions inherited from SDL::Texture
static constexpr Texture	Borrow (TextureParam resource)
	Safely borrows the from TextureParam. More...

Constructor & Destructor Documentation

◆ TextureRef()

SDL::TextureRef::TextureRef ( TextureRaw resource )

inlinenoexcept

Parameters

resource a TextureRaw.

This borrows the ownership, increments the refcount!

Member Function Documentation

◆ Texture() [1/6]

constexpr SDL::Texture::Texture ( const TextureRaw resource )

inlineexplicitconstexprnoexcept

Parameters

resource a TextureRaw to be wrapped.

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

◆ Texture() [2/6]

SDL::Texture::Texture	(	RendererParam	renderer,
		IOStreamParam	src,
		bool	closeio = `false`
	)

inline

An Texture represents an image in GPU memory, usable by SDL's 2D Render API. This can be significantly more efficient than using a CPU-bound Surface if you don't need to manipulate the image directly after loading it.

If the loaded image has transparency or a colorkey, a texture with an alpha channel will be created. Otherwise, SDL_image will attempt to create an Texture in the most format that most reasonably represents the image data (but in many cases, this will just end up being 32-bit RGB or 32-bit RGBA).

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: Texture.Texture(renderer, "filename.jpg") will call this function and manage those details for you, determining the file type from the filename's extension.

There is also LoadTextureTyped(), 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 would rather decode an image to an Surface (a buffer of pixels in CPU memory), call Surface.Surface() instead.

Parameters

renderer	the Renderer to use to create the texture.
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 texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: Texture.Texture; LoadTextureTyped

◆ Texture() [3/6]

SDL::Texture::Texture	(	RendererParam	renderer,
		PixelFormat	format,
		TextureAccess	access,
		const PointRaw &	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.

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.Texture; Texture.Texture; Texture.Destroy; Texture.GetSize; Texture.Update

◆ Texture() [4/6]

SDL::Texture::Texture	(	RendererParam	renderer,
		PropertiesParam	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_PALETTE_POINTER: an Palette to use with palettized texture formats. This can be set later with Texture.SetPalette()
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 associated with the texture, if you want to wrap an existing texture.
prop::Texture.CREATE_VULKAN_LAYOUT_NUMBER: the VkImageLayout for the VkImage, defaults to VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL.

With the GPU renderer:

prop::Texture.CREATE_GPU_TEXTURE_POINTER: the GPUTexture associated with the texture, if you want to wrap an existing texture.
SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_UV_NUMBER: the GPUTexture associated with the UV plane of an NV12 texture, if you want to wrap an existing texture.
SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_U_NUMBER: the GPUTexture associated with the U plane of a YUV texture, if you want to wrap an existing texture.
SDL_PROP_TEXTURE_CREATE_GPU_TEXTURE_V_NUMBER: the GPUTexture associated with the V plane of a YUV texture, if you want to wrap an existing texture.

Parameters

renderer	the rendering context.
props	the properties to use.

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.Texture; Texture.Texture; Texture.Destroy; Texture.GetSize; Texture.Update

◆ Texture() [5/6]

SDL::Texture::Texture	(	RendererParam	renderer,
		StringParam	file
	)

inline

An Texture represents an image in GPU memory, usable by SDL's 2D Render API. This can be significantly more efficient than using a CPU-bound Surface if you don't need to manipulate the image directly after loading it.

If the loaded image has transparency or a colorkey, a texture with an alpha channel will be created. Otherwise, SDL_image will attempt to create an Texture in the most format that most reasonably represents the image data (but in many cases, this will just end up being 32-bit RGB or 32-bit RGBA).

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 Texture.Texture().

If you would rather decode an image to an Surface (a buffer of pixels in CPU memory), call Surface.Surface() instead.

Parameters

renderer	the Renderer to use to create the texture.
file	a path on the filesystem to load an image from.

Postcondition: a new texture, or nullptr on error.

Since: This function is available since SDL_image 3.0.0.

See also: LoadTextureTyped; Texture.Texture

◆ Texture() [6/6]

SDL::Texture::Texture	(	RendererParam	renderer,
		SurfaceParam	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 Surface structure containing pixel data used to fill the texture.

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.Texture; Texture.Destroy

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

SDL3pp/SDL3pp_render.h

Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ TextureRef()

Member Function Documentation

◆ Texture() [1/6]

◆ Texture() [2/6]

◆ Texture() [3/6]

◆ Texture() [4/6]

◆ Texture() [5/6]

◆ Texture() [6/6]