#include <CUImageArray.h>

Public Member Functions
	ImageArray ()

	~ImageArray ()

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)

ImageArrayData *	getImplementation ()

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

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

const ImageArray &	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

ImageAccess	getAccess () const

Uint32	getWidth () const

Uint32	getHeight () const

Uint32	getLayers () const

Size	getSize () const

size_t	getByteSize () const

TexelFormat	getFormat () const

bool	hasMipMaps () const

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

	operator std::string () const

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

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

Protected Attributes
std::string	_name

Uint32	_width

Uint32	_height

Uint32	_layers

ImageArrayData *	_data

ImageAccess	_access

TexelFormat	_format

bool	_mipmaps

Detailed Description

This is a class representing an image.

This class represents an array of 2d images, each of which is a rectangular collection of texels. The color format for these texels is determined by the value TexelFormat. This value is a slightly optimized version of Image that allows for multiple images in a single object. While less valuable in Vulkan, it is a desirable optimization for OpenGL.

Historically, many game engines treat images and textures as the same thing. However, this is not the case in Vulkan and modern graphics APIs, where a texture is actually an image plus a sampler. To maximize compatibility with Vulkan, we have split textures into this class and the class Sampler.

Each entry in an image array stores the pixel information for a texture, but does not specify how to resize it or how to handle texture coordinates that are out-of-bounds. Note that in Vulkan, a texture must explicitly specify the number of mipmap levels, while this value is implicit in OpenGL. Our interface assumes that all OpenGL images with mipmap level > 0 are the same.

Note that image 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

◆ ImageArray()

cugl::graphics::ImageArray::ImageArray ( )

Creates a new empty image array with no size.

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

◆ ~ImageArray()

cugl::graphics::ImageArray::~ImageArray ( )

inline

Deletes this image array, disposing all resources

Member Function Documentation

◆ alloc()

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

inlinestatic

Returns a new empty image array with the given dimensions.

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

Parameters

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

Returns: a new empty image array with the given dimensions.

◆ allocWithData()

static std::shared_ptr< ImageArray > cugl::graphics::ImageArray::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 image 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.

Parameters

data	The image data (size widthheightformat)
width	The image width in pixels
height	The image height in pixels
layers	The number of image layers
format	The image data format
access	The image access
mipmaps	A flag to generate mipmaps

Returns: a new image array with the given data.

◆ dispose()

void cugl::graphics::ImageArray::dispose ( )

Deletes the image array and resets all attributes.

You must reinitialize the image to use it.

◆ get()

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

Fills the given buffer with data from this texture.

This method will append the data to the given vector. This method will fail if the access does not support CPU-side reads.

Parameters

data	The buffer to store the texture data

Returns: the number of bytes read into the buffer

◆ getAccess()

ImageAccess cugl::graphics::ImageArray::getAccess ( ) const

inline

Returns the access policy of this image array

Returns: the access policy of this image array

◆ getByteSize()

size_t cugl::graphics::ImageArray::getByteSize ( ) const

Returns the number of bytes in a single texel of this image array.

Returns: the number of bytes in a single texel of this image array.

◆ getFormat()

TexelFormat cugl::graphics::ImageArray::getFormat ( ) const

inline

Returns the data format of this image array.

The data format determines what type of data can be assigned to this image.

Returns: the data format of this image array.

◆ getHeight()

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

inline

Returns the height of this image in texels.

Returns: the height of this image in texels.

◆ getImplementation()

ImageArrayData * cugl::graphics::ImageArray::getImplementation ( )

inline

Returns the platform-specific implementation for this image array

The value returned is an opaque type encapsulating the information for either OpenGL or Vulkan.

Returns: the platform-specific implementation for this image

◆ getLayer()

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

Fills the given buffer with a single layer in this texture.

This method will append the data to the given vector. This method will fail if the access does not support CPU-side reads.

Parameters

layer	The layer to read from
data	The buffer to store the texture data

Returns: the number of bytes read into the buffer

◆ getLayers()

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

inline

Returns the number of layers in this image array.

Returns: the number of layers in this image array.

◆ getName()

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

inline

Returns the name of this image array.

A name is a user-defined way of identifying a image array.

Returns: the name of this image array.

◆ getSize()

