Texture wrapper that internally reuses resources when multiple Texture objects are loaded from the same file. More...

#include <TGUI/Texture.hpp>

Public Types
using	CallbackFunc = std::function<void(std::shared_ptr<TextureData>)>

using	BackendTextureLoaderFunc = std::function<bool(BackendTexture&, const String&, bool smooth)>

using	TextureLoaderFunc = std::function<std::shared_ptr<TextureData>(Texture&, const String&, bool smooth)>

Public Member Functions
	Texture ()=default
	Default constructor.

	Texture (const char *id, const UIntRect &partRect=UIntRect(0, 0, 0, 0), const UIntRect &middlePart=UIntRect(0, 0, 0, 0), bool smooth=m_defaultSmooth)
	Constructor that created the texture.

	Texture (const String &id, const UIntRect &partRect=UIntRect(0, 0, 0, 0), const UIntRect &middlePart=UIntRect(0, 0, 0, 0), bool smooth=m_defaultSmooth)
	Constructor that created the texture.

	Texture (const sf::Texture &texture, const UIntRect &partRect=UIntRect(0, 0, 0, 0), const UIntRect &middlePart=UIntRect(0, 0, 0, 0))
	Constructor that created the texture from an existing sf::Texture.

	Texture (const Texture &)
	Copy constructor.

	Texture (Texture &&) noexcept
	Move constructor.

	~Texture ()
	Destructor.

Texture &	operator= (const Texture &)
	Overload of copy assignment operator.

Texture &	operator= (Texture &&) noexcept
	Move assignment.

void	load (const String &id, const UIntRect &partRect={}, const UIntRect &middleRect={}, bool smooth=m_defaultSmooth)
	Creates the texture.

void	load (const sf::Texture &texture, const UIntRect &partRect={}, const UIntRect &middleRect={})
	Creates the texture from an existing sf::Texture.

void	loadFromMemory (const std::uint8_t *data, std::size_t dataSize, const UIntRect &partRect={}, const UIntRect &middleRect={}, bool smooth=m_defaultSmooth)
	Loads the texture from memory (data in memory should contain the entire file, not just the pixels)

void	loadFromPixelData (Vector2u size, const std::uint8_t *pixels, const UIntRect &partRect={}, const UIntRect &middleRect={}, bool smooth=m_defaultSmooth)
	Loads the texture from an array of 32-bits RGBA pixels.

void	loadFromBase64 (CharStringView imageAsBase64, const UIntRect &partRect={}, const UIntRect &middleRect={}, bool smooth=m_defaultSmooth)
	Loads the texture from a base64 string.

const String &	getId () const
	Returns the id that was used to load the texture (for the default loader, the id is the filename)

std::shared_ptr< TextureData >	getData () const
	Returns the texture data.

Vector2u	getImageSize () const
	Returns the size that the loaded image, or the size of the part if only a part of the image is loaded.

UIntRect	getPartRect () const
	Returns which part of the image was loaded.

bool	isSmooth () const
	Tells whether the smooth filter is enabled or not.

void	setColor (const Color &color)
	Sets the global color of the texture.

const Color &	getColor () const
	Returns the global color of the texture.

void	setShader (sf::Shader *shader)
	Sets the shader used to draw the texture.

sf::Shader *	getShader () const
	Returns the shader used to draw the texture.

void	setMiddleRect (const UIntRect &middleRect)
	Sets the middle part of the image for 9-slice scaling (relative to the part defined by partRect)

UIntRect	getMiddleRect () const
	Returns the middle rect of the texture which is used for 9-slice scaling.

bool	isTransparentPixel (Vector2u pos) const
	Checks if a certain pixel is transparent.

void	setCopyCallback (const CallbackFunc &func)
	Sets a callback function for when this texture is copied.

void	setDestructCallback (const CallbackFunc &func)
	Sets a callback function for when this texture is destroyed.

bool	operator== (const Texture &right) const
	Compares the texture with another one.

bool	operator!= (const Texture &right) const
	Compares the texture with another one.

Static Public Member Functions
static void	setDefaultSmooth (bool smooth)
	Changes whether textures are smoothed by default or not.

