#include <CUTextureArray.h>

Public Member Functions
	TextureArray ()

	~TextureArray ()

void	dispose ()

bool	init (Uint32 width, Uint32 height, Uint32 layers, TexelFormat format=TexelFormat::COLOR_RGBA, ImageAccess access=ImageAccess::READ_WRITE)

bool	initWithData (const std::byte *data, Uint32 width, Uint32 height, Uint32 layers, TexelFormat format=TexelFormat::COLOR_RGBA, ImageAccess access=ImageAccess::READ_WRITE, bool mipmaps=false)

bool	initWithImages (const std::shared_ptr< ImageArray > &images)

bool	initWithImages (const std::shared_ptr< ImageArray > &images, const std::shared_ptr< Sampler > &sampler)

const std::shared_ptr< ImageArray >	getImages () const

const std::shared_ptr< Sampler >	getSampler () const

const TextureArray &	operator= (const std::byte *data)

const TextureArray &	set (const std::byte *data)

const TextureArray &	set (const std::vector< std::byte > &data)

bool	setLayer (Uint32 layer, const std::byte *data)

bool	setLayer (Uint32 layer, const std::vector< std::byte > &data)

const size_t	get (std::vector< std::byte > &data)

const size_t	getLayer (Uint32 layer, std::vector< std::byte > &data)

void	setName (std::string name)

const std::string	getName () const

size_t	id () const

Uint32	getWidth () const

Uint32	getHeight () const

Uint32	getLayers () const

Size	getSize ()

std::string	toString (bool verbose=false) const

	operator std::string () const

Static Public Member Functions
static std::shared_ptr< TextureArray >	alloc (Uint32 width, Uint32 height, Uint32 layers, TexelFormat format=TexelFormat::COLOR_RGBA, ImageAccess access=ImageAccess::READ_WRITE)

static std::shared_ptr< TextureArray >	allocWithData (const std::byte *data, Uint32 width, Uint32 height, Uint32 layers, TexelFormat format=TexelFormat::COLOR_RGBA, ImageAccess access=ImageAccess::READ_WRITE, bool mipmaps=false)

static std::shared_ptr< TextureArray >	allocWithImages (const std::shared_ptr< ImageArray > &images)

static std::shared_ptr< TextureArray >	allocWithImages (const std::shared_ptr< ImageArray > &images, const std::shared_ptr< Sampler > &sampler)

Detailed Description

This is a class representing a texture array.

A class is mostly a pair of an ImageArray and a Sampler. Most of its functionality can be accessed through those two attributes. Unlike the class Texture, we do not currently have texture atlas support for texture arrays.

Texture arrays are intended to be used with GraphicsShader objects. As they can support either Vulkan or OpenGL, we do not support the binding API of OpenGL. This functionality has been abstracted away.

Note that texture arrays can only be constructed on the main thread when using OpenGL. However, in Vulkan, images can be safely constructed on any thread.

Constructor & Destructor Documentation

◆ TextureArray()

cugl::graphics::TextureArray::TextureArray ( )

Creates a new empty texture array with no size.

This method performs no allocations. You must call init to generate a proper texture.

◆ ~TextureArray()

cugl::graphics::TextureArray::~TextureArray ( )

inline

Deletes this texture array, disposing all resources

Member Function Documentation

◆ alloc()

static std::shared_ptr< TextureArray > cugl::graphics::TextureArray::alloc	(	Uint32	width,
		Uint32	height,
		Uint32	layers,
		TexelFormat	format = `TexelFormat::COLOR_RGBA`,
		ImageAccess	access = `ImageAccess::READ_WRITE`
	)

inlinestatic

Returns a new empty texture with the given dimensions.

The image array will have all of its texels set to 0. It will not support mipmaps. You should use allocWithData for mipmap support.

The sampler will be the default, using a TextureFilter#LINEAR filter and TextureWrap#CLAMP on both axes.

Parameters

width	The texture width in pixels
height	The texture height in pixels
layers	The number of layers in the array
format	The texture data format
access	The image access

Returns: a new empty texture with the given dimensions.

◆ allocWithData()

static std::shared_ptr< TextureArray > cugl::graphics::TextureArray::allocWithData	(	const std::byte *	data,
		Uint32	width,
		Uint32	height,
		Uint32	layers,
		TexelFormat	format = `TexelFormat::COLOR_RGBA`,
		ImageAccess	access = `ImageAccess::READ_WRITE`,
		bool	mipmaps = `false`
	)

inlinestatic

Returns a new texture array with the given data.

The data format must match the one specified by the format parameter. If the parameter mipmaps is true, the image will generate an appropriate number of mipmaps determined by its size.

The sampler will be the default, using a TextureFilter#LINEAR filter and TextureWrap#CLAMP on both axes.

Parameters

data	The texture data (size widthheightformat)
width	The texture width in pixels
height	The texture height in pixels
layers	The number of layers in the array
format	The texture data format
access	The image access
mipmaps	Flag to generate mipmaps

Returns: a new texture array with the given data.

