Storage for multidimensional data, such as 2D images, on the GPU, combined with a sampler configuration that defines how to render the stored data. More...

#include <donut/graphics/Texture.hpp>

Public Member Functions
	Texture () noexcept=default
	Construct an empty texture without a value. More...

	Texture (TextureFormat internalFormat, std::size_t width, std::size_t height, PixelFormat pixelFormat, PixelComponentType pixelComponentType, const void *pixels, const TextureOptions &options={})
	Create a new texture object and allocate GPU memory for storing 2D image data. More...

	Texture (TextureFormat internalFormat, std::size_t width, std::size_t height, std::size_t depth, PixelFormat pixelFormat, PixelComponentType pixelComponentType, const void *pixels, const TextureOptions &options={})
	Create a new texture object and allocate GPU memory for storing an array of layers of 2D image data. More...

	Texture (TextureFormat internalFormat, std::size_t width, std::size_t height, const TextureOptions &options={})
	Create a new texture object and allocate uninitialized GPU memory for storing 2D image data. More...

	Texture (TextureFormat internalFormat, std::size_t width, std::size_t height, std::size_t depth, const TextureOptions &options={})
	Create a new texture object and allocate uninitialized GPU memory for storing an array of layers of 2D image data. More...

	Texture (const ImageView &image, const TextureOptions &options={})
	Create a new texture object and allocate GPU memory for storing 2D image data loaded from an image. More...

	operator bool () const noexcept
	Check if the texture has a value. More...

void	setOptions2D (const TextureOptions &newOptions)
	Apply a new configuration of texture/sampler options to the 2D texture. More...

void	setOptions2DArray (const TextureOptions &newOptions)
	Apply a new configuration of texture/sampler options to the 2D array texture. More...

void	pasteImage2D (std::size_t width, std::size_t height, PixelFormat pixelFormat, PixelComponentType pixelComponentType, const void *pixels, std::size_t x, std::size_t y)
	Copy 2D image data into the 2D texture at a specific position. More...

void	pasteImage2D (const ImageView &image, std::size_t x, std::size_t y)
	Copy a 2D image into the 2D texture at a specific position. More...

void	pasteImage2DArray (std::size_t width, std::size_t height, std::size_t depth, PixelFormat pixelFormat, PixelComponentType pixelComponentType, const void *pixels, std::size_t x, std::size_t y, std::size_t z)
	Copy an array of layers of 2D image data into the 2D array texture at a specific position. More...

void	pasteImage2DArray (const ImageView &image, std::size_t x, std::size_t y, std::size_t z)
	Copy a 2D image into the 2D array texture at a specific position. More...

void	fill2D (Renderer &renderer, Color color)
	Fill the entire allocated 2D texture data with pixels of the given color. More...

void	grow2D (Renderer &renderer, std::size_t newWidth, std::size_t newHeight, std::optional< Color > backgroundColor={})
	Expand the allocated 2D texture data by allocating larger texture storage and copying the old texture image onto the bottom left corner of the new texture. More...

Texture	copy2D (Renderer &renderer) const
	Create a new texture object and allocate GPU memory onto which the 2D image data of this 2D texture is copied. More...

Texture	copyGrow2D (Renderer &renderer, std::size_t newWidth, std::size_t newHeight, std::optional< Color > backgroundColor={}) const
	Create a new texture object and allocate GPU memory in an expanded version of this texture onto which the 2D texture data of this 2D texture is copied. More...

vec2	getSize2D () const noexcept
	Get the floating-point size, in texels, of the 2D image data stored in this texture. More...

TextureFormat	getInternalFormat () const noexcept
	Get the internal texel format of this texture. More...

std::size_t	getWidth () const noexcept
	Get the width, in texels, of the 2D image data stored in this texture. More...

std::size_t	getHeight () const noexcept
	Get the height, in texels, of the 2D image data stored in this texture. More...

const TextureOptions &	getOptions () const noexcept
	Get the configuration options of this texture and its associated sampler. More...

Handle	get () const noexcept
	Get an opaque handle to the GPU representation of the texture. More...