static bool	getDefaultSmooth ()
	Returns whether textures are smoothed by default or not.

static void	setBackendTextureLoader (const BackendTextureLoaderFunc &func)
	Sets a different backend texture loader.

static const BackendTextureLoaderFunc &	getBackendTextureLoader ()
	Returns the used backend texture loader.

static void	setTextureLoader (const TextureLoaderFunc &func)
	Sets a different texture loader.

static const TextureLoaderFunc &	getTextureLoader ()
	Returns the used texture loader.

Detailed Description

Texture wrapper that internally reuses resources when multiple Texture objects are loaded from the same file.

Constructor & Destructor Documentation

◆ Texture() [1/3]

tgui::Texture::Texture	(	const char *	id,
		const UIntRect &	partRect = UIntRect(0, 0, 0, 0),
		const UIntRect &	middlePart = UIntRect(0, 0, 0, 0),
		bool	smooth = m_defaultSmooth )

inline

Constructor that created the texture.

Parameters

id	Id for the the image to load (for the default loader, the id is the filename)
partRect	Load only part of the image. Pass an empty rectangle if you want to load the full image
middlePart	Choose the middle part of the image for 9-slice scaling (relative to the part defined by partRect)
smooth	Enable smoothing on the texture

Exceptions

Exception when loading failed

◆ Texture() [2/3]

tgui::Texture::Texture	(	const String &	id,
		const UIntRect &	partRect = UIntRect(0, 0, 0, 0),
		const UIntRect &	middlePart = UIntRect(0, 0, 0, 0),
		bool	smooth = m_defaultSmooth )

Constructor that created the texture.

Parameters

id	Id for the the image to load (for the default loader, the id is the filename)
partRect	Load only part of the image. Pass an empty rectangle if you want to load the full image
middlePart	Choose the middle part of the image for 9-slice scaling (relative to the part defined by partRect)
smooth	Enable smoothing on the texture

This constructor just calls the corresponding load function.

Exceptions

Exception when loading failed

◆ Texture() [3/3]

tgui::Texture::Texture	(	const sf::Texture &	texture,
		const UIntRect &	partRect = UIntRect(0, 0, 0, 0),
		const UIntRect &	middlePart = UIntRect(0, 0, 0, 0) )

Constructor that created the texture from an existing sf::Texture.

Parameters

texture	Existing texture to copy
partRect	Load only part of the image. Pass an empty rectangle if you want to load the full image
middlePart	Choose the middle part of the image for 9-slice scaling (relative to the part defined by partRect)

The texture will be copied, you do not have to keep the sf::Texture alive after calling this function.

This constructor just calls the corresponding load function.

Deprecated: Replaced by using Texture() and loadFromPixelData(texture.getSize(), texture.copyToImage().getPixelsPtr()) in TGUI 1.1 to make it more clear that this is a memory-intensive constructor that should be avoided.

Member Function Documentation

◆ getBackendTextureLoader()

static const BackendTextureLoaderFunc & tgui::Texture::getBackendTextureLoader ( )

staticnodiscard

Returns the used backend texture loader.

Returns: Backend texture loader that is currently being used

See also: setBackendTextureLoader

◆ getColor()

const Color & tgui::Texture::getColor ( ) const

nodiscard

Returns the global color of the texture.

This color is modulated (multiplied) with the pixel color. It can be used to colorize the texture, or change its global opacity. Note that the alpha component is multiplied with the opacity of the widget.

By default, the texture's color is opaque white.

Returns: Current color of the texture

◆ getData()

std::shared_ptr< TextureData > tgui::Texture::getData ( ) const

nodiscard

Returns the texture data.

Returns: Data of the texture

◆ getDefaultSmooth()

static bool tgui::Texture::getDefaultSmooth ( )

staticnodiscard

Returns whether textures are smoothed by default or not.

Returns: True if smoothing is enabled by default, false if it is disabled

Smoothed textures are rendered with bilinear interpolation (default). Turning smoothing off will switch rendering to nearest neighbor interpolation.

◆ getId()

const String & tgui::Texture::getId ( ) const

nodiscard

Returns the id that was used to load the texture (for the default loader, the id is the filename)