◆ allocWithImages() [1/2]

static std::shared_ptr< TextureArray > cugl::graphics::TextureArray::allocWithImages ( const std::shared_ptr< ImageArray > & images )

inlinestatic

Returns a new texture array with the given image array.

Note that this texture does not copy the image array, so any changes to the image array elsewhere will affect this is texture array.

The sampler will be the default, using a TextureFilter#LINEAR filter and TextureWrap#CLAMP on both axes.

Parameters

images The texture image array

Returns: a new texture array with the given image array.

◆ allocWithImages() [2/2]

static std::shared_ptr< TextureArray > cugl::graphics::TextureArray::allocWithImages	(	const std::shared_ptr< ImageArray > &	images,
		const std::shared_ptr< Sampler > &	sampler
	)

inlinestatic

Returns a new texture array with the given image array and sampler.

Note that this texture does not copy the image array, so any changes to the image array elsewhere will affect this is texture array.

Parameters

images	The texture image array
sampler	The texture sampler

Returns: a new texture array with the given image array and sampler.

◆ dispose()

void cugl::graphics::TextureArray::dispose ( )

Deletes the texture array and resets all attributes.

You must reinitialize the texture array to use it.

◆ get()

const size_t cugl::graphics::TextureArray::get ( std::vector< std::byte > & data )

Fills the given buffer with data from this texture array.

This method will append the data to the given vector.

Parameters

data	The buffer to store the texture data

Returns: the number of bytes read into the buffer

◆ getHeight()

Uint32 cugl::graphics::TextureArray::getHeight ( ) const

inline

Returns the height of this texture array in texels.

Returns: the height of this texture array in texels.

◆ getImages()

const std::shared_ptr< ImageArray > cugl::graphics::TextureArray::getImages ( ) const

inline

Returns the image array component of this texture array

In modern graphics APIs, texture arrays are composed of two objects: an image array and a sampler. Modifications to this image will be reflected in the texture during sampling.

Returns: the image array component of this texture

◆ getLayer()

const size_t cugl::graphics::TextureArray::getLayer	(	Uint32	layer,
		std::vector< std::byte > &	data
	)

Fills the given buffer with data from the specified layer

This method will append the data to the given vector.

Parameters

layer	The texture layer to modify
data	The buffer to store the texture data

Returns: the number of bytes read into the buffer

◆ getLayers()

Uint32 cugl::graphics::TextureArray::getLayers ( ) const

inline

Returns the number of layers in this texture array.

Returns: the number of layers in this texture array.

◆ getName()

const std::string cugl::graphics::TextureArray::getName ( ) const

inline

Returns the name of this texture array.

A name is a user-defined way of identifying a texture. Subtextures are permitted to have different names than their parents.

Returns: the name of this texture array.

◆ getSampler()

const std::shared_ptr< Sampler > cugl::graphics::TextureArray::getSampler ( ) const

inline

Returns the sampler component of this texture

In modern graphics APIs, texture arrays are composed of two objects: an image array and a sampler. Modifications to this sampler will be reflected in the texture during sampling.

Returns: the sampler component of this texture

◆ getSize()

Size cugl::graphics::TextureArray::getSize ( )

inline

Returns the size of this texture array in texels.

Returns: the size of this texture array in pixels.

◆ getWidth()

Uint32 cugl::graphics::TextureArray::getWidth ( ) const

inline

Returns the width of this texture array in texels.

Returns: the width of this texture array in texels.

◆ id()

size_t cugl::graphics::TextureArray::id ( ) const

Returns a unique identifier for this texture array

This value can be used in memory-based hashes.

Returns: a unique identifier for this texture array

◆ init()

bool cugl::graphics::TextureArray::init	(	Uint32	width,
		Uint32	height,
		Uint32	layers,
		TexelFormat	format = `TexelFormat::COLOR_RGBA`,
		ImageAccess	access = `ImageAccess::READ_WRITE`
	)

inline

Initializes an empty texture array with the given dimensions.

The image array will have all of its texels set to 0. It will not support mipmaps. You should use initWithData for mipmap support.

The sampler will be the default, using a TextureFilter#LINEAR filter and TextureWrap#CLAMP on both axes.

Parameters

width	The image width in texels
height	The image height in texels
layers	The number of layers in the array
format	The image data format
access	The image access

Returns: true if initialization was successful.

◆ initWithData()

bool cugl::graphics::TextureArray::initWithData	(	const std::byte *	data,
		Uint32	width,
		Uint32	height,
		Uint32	layers,
		TexelFormat	format = `TexelFormat::COLOR_RGBA`,
		ImageAccess	access = `ImageAccess::READ_WRITE`,
		bool	mipmaps = `false`
	)

Initializes a texture array with the given data.

The data format must match the one specified by the format parameter. If the parameter mipmaps is true, the image will generate an appropriate number of mipmaps determined by its size.

The sampler will be the default, using a TextureFilter#LINEAR filter and TextureWrap#CLAMP on both axes.

Parameters