Size cugl::graphics::ImageArray::getSize ( ) const

inline

Returns the size of this image in texels.

Returns: the size of this image in texels.

◆ getWidth()

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

inline

Returns the width of this image in texels.

Returns: the width of this image in texels.

◆ hasMipMaps()

bool cugl::graphics::ImageArray::hasMipMaps ( ) const

inline

Returns whether this image array has generated mipmaps.

This method will not indicate the number of mipmap levels in Vulkan. Instead, it treats mipmaps as all-or-nothing (like OpenGL).

Returns: whether this image array has generated mipmaps.

◆ id()

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

Returns a unique identifier for this image array

This value can be used in memory-based hashes.

Returns: a unique identifier for this image array

◆ init()

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

inline

Initializes an empty image array with the given dimensions.

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

Parameters

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

Returns: true if initialization was successful.

◆ initWithData()

bool cugl::graphics::ImageArray::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 an image array with the given data and access.

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.

Parameters

data	The image data (size widthheightformat)
width	The image width in pixels
height	The image height in pixels
layers	The number of image layers
format	The image data format
access	The image access
mipmaps	A flag to generate mipmaps

Returns: true if initialization was successful.

◆ operator std::string()

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

inline

Casts from ImageArray to a string.

◆ operator=()

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

inline

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

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

Note that some images created by CUGL are read-only. For any such images, this method will fail.

Parameters

data	The buffer to read into the image

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

◆ set() [1/2]

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

Sets this image to have the contents of the given buffer.

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

This method will fail if the access does not support CPU-side writes.

Parameters

data	The buffer to read into the image

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

◆ set() [2/2]

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

inline

Sets this image to have the contents of the given buffer.

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

This method will fail if the access does not support CPU-side writes.

Parameters

data	The buffer to read into the image

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

◆ setLayer() [1/2]

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

Sets a single layer of this image to have the contents of the given buffer.

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

This method will fail if the access does not support CPU-side writes.

Parameters

layer	The layer to read from
data	The buffer to read into the image

Returns: true if the data was successfully set

◆ setLayer() [2/2]

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

inline

Sets a single layer of this image to have the contents of the given buffer.

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

This method will fail if the access does not support CPU-side writes.

Parameters

layer	The layer to read from
data	The buffer to read into the image

Returns: true if the data was successfully set

◆ setName()

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

inline

Sets the name of this image array.

A name is a user-defined way of identifying a image array.

Parameters

name	The name of this image array.

◆ toString()

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

Returns a string representation of this image array for debugging purposes.

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 image array for debugging purposes.

Member Data Documentation

◆ _access

ImageAccess cugl::graphics::ImageArray::_access

protected

The access for this image array

◆ _data

ImageArrayData* cugl::graphics::ImageArray::_data

protected

The graphics API image array data

◆ _format

TexelFormat cugl::graphics::ImageArray::_format

protected

The pixel format of the image array

◆ _height

Uint32 cugl::graphics::ImageArray::_height

protected

The height in texels

◆ _layers

Uint32 cugl::graphics::ImageArray::_layers

protected

The number of images in the array

◆ _mipmaps

bool cugl::graphics::ImageArray::_mipmaps

protected

Whether this image array has associated mipmaps

◆ _name

std::string cugl::graphics::ImageArray::_name

protected

The decriptive name of this image array

◆ _width

Uint32 cugl::graphics::ImageArray::_width

protected

The width in texels

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

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

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ImageArray()

◆ ~ImageArray()

Member Function Documentation

◆ alloc()

◆ allocWithData()

◆ dispose()

◆ get()

◆ getAccess()

◆ getByteSize()

◆ getFormat()

◆ getHeight()

◆ getImplementation()

◆ getLayer()

◆ getLayers()

◆ getName()

◆ getSize()

◆ getWidth()

◆ hasMipMaps()

◆ id()

◆ init()

◆ initWithData()

◆ operator std::string()

◆ operator=()

◆ set() [1/2]

◆ set() [2/2]

◆ setLayer() [1/2]

◆ setLayer() [2/2]

◆ setName()

◆ toString()

Member Data Documentation

◆ _access

◆ _data

◆ _format

◆ _height

◆ _layers

◆ _mipmaps

◆ _name

◆ _width