Returns: Id of the texture

◆ getImageSize()

Vector2u tgui::Texture::getImageSize ( ) const

nodiscard

Returns the size that the loaded image, or the size of the part if only a part of the image is loaded.

Returns: Size of the image like it was when loaded (no scaling applied)

◆ getMiddleRect()

UIntRect tgui::Texture::getMiddleRect ( ) const

nodiscard

Returns the middle rect of the texture which is used for 9-slice scaling.

Returns: Middle rect of the texture

◆ getPartRect()

UIntRect tgui::Texture::getPartRect ( ) const

nodiscard

Returns which part of the image was loaded.

Returns: Part of the image that was loaded

◆ getShader()

sf::Shader * tgui::Texture::getShader ( ) const

nodiscard

Returns the shader used to draw the texture.

Returns: Shader currently being use to draw the texture

◆ getTextureLoader()

static const TextureLoaderFunc & tgui::Texture::getTextureLoader ( )

staticnodiscard

Returns the used texture loader.

Returns: Texture loader that is currently being used

See also: setTextureLoader

◆ isSmooth()

bool tgui::Texture::isSmooth ( ) const

nodiscard

Tells whether the smooth filter is enabled or not.

Returns: True if smoothing is enabled, false if it is disabled

◆ isTransparentPixel()

bool tgui::Texture::isTransparentPixel ( Vector2u pos ) const

nodiscard

Checks if a certain pixel is transparent.

Parameters

pos	Coordinate of the pixel

Returns: True when the pixel is transparent, false when it is not

◆ load() [1/2]

void tgui::Texture::load	(	const sf::Texture &	texture,
		const UIntRect &	partRect = {},
		const UIntRect &	middleRect = {} )

Creates the texture from an existing sf::Texture.

Parameters

texture	Existing texture to copy
partRect	Load only part of the texture. Don't pass this parameter if you want to load the full image
middleRect	Choose the middle part of the image for 9-slice scaling (relative to the part defined by partRect)

The texture will be copied, you do not have to keep the sf::Texture alive after calling this function.

Exceptions

Exception when loading failed

Deprecated: Replaced by loadFromPixelData(texture.getSize(), texture.copyToImage().getPixelsPtr()) in TGUI 1.1 to make it more clear that this is a memory-intensive function that should be avoided.

◆ load() [2/2]

void tgui::Texture::load	(	const String &	id,
		const UIntRect &	partRect = {},
		const UIntRect &	middleRect = {},
		bool	smooth = m_defaultSmooth )

Creates the texture.

Parameters

id	Id for the the image to load (for the default loader, the id is the filename)
partRect	Load only part of the image. Don't pass this parameter if you want to load the full image
middleRect	Choose the middle part of the image for 9-slice scaling (relative to the part defined by partRect)
smooth	Enable smoothing on the texture

Exceptions

Exception when loading failed

◆ loadFromBase64()

void tgui::Texture::loadFromBase64	(	CharStringView	imageAsBase64,
		const UIntRect &	partRect = {},
		const UIntRect &	middleRect = {},
		bool	smooth = m_defaultSmooth )

Loads the texture from a base64 string.

Parameters

imageAsBase64	Character array with the base64-encoded image (the entire file, not just the pixel data)
partRect	Load only part of the texture. Don't pass this parameter if you want to load the full image
middleRect	Choose the middle part of the image for 9-slice scaling (relative to the part defined by partRect)
smooth	Enable smoothing on the texture

Note that imageAsBase64 is just the base64 data (of the entire file), it should NOT start with a prefix like "data:".

Exceptions

Exception when loading failed

◆ loadFromMemory()

void tgui::Texture::loadFromMemory	(	const std::uint8_t *	data,
		std::size_t	dataSize,
		const UIntRect &	partRect = {},
		const UIntRect &	middleRect = {},
		bool	smooth = m_defaultSmooth )

Loads the texture from memory (data in memory should contain the entire file, not just the pixels)

Parameters

data	Pointer to the file in memory
dataSize	Amount of bytes of the file in memory
partRect	Load only part of the texture. Don't pass this parameter if you want to load the full image
middleRect	Choose the middle part of the image for 9-slice scaling (relative to the part defined by partRect)
smooth	Enable smoothing on the texture