data	The texture data (size widthheightformat)
width	The texture width in pixels
height	The texture height in pixels
layers	The number of layers in the array
format	The texture data format
access	The image access
mipmaps	Flag to generate mipmaps

Returns: true if initialization was successful.

◆ initWithImages() [1/2]

bool cugl::graphics::TextureArray::initWithImages ( const std::shared_ptr< ImageArray > & images )

Initializes an texture array with the given image array.

Note that this texture does not copy the image array, so any changes to the image array elsewhere will affect this is texture array.

The sampler will be the default, using a TextureFilter#LINEAR filter and TextureWrap#CLAMP on both axes.

Parameters

images The texture image array

Returns: true if initialization was successful.

◆ initWithImages() [2/2]

bool cugl::graphics::TextureArray::initWithImages	(	const std::shared_ptr< ImageArray > &	images,
		const std::shared_ptr< Sampler > &	sampler
	)

Initializes an texture with the given image array and sampler.

Note that this texture does not copy the image, so any changes to the image elsewhere will affect this is texture.

Parameters

images	The texture image array
sampler	The texture sampler

Returns: true if initialization was successful.

◆ operator std::string()

cugl::graphics::TextureArray::operator std::string ( ) const

inline

Casts from Texture to a string.

◆ operator=()

const TextureArray & cugl::graphics::TextureArray::operator= ( const std::byte * data )

inline

Sets this texture array to have the contents of the given buffer.

This method is the same as in ImageArray.

The buffer must have the correct data format. In addition, the buffer must be size width*height*layers*bytesize. See ImageArray#getByteSize for a description of the latter.

Parameters

data	The buffer to read into the texture array

Returns: a reference to this (modified) texture array for chaining.

◆ set() [1/2]

const TextureArray & cugl::graphics::TextureArray::set ( const std::byte * data )

Sets this texture array to have the contents of the given buffer.

This method is the same as in ImageArray.

The buffer must have the correct data format. In addition, the buffer must be size width*height*layers*bytesize. See ImageArray#getByteSize for a description of the latter.

Parameters

data	The buffer to read into the texture array

Returns: a reference to this (modified) texture array for chaining.

◆ set() [2/2]

const TextureArray & cugl::graphics::TextureArray::set ( const std::vector< std::byte > & data )

inline

Sets this texture array to have the contents of the given buffer.

This method is the same as in ImageArray.

The buffer must have the correct data format. In addition, the buffer must be size width*height*layers*bytesize. See ImageArray#getByteSize for a description of the latter.

Parameters

data	The buffer to read into the texture array

Returns: a reference to this (modified) texture array for chaining.

◆ setLayer() [1/2]

bool cugl::graphics::TextureArray::setLayer	(	Uint32	layer,
		const std::byte *	data
	)

Sets the specified layer to have the contents of the given buffer.

This method is the same as in ImageArray. If layer is not a valid layer, this method does nothing.

The buffer must have the correct data format. In addition, the buffer must be size width*height*bytesize. See ImageArray#getByteSize for a description of the latter.

Parameters

layer	The texture layer to modify
data	The buffer to read into the texture array

Returns: true if the data was successfully set

◆ setLayer() [2/2]

bool cugl::graphics::TextureArray::setLayer	(	Uint32	layer,
		const std::vector< std::byte > &	data
	)

inline

Sets the specified layer to have the contents of the given buffer.

This method is the same as in ImageArray. If layer is not a valid layer, this method does nothing.

The buffer must have the correct data format. In addition, the buffer must be size width*height*layers*bytesize. See ImageArray#getByteSize for a description of the latter.

Parameters

layer	The texture layer to modify
data	The buffer to read into the texture array

Returns: true if the data was successfully set

◆ setName()

void cugl::graphics::TextureArray::setName ( std::string name )

inline

Sets the name of this texture array.

A name is a user-defined way of identifying a texture. Subtextures are permitted to have different names than their parents.

Parameters

name	The name of this texture array.

◆ toString()

std::string cugl::graphics::TextureArray::toString ( bool verbose = false ) const

Returns a string representation of this texture array for debugging.

If verbose is true, the string will include class information. This allows us to unambiguously identify the class.

Parameters

verbose Whether to include class information

Returns: a string representation of this texture array for debugging.

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

/Users/wmwhite/Developer/CUGL/include/cugl/graphics/CUTextureArray.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TextureArray()

◆ ~TextureArray()

Member Function Documentation

◆ alloc()

◆ allocWithData()

◆ allocWithImages() [1/2]

◆ allocWithImages() [2/2]

◆ dispose()

◆ get()

◆ getHeight()

◆ getImages()

◆ getLayer()

◆ getLayers()

◆ getName()

◆ getSampler()

◆ getSize()

◆ getWidth()

◆ id()

◆ init()

◆ initWithData()

◆ initWithImages() [1/2]

◆ initWithImages() [2/2]

◆ operator std::string()

◆ operator=()

◆ set() [1/2]

◆ set() [2/2]

◆ setLayer() [1/2]

◆ setLayer() [2/2]

◆ setName()

◆ toString()