Static Public Member Functions
static std::size_t	getChannelCount (TextureFormat internalFormat) noexcept
	Get the number of texel component channels defined by an internal texel format. More...

static PixelFormat	getPixelFormat (TextureFormat internalFormat) noexcept
	Get a description of the pixel format that corresponds to the texel format of an internal texture format. More...

static PixelComponentType	getPixelComponentType (TextureFormat internalFormat) noexcept
	Get a description of the pixel component type that corresponds to the texel component type of an internal texture format. More...

static TextureFormat	getInternalFormat (PixelFormat pixelFormat, PixelComponentType pixelComponentType) noexcept
	Get the internal texture format that correspons to an image format. More...

Static Public Attributes
static const Texture *const	TRANSPARENT
	Pointer to the statically allocated storage for the built-in transparent 2D texture. More...

static const Texture *const	BLACK
	Pointer to the statically allocated storage for the built-in black 2D texture. More...

static const Texture *const	WHITE
	Pointer to the statically allocated storage for the built-in white 2D texture. More...

static const Texture *const	DEFAULT_SPECULAR
	Pointer to the statically allocated storage for the built-in default specular-map 2D texture. More...

static const Texture *const	DEFAULT_NORMAL
	Pointer to the statically allocated storage for the built-in default normal-map 2D texture. More...

Detailed Description

Storage for multidimensional data, such as 2D images, on the GPU, combined with a sampler configuration that defines how to render the stored data.

Examples: example_game.cpp.

Constructor & Destructor Documentation

◆ Texture() [1/6]

donut::graphics::Texture::Texture ( )

defaultnoexcept

Construct an empty texture without a value.

◆ Texture() [2/6]

donut::graphics::Texture::Texture	(	TextureFormat	internalFormat,
		std::size_t	width,
		std::size_t	height,
		PixelFormat	pixelFormat,
		PixelComponentType	pixelComponentType,
		const void *	pixels,
		const TextureOptions &	options = `{}`
	)

Create a new texture object and allocate GPU memory for storing 2D image data.

Parameters

internalFormat	internal texel format of the new texture.
width	width of the 2D image data to allocate, in texels.
height	height of the 2D image data to allocate, in texels.
pixelFormat	pixel format of the input image.
pixelComponentType	pixel component type of the input image.
pixels	non-owning read-only pointer to the pixel data of the input image to copy into the new texture data storage, or nullptr to leave the data uninitialized.
options	texture/sampler options, see TextureOptions.

Exceptions

graphics::Error	on failure to create the texture object.
std::bad_alloc	on allocation failure. Note: this pertains only to CPU memory allocations. Failure to allocate GPU memory for the texture data might not be reported directly.

Warning: If not nullptr, the pixel data pointed to by the pixels parameter must be of the shape and format described by the width, height, format and type parameters.

Note: For uninitialized data, consider using the Texture(TextureFormat, std::size_t, std::size_t, const TextureOptions&) overload instead of passing nullptr to the pixels parameter.

◆ Texture() [3/6]

donut::graphics::Texture::Texture	(	TextureFormat	internalFormat,
		std::size_t	width,
		std::size_t	height,
		std::size_t	depth,
		PixelFormat	pixelFormat,
		PixelComponentType	pixelComponentType,
		const void *	pixels,
		const TextureOptions &	options = `{}`
	)

Create a new texture object and allocate GPU memory for storing an array of layers of 2D image data.

Parameters

internalFormat	internal texel format of the new texture.
width	width of the 2D image data to allocate, in texels.
height	height of the 2D image data to allocate, in texels.
depth	number of 2D image layers to allocate for the array.
pixelFormat	pixel format of the input image array.
pixelComponentType	pixel component type of the input image array.
pixels	non-owning read-only pointer to the pixel data of the input image array to copy into the new texture data storage, or nullptr to leave the data uninitialized.
options	texture/sampler options, see TextureOptions.

Exceptions

graphics::Error	on failure to create the texture object.
std::bad_alloc	on allocation failure. Note: this pertains only to CPU memory allocations. Failure to allocate GPU memory for the texture data might not be reported directly.

Warning: If not nullptr, the pixel data array pointed to by the pixels parameter must be of the shape and format described by the width, height, depth, format and type parameters.

