#include <CUTexture.h>

Inheritance diagram for cugl::graphics::Texture:

Public Member Functions
	Texture ()

	~Texture ()

void	dispose ()

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

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

bool	initWithFile (const std::string filename, ImageAccess access=ImageAccess::READ_WRITE, bool mipmaps=false)

bool	initWithImage (const std::shared_ptr< Image > &image)

bool	initWithImage (const std::shared_ptr< Image > &image, const std::shared_ptr< Sampler > &sampler)

const std::shared_ptr< Image >	getImage () const

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

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

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

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

const size_t	get (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

Size	getSize () const

bool	isPremultiplied () const

void	setPremultiplied (bool value)

TextureFilter	getMagFilter () const

void	setMagFilter (TextureFilter filter)

TextureFilter	getMinFilter () const

void	setMinFilter (TextureFilter filter)

TextureWrap	getWrapS () const

void	setWrapS (TextureWrap wrap)

TextureWrap	getWrapT () const

void	setWrapT (TextureWrap wrap)

std::shared_ptr< Texture >	getSubTexture (Uint32 x, Uint32 y, Uint32 w, Uint32 h)

bool	isSubTexture () const

Sint32	getX () const

Sint32	getT () const

Vec2	getOrigin () const

float	getMinS () const

float	getMinT () const

float	getMaxS () const

float	getMaxT () const

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

	operator std::string () const

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

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

static std::shared_ptr< Texture >	allocWithFile (const std::string filename, ImageAccess access=ImageAccess::READ_WRITE, bool mipmaps=false)

static std::shared_ptr< Texture >	allocWithImage (const std::shared_ptr< Image > &image)

static std::shared_ptr< Texture >	allocWithImage (const std::shared_ptr< Image > &image, const std::shared_ptr< Sampler > &sampler)

static const std::shared_ptr< Texture > &	getBlank ()

Detailed Description

This is a class representing a texture.

A class is mostly a pair of an Image and a Sampler. Most of its functionality can be accessed through those two attributes.

However, this class also provides support for texture atlases. Any non-repeating texture can produce a subtexture. A subtexture creates a subimage from the underlying image using Image#getSubImage, but it has its own sampler. See getSubTexture for more information.

Textures 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 we talk about texture coordinates in terms of S (horizontal) and T (vertical). This is different from other implementations that use UV instead.

Textures 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

◆ Texture()

cugl::graphics::Texture::Texture ( )

Creates a new empty texture with no size.

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

◆ ~Texture()

cugl::graphics::Texture::~Texture ( )

inline

Deletes this texture, disposing all resources

Member Function Documentation

◆ alloc()

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

inlinestatic

Returns a new empty texture with the given dimensions.

The image will have all of its texels set to 0. You should access the image with getImage and use Image#set method to load data into the image.

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
format	The texture data format
access	The image access

Returns: a new empty texture with the given dimensions.

◆ allocWithData()

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

inlinestatic

Returns a new texture 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.

This initializer assumes that alpha is not premultiplied. You should call setPremultiplied if this is not the case.

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
format	The texture data format
access	The image access
mipmaps	Flag to generate mipmaps

Returns: a new texture with the given data.

◆ allocWithFile()

static std::shared_ptr< Texture > cugl::graphics::Texture::allocWithFile	(	const std::string	filename,
		ImageAccess	access = `ImageAccess::READ_WRITE`,
		bool	mipmaps = `false`
	)

inlinestatic

Returns a new texture with the data from the given file.

This method can load any file format supported by SDL_Image. This includes (but is not limited to) PNG, JPEG, GIF, TIFF, BMP and PCX. The image will be stored in RGBA format, even if it is a file format that does not support transparency (e.g. JPEG). Because of how SDL3 processes image files, any image loaded this way will have premultiplied alpha.

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.

If the file path is relative, it is assumed to be with respect to Application#getAssetDirectory. If you wish to load a texture from somewhere else, you must use an absolute path.

Parameters

filename	The file supporting the texture file.
access	The image access
mipmaps	Flag to generate mipmaps

Returns: a new texture with the given data

◆ allocWithImage() [1/2]

static std::shared_ptr< Texture > cugl::graphics::Texture::allocWithImage ( const std::shared_ptr< Image > & image )

inlinestatic

Returns a new texture with the given image.

This texture will cover the entire image, and not just a subregion. Note that this texture does not copy the image, so any changes to the image elsewhere will affect this is texture.

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

Parameters

image The texture image

Returns: a new texture with the given image.

◆ allocWithImage() [2/2]

static std::shared_ptr< Texture > cugl::graphics::Texture::allocWithImage	(	const std::shared_ptr< Image > &	image,
		const std::shared_ptr< Sampler > &	sampler
	)

inlinestatic

Returns a new texture with the given image and sampler.

This texture will cover the entire image, and not just a subregion. Note that this texture does not copy the image, so any changes to the image elsewhere will affect this is texture.

Parameters

image	The texture image
sampler	The texture sampler

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

◆ dispose()

void cugl::graphics::Texture::dispose ( )

Deletes the texture and resets all attributes.

You must reinitialize the texture to use it.

◆ get()

const size_t cugl::graphics::Texture::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. In the case of subtextures, this will only extract the texels in the texture region.

Parameters

data	The buffer to store the texture data

Returns: the number of bytes read into the buffer

◆ getBlank()

static const std::shared_ptr< Texture > & cugl::graphics::Texture::getBlank ( )

static

Returns a blank texture that can be used to make solid shapes.

This is the texture used by SpriteBatch when the active texture is nullptr. It is a 2x2 texture of all white pixels. Using this texture means that all shapes and outlines will be drawn with a solid color.

This texture is a singleton. There is only one of it. All calls to this method will return a reference to the same object.

Returns: a blank texture that can be used to make solid shapes.

◆ getHeight()

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

inline

Returns the height of this texture in texels.

If this is a subtexture, this will return the height of the subregion.

Returns: the height of this texture in texels.

◆ getImage()

const std::shared_ptr< Image > cugl::graphics::Texture::getImage ( ) const

inline

Returns the image component of this texture

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

If this is a subtexture (e.g. part of a texture atlas), this method will return the image for the root texture, and is not limited to the image for this subregion.

Returns: the image component of this texture

◆ getMagFilter()

TextureFilter cugl::graphics::Texture::getMagFilter ( ) const

inline

Returns the magnification filter of the associated sampler.

This is a convenience method that queries the result from the sampler. The magnification filter is the algorithm hint that the graphics card uses to make an image larger. The default is LINEAR.

Returns: the magnification filter of the associated sampler.

◆ getMaxS()

float cugl::graphics::Texture::getMaxS ( ) const

inline

Returns the maximum horizontal texture coordinate for this texture.

When rescaling texture coordinates for a subtexture, this value is used in place of 1.

Returns: the maximum horizontal texture coordinate for this texture.

◆ getMaxT()

float cugl::graphics::Texture::getMaxT ( ) const

inline

Returns the maximum vertical texture coordinate for this texture.

When rescaling texture coordinates for a subtexture, this value is used in place of 1.

Returns: the maximum vertical texture coordinate for this texture.

◆ getMinFilter()

TextureFilter cugl::graphics::Texture::getMinFilter ( ) const

inline

Returns the minimization filter of the associated sampler.

This is a convenience method that queries the result from the sampler. The minimization filter is the algorithm hint that the graphics card uses to make an image smaller. The default is LINEAR.

Returns: the minimization filter of the associated sampler.

◆ getMinS()

float cugl::graphics::Texture::getMinS ( ) const

inline

Returns the minimum horizontal texture coordinate for this texture.

When rescaling texture coordinates for a subtexture, this value is used in place of 0.

Returns: the minimum horizontal texture coordinate for this texture.

◆ getMinT()

float cugl::graphics::Texture::getMinT ( ) const

inline

Returns the minimum vertical texture coordinate for this texture.

When rescaling texture coordinates for a subtexture, this value is used in place of 0.

Returns: the minimum vertical texture coordinate for this texture.

◆ getName()

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

inline

Returns the name of this texture.

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.

◆ getOrigin()

Vec2 cugl::graphics::Texture::getOrigin ( ) const

inline

Returns the origin texel.

If this is not a subtexture, this method returns the origin (0,0). Otherwise, this method returns the bottom left corner of the subtexture region.

Returns: the y-coordinate of the origin texel.

◆ getSampler()

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

inline

Returns the sampler component of this texture

In modern graphics APIs, textures are composed of two objects: an image 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::Texture::getSize ( ) const

Returns the size of this texture in texels.

If this is a subtexture, this will return the height of the subregion.

Returns: the size of this texture in pixels.

◆ getSubTexture()

std::shared_ptr< Texture > cugl::graphics::Texture::getSubTexture	(	Uint32	x,
		Uint32	y,
		Uint32	w,
		Uint32	h
	)

Returns a subtexture with the given dimensions.

The values x,y,w, and h must specify a subrectangle inside of the texure image. All values are in texels. In defining this rectangle, we put the origin in the bottom left corner with positive y values go up in the texture image.

Subtextures are constructed using Image#getSubImage to construct a subimage of the texture image. So any changes to the parent image will affect the subtexture. On the other hand, subtextures always have their own sampler distinct from that of the original texture. So changes to the sampler of the parent texture will not affect the subtexture.

It is the responsibility of the user to rescale the texture coordinates of a mesh when using a subtexture. Otherwise, the graphics pipeline will just use the original texture instead. See the method internal method SpriteBatch#prepare for an example of how to scale texture coordinates.

It is possible to make a subtexture of a subtexture. However, in that case, the parent of the new subtexture will be the original root texture. So no tree of subtextures is more than one level deep.

Parameters

x	The x-coordinate of the bottom left in texels
y	The y-coordinate of the bottom left in texels
w	The region width in texels
h	The region height in texels

Returns: a subtexture with the given dimensions.

◆ getT()

Sint32 cugl::graphics::Texture::getT ( ) const

inline

Returns the y-coordinate of the origin texel.

If this is not a subtexture, this method returns 0. Otherwise, this method is given by the origin of the subtexture region.

Returns: the y-coordinate of the origin texel.

◆ getWidth()

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

inline

Returns the width of this texture in texels.

If this is a subtexture, this will return the width of the subregion.

Returns: the width of this texture in texels.

◆ getWrapS()

TextureWrap cugl::graphics::Texture::getWrapS ( ) const

inline

Returns the horizontal wrap of the associated sampler.

This is a convenience method that queries the result from the sampler. The default is CLAMP.

Returns: the horizontal wrap of the associated sampler.

◆ getWrapT()

TextureWrap cugl::graphics::Texture::getWrapT ( ) const

inline

Returns the vertical wrap of the associated sampler.

This is a convenience method that queries the result from the sampler. The default is CLAMP.

Returns: the vertical wrap of the associated sampler.

◆ getX()

Sint32 cugl::graphics::Texture::getX ( ) const

inline

Returns the x-coordinate of the origin texel.

If this is not a subtexture, this method returns 0. Otherwise, this method is given by the origin of the subtexture region.

Returns: the x-coordinate of the origin texel.

◆ id()

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

Returns a unique identifier for this texture

This value can be used in memory-based hashes.

Returns: a unique identifier for this texture

◆ init()

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

inline

Initializes an empty texture 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.

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
format	The image data format
access	The image access

Returns: true if initialization was successful.

◆ initWithData()

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

Initializes an texture 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.

This initializer assumes that alpha is not premultiplied. You should call setPremultiplied if this is not the case.

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
format	The texture data format
access	The image access
mipmaps	Flag to generate mipmaps

Returns: true if initialization was successful.

◆ initWithFile()

bool cugl::graphics::Texture::initWithFile	(	const std::string	filename,
		ImageAccess	access = `ImageAccess::READ_WRITE`,
		bool	mipmaps = `false`
	)

Initializes an texture with the data from the given file.

This method can load any file format supported by SDL_Image. This includes (but is not limited to) PNG, JPEG, GIF, TIFF, BMP and PCX. The image will be stored in RGBA format, even if it is a file format that does not support transparency (e.g. JPEG). Because of how SDL3 processes image files, any image loaded this way will have premultiplied alpha.

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.

If the file path is relative, it is assumed to be with respect to Application#getAssetDirectory. If you wish to load a texture from somewhere else, you must use an absolute path.

Parameters

filename	The file supporting the texture file.
access	The image access
mipmaps	Flag to generate mipmaps

Returns: true if initialization was successful.

◆ initWithImage() [1/2]

bool cugl::graphics::Texture::initWithImage ( const std::shared_ptr< Image > & image )

Initializes an texture with the given image.

This texture will cover the entire image, and not just a subregion. Note that this texture does not copy the image, so any changes to the image elsewhere will affect this is texture.

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

Parameters

image The texture image

Returns: true if initialization was successful.

◆ initWithImage() [2/2]

bool cugl::graphics::Texture::initWithImage	(	const std::shared_ptr< Image > &	image,
		const std::shared_ptr< Sampler > &	sampler
	)

Initializes an texture with the given image and sampler.

This texture will cover the entire image, and not just a subregion. Note that this texture does not copy the image, so any changes to the image elsewhere will affect this is texture.

Parameters

image	The texture image
sampler	The texture sampler

Returns: true if initialization was successful.

◆ isPremultiplied()

bool cugl::graphics::Texture::isPremultiplied ( ) const

inline

Returns texture if this image uses premultiplied alpha.

Changing this value does not actually change the image data. It only changes how the texture is interpretted by the graphics backend.

By default, this value is true if the texture was read from a file (because of how SDL3 processes image files) and false otherwise.

Returns: true if this texture uses premultiplied alpha.

◆ isSubTexture()

bool cugl::graphics::Texture::isSubTexture ( ) const

inline

Returns true if this texture is a subtexture.

This method is the same as checking if the parent is not nullptr.

Returns: true if this texture is a subtexture.

◆ operator std::string()

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

inline

Casts from Texture to a string.

◆ operator=()

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

inline

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

If this is a subtexture, then this data is confined to the size of the texture region. Otherwise, this method is the same as in Image.

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

Parameters

data	The buffer to read into the texture

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

◆ set() [1/2]

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

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

If this is a subtexture, then this data is confined to the size of the texture region. Otherwise, this method is the same as in Image.

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

Parameters

data	The buffer to read into the texture

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

◆ set() [2/2]

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

inline

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

If this is a subtexture, then this data is confined to the size of the texture region. Otherwise, this method is the same as in Image.

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

Parameters

data	The buffer to read into the texture

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

◆ setMagFilter()

void cugl::graphics::Texture::setMagFilter ( TextureFilter filter )

inline

Sets the magnification filter of the associated sampler.

This is a convenience method that pushes directly to the sampler. The magnification filter is the algorithm hint that the graphics card uses to make an image larger. The default is LINEAR.

When this value is changed, the value will be pushed to the implementation and all subsequent drawing commands will use the new value. Previous drawing commands (including those in flight) are unaffected.

Parameters

filter The magnification filter of the associated sampler.

◆ setMinFilter()

void cugl::graphics::Texture::setMinFilter ( TextureFilter filter )

inline

Sets the minimization filter of the associated sampler.

This is a convenience method that pushes directly to the sampler. The minimization filter is the algorithm hint that the graphics card uses to make an image smaller. The default is LINEAR.

When this value is changed, the value will be pushed to the implementation and all subsequent drawing commands will use the new value. Previous drawing commands (including those in flight) are unaffected.

Parameters

filter The min filter of the associated sampler.

◆ setName()

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

inline

Sets the name of this texture.

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.

◆ setPremultiplied()

void cugl::graphics::Texture::setPremultiplied ( bool value )

inline

Sets whether this texture uses premultiplied alpha.

Changing this value does not actually change the image data. It only changes how the texture is interpretted by the graphics backend.

By default, this value is true if the texture was read from a file (because of how SDL3 processes image files) and false otherwise.

Parameters

value Whether this texture uses premultiplied alpha.

◆ setWrapS()

void cugl::graphics::Texture::setWrapS ( TextureWrap wrap )

inline

Sets the horizontal wrap of the associated sampler.

This is a convenience method that pushes directly to the sampler. When this value is changed, the value will be pushed to the implementation and all subsequent drawing commands will use the new value. Previous drawing commands (including those in flight) are unaffected.

The default is CLAMP.

Parameters

wrap	The horizontal wrap setting of the associated sampler.

◆ setWrapT()

void cugl::graphics::Texture::setWrapT ( TextureWrap wrap )

inline

Sets the vertical wrap of the associated sampler.

This is a convenience method that pushes directly to the sampler. When this value is changed, the value will be pushed to the implementation and all subsequent drawing commands will use the new value. Previous drawing commands (including those in flight) are unaffected.

The default is CLAMP.

Parameters

wrap	The vertical wrap setting of the associated sampler.

◆ toString()

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

Returns a string representation of this texture 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 texture for debugging purposes.

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

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

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Texture()

◆ ~Texture()

Member Function Documentation

◆ alloc()

◆ allocWithData()

◆ allocWithFile()

◆ allocWithImage() [1/2]

◆ allocWithImage() [2/2]

◆ dispose()

◆ get()

◆ getBlank()

◆ getHeight()

◆ getImage()

◆ getMagFilter()

◆ getMaxS()

◆ getMaxT()

◆ getMinFilter()

◆ getMinS()

◆ getMinT()

◆ getName()

◆ getOrigin()

◆ getSampler()

◆ getSize()

◆ getSubTexture()

◆ getT()

◆ getWidth()

◆ getWrapS()

◆ getWrapT()

◆ getX()

◆ id()

◆ init()

◆ initWithData()

◆ initWithFile()

◆ initWithImage() [1/2]

◆ initWithImage() [2/2]

◆ isPremultiplied()

◆ isSubTexture()

◆ operator std::string()

◆ operator=()

◆ set() [1/2]

◆ set() [2/2]

◆ setMagFilter()

◆ setMinFilter()

◆ setName()

◆ setPremultiplied()

◆ setWrapS()

◆ setWrapT()

◆ toString()