Exceptions

Exception when loading failed

◆ loadFromPixelData()

void tgui::Texture::loadFromPixelData	(	Vector2u	size,
		const std::uint8_t *	pixels,
		const UIntRect &	partRect = {},
		const UIntRect &	middleRect = {},
		bool	smooth = m_defaultSmooth )

Loads the texture from an array of 32-bits RGBA pixels.

Parameters

size	Width and height of the image to create
pixels	Pointer to array of size.xsize.y4 bytes with RGBA pixels
partRect	Load only part of the texture. Don't pass this parameter if you want to load the full image
middleRect	Choose the middle part of the image for 9-slice scaling (relative to the part defined by partRect)
smooth	Enable smoothing on the texture

The pixels are copied by this function, you can free the buffer after calling this function.

Exceptions

Exception when loading failed

◆ setBackendTextureLoader()

static void tgui::Texture::setBackendTextureLoader ( const BackendTextureLoaderFunc & func )

static

Sets a different backend texture loader.

Parameters

func	New backend texture loader function

The backend texture loader will be called inside the texture loader to create the backend texture.

The default loader will simply load the image from a file.

◆ setColor()

void tgui::Texture::setColor ( const Color & color )

Sets the global color of the texture.

This color is modulated (multiplied) with the pixel color. It can be used to colorize the texture, or change its global opacity. Note that the alpha component is multiplied with the opacity of the widget.

By default, the texture's color is opaque white.

Parameters

color New color of the texture

◆ setCopyCallback()

void tgui::Texture::setCopyCallback ( const CallbackFunc & func )

Sets a callback function for when this texture is copied.

Parameters

func	Function that will be called when this texture is copied

This function can be useful when implementing a resource manager.

◆ setDefaultSmooth()

static void tgui::Texture::setDefaultSmooth ( bool smooth )

static

Changes whether textures are smoothed by default or not.

Parameters

smooth Enable smoothing on the texture by default

Smoothed textures are rendered with bilinear interpolation (default). Turning smoothing off will switch rendering to nearest neighbor interpolation.

Changing the default only affects new textures where smoothing isn't explicitly set. No existing textures are modified.

◆ setDestructCallback()

void tgui::Texture::setDestructCallback ( const CallbackFunc & func )

Sets a callback function for when this texture is destroyed.

Parameters

func	Function that will be called when this texture is destroyed

This function can be useful when implementing a resource manager.

◆ setMiddleRect()

void tgui::Texture::setMiddleRect ( const UIntRect & middleRect )

Sets the middle part of the image for 9-slice scaling (relative to the part defined by partRect)

Parameters

middleRect Middle rect of the texture

Since: TGUI 1.1

◆ setShader()

void tgui::Texture::setShader ( sf::Shader * shader )

Sets the shader used to draw the texture.

Parameters

shader New shader to use

◆ setTextureLoader()

static void tgui::Texture::setTextureLoader ( const TextureLoaderFunc & func )

static

Sets a different texture loader.

Parameters

func	New texture loader function

The texture loader will initialize this Texture object.

The default loader will use an internal texture manager to prevent the same thing from being loaded twice.

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

include/TGUI/Texture.hpp

TGUI

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Texture() [1/3]

◆ Texture() [2/3]

◆ Texture() [3/3]

Member Function Documentation

◆ getBackendTextureLoader()

◆ getColor()

◆ getData()

◆ getDefaultSmooth()

◆ getId()

◆ getImageSize()

◆ getMiddleRect()

◆ getPartRect()

◆ getShader()

◆ getTextureLoader()

◆ isSmooth()

◆ isTransparentPixel()

◆ load() [1/2]

◆ load() [2/2]

◆ loadFromBase64()

◆ loadFromMemory()

◆ loadFromPixelData()

◆ setBackendTextureLoader()

◆ setColor()

◆ setCopyCallback()

◆ setDefaultSmooth()

◆ setDestructCallback()

◆ setMiddleRect()

◆ setShader()

◆ setTextureLoader()