Note: For uninitialized data, consider using the Texture(TextureFormat, std::size_t, std::size_t, std::size_t, const TextureOptions&) overload instead of passing nullptr to the pixels parameter.

◆ Texture() [4/6]

donut::graphics::Texture::Texture	(	TextureFormat	internalFormat,
		std::size_t	width,
		std::size_t	height,
		const TextureOptions &	options = `{}`
	)

Create a new texture object and allocate uninitialized GPU memory for storing 2D image data.

Parameters

internalFormat	internal texel format of the new texture.
width	width of the 2D image data to allocate, in texels.
height	height of the 2D image data to allocate, in texels.
options	texture/sampler options, see TextureOptions.

Exceptions

graphics::Error	on failure to create the texture object.
std::bad_alloc	on allocation failure. Note: this pertains only to CPU memory allocations. Failure to allocate GPU memory for the texture data might not be reported directly.

◆ Texture() [5/6]

donut::graphics::Texture::Texture	(	TextureFormat	internalFormat,
		std::size_t	width,
		std::size_t	height,
		std::size_t	depth,
		const TextureOptions &	options = `{}`
	)

Create a new texture object and allocate uninitialized GPU memory for storing an array of layers of 2D image data.

Parameters

internalFormat	internal texel format of the new texture.
width	width of the 2D image data to allocate, in texels.
height	height of the 2D image data to allocate, in texels.
depth	number of 2D image layers to allocate for the array.
options	texture/sampler options, see TextureOptions.

Exceptions

graphics::Error	on failure to create the texture object.
std::bad_alloc	on allocation failure. Note: this pertains only to CPU memory allocations. Failure to allocate GPU memory for the texture data might not be reported directly.

◆ Texture() [6/6]

donut::graphics::Texture::Texture	(	const ImageView &	image,
		const TextureOptions &	options = `{}`
	)

Create a new texture object and allocate GPU memory for storing 2D image data loaded from an image.

Parameters

image	non-owning read-only view over the image to copy into the new texture data storage. The allocated storage will be sized to fit the image.
options	texture/sampler options, see TextureOptions.

Exceptions

graphics::Error	on failure to create the texture object, or on failure to choose an appropriate internal texel format for the given image.
std::bad_alloc	on allocation failure. Note: this pertains only to CPU memory allocations. Failure to allocate GPU memory for the texture data might not be reported directly.

Note: A suitable internal texel format is chosen automatically based on the pixel format of the image. To choose the internal format manually, use the Texture(TextureFormat, std::size_t, std::size_t, PixelFormat, PixelComponentType, const void*, const TextureOptions&) overload instead.

Member Function Documentation

◆ getChannelCount()

static std::size_t donut::graphics::Texture::getChannelCount ( TextureFormat internalFormat )

staticnoexcept

Get the number of texel component channels defined by an internal texel format.

Parameters

internalFormat the format to get the number of channels of.

Returns: the number of channels in the given format.

◆ getPixelFormat()

static PixelFormat donut::graphics::Texture::getPixelFormat ( TextureFormat internalFormat )

staticnoexcept

Get a description of the pixel format that corresponds to the texel format of an internal texture format.

Parameters

internalFormat the internal texel format to get the pixel format of.

Returns: the corresponding pixel format.

◆ getPixelComponentType()

static PixelComponentType donut::graphics::Texture::getPixelComponentType ( TextureFormat internalFormat )

staticnoexcept

Get a description of the pixel component type that corresponds to the texel component type of an internal texture format.

Parameters

internalFormat the internal texel format to get the component type of.

Returns: the corresponding pixel component type.

◆ getInternalFormat() [1/2]

static TextureFormat donut::graphics::Texture::getInternalFormat	(	PixelFormat	pixelFormat,
		PixelComponentType	pixelComponentType
	)

staticnoexcept

Get the internal texture format that correspons to an image format.

Parameters

pixelFormat	the pixel format of the image format.
pixelComponentType	the pixel component type of the image format.

Returns: the corresponding texture format.

◆ operator bool()

donut::graphics::Texture::operator bool ( ) const

inlineexplicitnoexcept

Check if the texture has a value.

Returns: true if the texture has a value, false otherwise.

◆ setOptions2D()

void donut::graphics::Texture::setOptions2D ( const TextureOptions & newOptions )

Apply a new configuration of texture/sampler options to the 2D texture.

Parameters

newOptions the new options to apply.

Warning: This function must only be called on textures that are set up to store 2D image data.

◆ setOptions2DArray()

void donut::graphics::Texture::setOptions2DArray ( const TextureOptions & newOptions )

Apply a new configuration of texture/sampler options to the 2D array texture.

Parameters

newOptions the new options to apply.

Warning: This function must only be called on textures that are set up to store an array of layers of 2D image data.

◆ pasteImage2D() [1/2]

void donut::graphics::Texture::pasteImage2D	(	std::size_t	width,
		std::size_t	height,
		PixelFormat	pixelFormat,
		PixelComponentType	pixelComponentType,
		const void *	pixels,
		std::size_t	x,
		std::size_t	y
	)

Copy 2D image data into the 2D texture at a specific position.

Parameters

width	width of the 2D image data to copy, in pixels.
height	height of the 2D image data to copy, in pixels.
pixelFormat	pixel format of the input image.
pixelComponentType	pixel component type of the input image.
pixels	non-owning read-only pointer to the pixel data of the input image to copy into the existing texture data storage. Must not be nullptr.
x	the horizontal offset, in texels, from the left edge of the texture at which to paste the image, where the left edge of the pasted image will begin.
y	the vertical offset, in texels, from the bottom edge of the texture at which to paste the image, where the bottom edge of the pasted image will begin.

Warning: This function must only be called on textures that are set up to store 2D image data.; The pixel data pointed to by the pixels parameter must be of the shape and format described by the width, height, pixelFormat and pixelComponentType parameters.; Enough space must be allocated in the texture for the full image to fit at the given position.

◆ pasteImage2D() [2/2]

void donut::graphics::Texture::pasteImage2D	(	const ImageView &	image,
		std::size_t	x,
		std::size_t	y
	)

Copy a 2D image into the 2D texture at a specific position.

Parameters

image	non-owning read-only view over the image to copy into the existing texture data storage.
x	the horizontal offset, in texels, from the left edge of the texture at which to paste the image, where the left edge of the pasted image will begin.
y	the vertical offset, in texels, from the bottom edge of the texture at which to paste the image, where the bottom edge of the pasted image will begin.

Warning: This function must only be called on textures that are set up to store 2D image data.; Enough space must be allocated in the texture for the full image to fit at the given position.

◆ pasteImage2DArray() [1/2]

void donut::graphics::Texture::pasteImage2DArray	(	std::size_t	width,
		std::size_t	height,
		std::size_t	depth,
		PixelFormat	pixelFormat,
		PixelComponentType	pixelComponentType,
		const void *	pixels,
		std::size_t	x,
		std::size_t	y,
		std::size_t	z
	)

Copy an array of layers of 2D image data into the 2D array texture at a specific position.

Parameters

width	width of the 2D image data to copy, in pixels.
height	height of the 2D image data to copy, in pixels.
depth	number of 2D image layers in the array to copy.
pixelFormat	pixel format of the input image.
pixelComponentType	pixel component type of the input image.
pixels	non-owning read-only pointer to the pixel data of the input image array to copy into the existing texture data storage. Must not be nullptr.
x	the horizontal offset, in texels, from the left edge of the texture at which to paste the image array, where the left edge of the pasted image array will begin.
y	the vertical offset, in texels, from the bottom edge of the texture at which to paste the image array, where the bottom edge of the pasted image array will begin.
z	the depth offset, in texels, from the first layer of the texture at which to paste the image array, where the first pasted image will begin.

Warning: This function must only be called on textures that are set up to store arrays of layers of 2D image data.; The pixel data pointed to by the pixels parameter must be of the shape and format described by the width, height, depth, pixelFormat and pixelComponentType parameters.; Enough space must be allocated in the texture for the full image array to fit at the given position.

◆ pasteImage2DArray() [2/2]

void donut::graphics::Texture::pasteImage2DArray	(	const ImageView &	image,
		std::size_t	x,
		std::size_t	y,
		std::size_t	z
	)

Copy a 2D image into the 2D array texture at a specific position.

Parameters

image	non-owning read-only view over the image to copy into the existing texture data storage.
x	the horizontal offset, in texels, from the left edge of the texture at which to paste the image, where the left edge of the pasted image will begin.
y	the vertical offset, in texels, from the bottom edge of the texture at which to paste the image, where the bottom edge of the pasted image will begin.
z	the depth offset, in texels, from the first layer of the texture at which to paste the image.

Warning: This function must only be called on textures that are set up to store arrays of layers of 2D image data.; Enough space must be allocated in the texture for the full image to fit at the given position.

◆ fill2D()

void donut::graphics::Texture::fill2D	(	Renderer &	renderer,
		Color	color
	)

Fill the entire allocated 2D texture data with pixels of the given color.

Parameters

renderer	renderer to use for filling the texture.
color	color to fill the texture with.

Warning: This function must only be called on textures that are set up to store 2D image data.; The internal texture format must be framebuffer-compatible.

◆ grow2D()

void donut::graphics::Texture::grow2D	(	Renderer &	renderer,
		std::size_t	newWidth,
		std::size_t	newHeight,
		std::optional< Color >	backgroundColor = `{}`
	)

Expand the allocated 2D texture data by allocating larger texture storage and copying the old texture image onto the bottom left corner of the new texture.

Parameters

renderer	renderer to use for copying the texture data.
newWidth	new width of the 2D image data to allocate, in texels. Must be greater than or equal to the old width.
newHeight	new height of the 2D image data to allocate, in texels. Must be greater than or equal to the old height.
backgroundColor	if set, the new texture data is cleared to this color before copying the old data onto it.

Warning: This function must only be called on textures that are set up to store 2D image data.; The internal texture format must be framebuffer-compatible.

Exceptions

std::bad_alloc on allocation failure. Note: this pertains only to CPU memory allocations. Failure to allocate GPU memory for the texture data might not be reported directly.

See also: copy2D(); copyGrow2D()

◆ copy2D()

Texture donut::graphics::Texture::copy2D ( Renderer & renderer ) const

Create a new texture object and allocate GPU memory onto which the 2D image data of this 2D texture is copied.

Parameters

renderer renderer to use for copying the texture data.

Returns: the new copied texture.

Warning: This function must only be called on textures that are set up to store 2D image data.; The internal texture format must be framebuffer-compatible.

Exceptions

std::bad_alloc on allocation failure. Note: this pertains only to CPU memory allocations. Failure to allocate GPU memory for the texture data might not be reported directly.

See also: grow2D(); copyGrow2D()

◆ copyGrow2D()

Texture donut::graphics::Texture::copyGrow2D	(	Renderer &	renderer,
		std::size_t	newWidth,
		std::size_t	newHeight,
		std::optional< Color >	backgroundColor = `{}`
	)		const

Create a new texture object and allocate GPU memory in an expanded version of this texture onto which the 2D texture data of this 2D texture is copied.

Parameters

renderer	renderer to use for copying the texture data.
newWidth	new width of the 2D image data to allocate, in texels. Must be greater than or equal to the old width.
newHeight	new height of the 2D image data to allocate, in texels. Must be greater than or equal to the old height.
backgroundColor	if set, the new texture data is cleared to this color before copying the old data onto it.

Returns: the new expanded copied texture.

Warning: This function must only be called on textures that are set up to store 2D image data.; The internal texture format must be framebuffer-compatible.

Exceptions

std::bad_alloc on allocation failure. Note: this pertains only to CPU memory allocations. Failure to allocate GPU memory for the texture data might not be reported directly.

See also: grow2D(); copy2D()

◆ getSize2D()

vec2 donut::graphics::Texture::getSize2D ( ) const

inlinenoexcept

Get the floating-point size, in texels, of the 2D image data stored in this texture.

Returns: a 2D vector representing the width and height of the texture, in texels, or (0, 0) if the texture does not have a value.

Note: For 2D array textures, this function returns the width and height of a single image layer in the array.

See also: getWidth(); getHeight()

◆ getInternalFormat() [2/2]

TextureFormat donut::graphics::Texture::getInternalFormat ( ) const

inlinenoexcept

Get the internal texel format of this texture.

Returns: the internal texel format, or TextureFormat::R8_UNORM if the texture does not have a value.

◆ getWidth()

std::size_t donut::graphics::Texture::getWidth ( ) const

inlinenoexcept

Get the width, in texels, of the 2D image data stored in this texture.

Returns: the width of the texture, in texels, or 0 if the texture does not have a value.

Note: For 2D array textures, this function returns the width of a single image layer in the array.

See also: getSize2D(); getHeight()

◆ getHeight()

std::size_t donut::graphics::Texture::getHeight ( ) const

inlinenoexcept

Get the height, in texels, of the 2D image data stored in this texture.

Returns: the height of the texture, in texels, or 0 if the texture does not have a value.

Note: For 2D array textures, this function returns the height of a single image layer in the array.

See also: getSize2D(); getWidth()

◆ getOptions()

const TextureOptions& donut::graphics::Texture::getOptions ( ) const

inlinenoexcept

Get the configuration options of this texture and its associated sampler.

Returns: a read-only reference to the internal texture options, valid until the texture is moved from or destroyed.

◆ get()

Handle donut::graphics::Texture::get ( ) const

inlinenoexcept

Get an opaque handle to the GPU representation of the texture.

Returns: a non-owning resource handle to the GPU representation of the texture.

Note: This function is used internally by the implementations of various abstractions and is not intended to be used outside of the graphics module. The returned handle has no meaning to application code.

Member Data Documentation

◆ TRANSPARENT

const Texture* const donut::graphics::Texture::TRANSPARENT

static

Pointer to the statically allocated storage for the built-in transparent 2D texture.

Warning: This pointer must not be dereferenced in application code. It is not guaranteed that the underlying texture will be present at all times.

◆ BLACK

const Texture* const donut::graphics::Texture::BLACK

static

Pointer to the statically allocated storage for the built-in black 2D texture.

Warning: This pointer must not be dereferenced in application code. It is not guaranteed that the underlying texture will be present at all times.

◆ WHITE

const Texture* const donut::graphics::Texture::WHITE

static

Pointer to the statically allocated storage for the built-in white 2D texture.

Warning: This pointer must not be dereferenced in application code. It is not guaranteed that the underlying texture will be present at all times.

◆ DEFAULT_SPECULAR

const Texture* const donut::graphics::Texture::DEFAULT_SPECULAR

static

Pointer to the statically allocated storage for the built-in default specular-map 2D texture.

Warning: This pointer must not be dereferenced in application code. It is not guaranteed that the underlying texture will be present at all times.

◆ DEFAULT_NORMAL

const Texture* const donut::graphics::Texture::DEFAULT_NORMAL

static

Pointer to the statically allocated storage for the built-in default normal-map 2D texture.

Warning: This pointer must not be dereferenced in application code. It is not guaranteed that the underlying texture will be present at all times.

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

include/donut/graphics/Texture.hpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Texture() [1/6]

◆ Texture() [2/6]

◆ Texture() [3/6]

◆ Texture() [4/6]

◆ Texture() [5/6]

◆ Texture() [6/6]

Member Function Documentation

◆ getChannelCount()

◆ getPixelFormat()

◆ getPixelComponentType()

◆ getInternalFormat() [1/2]

◆ operator bool()

◆ setOptions2D()

◆ setOptions2DArray()

◆ pasteImage2D() [1/2]

◆ pasteImage2D() [2/2]

◆ pasteImage2DArray() [1/2]

◆ pasteImage2DArray() [2/2]

◆ fill2D()

◆ grow2D()

◆ copy2D()

◆ copyGrow2D()

◆ getSize2D()

◆ getInternalFormat() [2/2]

◆ getWidth()

◆ getHeight()

◆ getOptions()

◆ get()

Member Data Documentation

◆ TRANSPARENT

◆ BLACK

◆ WHITE

◆ DEFAULT_SPECULAR

◆ DEFAULT_NORMAL