#include <CUTexture.h>

Inheritance diagram for cugl::Texture:

Public Types
enum class	PixelFormat : GLenum { RGBA = GL_RGBA , RGB = GL_RGB , RED = GL_RED , RED_GREEN = GL_RG , DEPTH = GL_DEPTH_COMPONENT , DEPTH_STENCIL = GL_DEPTH_STENCIL }

Public Member Functions
	Texture ()

	~Texture ()

void	dispose ()

bool	init (int width, int height, PixelFormat format=PixelFormat::RGBA)

bool	initWithData (const void *data, int width, int height, PixelFormat format=PixelFormat::RGBA)

bool	initWithFile (const std::string filename)

const Texture &	operator= (const void *data)

const Texture &	set (const void *data)

void	setName (std::string name)

const std::string	getName () const

bool	isReady () const

unsigned int	getWidth () const

unsigned int	getHeight () const

Size	getSize ()

unsigned int	getByteSize () const

PixelFormat	getFormat () const

bool	hasMipMaps () const

void	buildMipMaps ()

GLuint	getMinFilter () const

GLuint	getMagFilter () const

void	setMinFilter (GLuint minFilter)

void	setMagFilter (GLuint magFilter)

GLuint	getWrapS () const

GLuint	getWrapT () const

void	setWrapS (GLuint wrap)

void	setWrapT (GLuint wrap)

const std::shared_ptr< Texture > &	getParent () const

std::shared_ptr< Texture >	getParent ()

std::shared_ptr< Texture >	getSubTexture (GLfloat minS, GLfloat maxS, GLfloat minT, GLfloat maxT)

bool	isSubTexture () const

GLfloat	getMinS () const

GLfloat	getMinT () const

GLfloat	getMaxS () const

GLfloat	getMaxT () const

GLuint	getBuffer () const

GLuint	getBindPoint () const

void	setBindPoint (GLuint point)

void	bind ()

void	unbind ()

bool	isBound () const

bool	isActive () const

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

	operator std::string () const

bool	save (const std::string file)

Static Public Member Functions
static std::shared_ptr< Texture >	alloc (int width, int height, PixelFormat format=PixelFormat::RGBA)

static std::shared_ptr< Texture >	allocWithData (const void *data, int width, int height, PixelFormat format=PixelFormat::RGBA)

static std::shared_ptr< Texture >	allocWithFile (const std::string filename)

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

Detailed Description

This is a class representing an OpenGL texture.

We enforce that all textures must be a power-of-two along each dimension (though they need not be square). This is still required by some mobile devices and so it is easiest to require it across the board.

This class also provides support for texture atlases. Any non-repeating texture can produce a subtexture. A subtexture wraps the same texture data (and so does not require a context switch in the rendering pipeline), but has different start and end boundaries, as defined by minS, maxS, minT and maxT. See getSubtexture() for more information.

Shaders and textures have a many-to-many relationship. At any given time, a texture may be providing data to multiple shaders, and a shader may be working with multiple textures. This many-to-many relationship is captured by bind points. A texture is bound to a specific bind point and a shader associates a bind point with a sampler variable. That sampler variable then pulls data from the appropriate texture.

When discussing the relationship between a shader and a texture, we talk about a texture being bound and a texture being active. A bound texture is one that is associated with a shader; the shader will pull from the texture in a sampler variable. An active texture is one that is capable of receiving data from the CPU. A texture must be active if the user wants to change the data or filter settings of a texture.

Ideally, bound and active should be two separate concepts, like they are in UniformBuffer. However, for legacy reasons, OpenGL does not allow a texture to be active without being bound. Hence the bind method below is used for both activating and binding a texture.

Member Enumeration Documentation

◆ PixelFormat

enum class cugl::Texture::PixelFormat : GLenum

strong

This enum lists the possible texture pixel formats.

This enum defines the pixel formats supported by CUGL. Because of cross-platform issues (we must support both OpenGL and OpenGLES), our textures only support a small subset of formats.

This enum also associates default internal types and data types with each pixel format. This greatly simplifies texture creation at the loss of some flexibility.

Enumerator
RGBA	The default format: RGB with alpha transparency. This format uses GL_RGBA8 as the internal format. The data type (for each component) is unsigned byte.
RGB	RGB with no alpha All blending with this texture assumes alpha is 1.0. This format uses GL_RGB8 as the internal format. The data type (for each component) is unsigned byte.
RED	A single color channel. In OpenGL that is identified as red. The green and blue values will be 0. All blending with this texture assumes alpha is 1.0. This format uses GL_RGB8 as the internal format. The data type (for each component) is unsigned byte.
RED_GREEN	A dual color channel. In OpenGL that is identified as red and green. The blue values will be 0. All blending with this texture assumes alpha is 1.0. This format uses GL_RGB8 as the internal format. The data type (for each component) is unsigned byte.
DEPTH	A texture used to store a depth component. This format uses GL_DEPTH_COMPONENT32F as the internal format. The data type (for the only component) is float.
DEPTH_STENCIL	A texture used to store a combined depth and stencil component This format uses GL_DEPTH24_STENCIL8 as the internal format. The data type is GL_UNSIGNED_INT_24_8, giving 24 bytes to depth and 8 bits to the stencil.

Constructor & Destructor Documentation

◆ Texture()

cugl::Texture::Texture ( )

Creates a new empty texture with no size.

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

◆ ~Texture()

cugl::Texture::~Texture ( )

inline

Deletes this texture, disposing all resources

Member Function Documentation

◆ alloc()

static std::shared_ptr< Texture > cugl::Texture::alloc	(	int	width,
		int	height,
		PixelFormat	format = `PixelFormat::RGBA`
	)

inlinestatic

Returns a new empty texture with the given dimensions.

Allocating a texture requires the use of the binding point at 0. Any texture bound to that point will be unbound. In addition, once allocation is done, this texture will not longer be bound as well.

You must use the set() method to load data into the texture.

Parameters

width	The texture width in pixels
height	The texture height in pixels
format	The texture data format

Returns: a new empty texture with the given dimensions.

◆ allocWithData()

static std::shared_ptr< Texture > cugl::Texture::allocWithData	(	const void *	data,
		int	width,
		int	height,
		PixelFormat	format = `PixelFormat::RGBA`
	)

inlinestatic

Returns a new texture with the given data.

Allocating a texture requires the use of the binding point at 0. Any texture bound to that point will be unbound. In addition, once allocation is done, this texture will not longer be bound as well.

The data format must match the one given.

Parameters

data	The texture data (size widthheightformat)
width	The texture width in pixels
height	The texture height in pixels
format	The texture data format

Returns: a new texture with the given data.

◆ allocWithFile()

static std::shared_ptr< Texture > cugl::Texture::allocWithFile ( const std::string filename )

inlinestatic

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

Allocating a texture requires the use of the binding point at 0. Any texture bound to that point will be unbound. In addition, once allocation is done, this texture will not longer be bound as well.

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 texture will be stored in RGBA format, even if it is a file format that does not support transparency (e.g. JPEG).

Parameters

filename The file supporting the texture file.

Returns: a new texture with the given data

◆ bind()

void cugl::Texture::bind ( )

Binds this texture to its bind point, making

Because of legacy issues with OpenGL, this method actually does two things. It attaches the block to the correct bind point, as defined by setBindPoint. It also makes this the active texture, capable of receiving OpenGL commands.

Unlike UniformBuffer is not possible to bind a texture without making it the active texture. Therefore, any existing texture will be deactivated, no matter its bind point. So this texture can be unbound without a call to unbind.

This call is reentrant. If can be safely called multiple times.

◆ buildMipMaps()

void cugl::Texture::buildMipMaps ( )

Builds mipmaps for the current texture.

This method will fail if this texture is a subtexture. Only the parent texture can have mipmaps. In addition, mipmaps can only be built if the texture size is a power of two.

This method is only successful if the texture is currently active.

◆ dispose()

void cugl::Texture::dispose ( )

Deletes the OpenGL texture and resets all attributes.

You must reinitialize the texture to use it.

◆ getBindPoint()

GLuint cugl::Texture::getBindPoint ( ) const

inline

Returns the bind point for this texture.

Textures and shaders have a many-to-many relationship. This means that connecting them requires an intermediate table. The positions in this table are called bind points. A texture is associated with a bind point and a shader associates a bind point with a sampler variable. That sampler variable then pulls data from the appropriate texture. By default this value is 0.

Returns: the bind point for for this texture.

◆ getBlank()

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

static

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

Allocating a texture requires the use of the binding point at 0. Any texture bound to that point will be unbound. In addition, once allocation is done, this texture will not longer be bound as well.

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.

◆ getBuffer()

GLuint cugl::Texture::getBuffer ( ) const

inline

Returns the OpenGL buffer for this texture.

The buffer is a value assigned by OpenGL when the texture was allocated. This method will return 0 if the texture is not initialized.

Returns: the OpenGL buffer for this texture.

◆ getByteSize()

unsigned int cugl::Texture::getByteSize ( ) const

Returns the number of bytes in a single pixel of this texture.

Returns: the number of bytes in a single pixel of this texture.

◆ getFormat()

PixelFormat cugl::Texture::getFormat ( ) const

inline

Returns the data format of this texture.

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

Returns: the data format of this texture.

◆ getHeight()

unsigned int cugl::Texture::getHeight ( ) const

inline

Returns the height of this texture in pixels.

Returns: the height of this texture in pixels.

◆ getMagFilter()

GLuint cugl::Texture::getMagFilter ( ) const

inline

Returns the mag filter of this texture.

The mag filter is the algorithm hint that OpenGL uses to make an image larger. The default is GL_LINEAR.

Returns: the mag filter of this texture.

◆ getMaxS()

GLfloat cugl::Texture::getMaxS ( ) const

inline

Returns the maximum S texture coordinate for this texture.

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

Returns: the maximum S texture coordinate for this texture.

◆ getMaxT()

GLfloat cugl::Texture::getMaxT ( ) const

inline

Returns the maximum T texture coordinate for this texture.

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

Returns: the maximum T texture coordinate for this texture.

◆ getMinFilter()

GLuint cugl::Texture::getMinFilter ( ) const

inline

Returns the min filter of this texture.

The min filter is the algorithm hint that OpenGL uses to make an image smaller. The default is GL_NEAREST.

Returns: the min filter of this texture.

◆ getMinS()

GLfloat cugl::Texture::getMinS ( ) const

inline

Returns the minimum S texture coordinate for this texture.

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

Returns: the minimum S texture coordinate for this texture.

◆ getMinT()

GLfloat cugl::Texture::getMinT ( ) const

inline

Returns the minimum T texture coordinate for this texture.

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

Returns: the minimum T texture coordinate for this texture.

◆ getName()

const std::string cugl::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.

◆ getParent() [1/2]

std::shared_ptr< Texture > cugl::Texture::getParent ( )

inline

Returns the parent texture of this subtexture.

This method will return nullptr is this is not a subtexture.

Returns the parent texture of this subtexture.

◆ getParent() [2/2]

const std::shared_ptr< Texture > & cugl::Texture::getParent ( ) const

inline

Returns the parent texture of this subtexture.

This method will return nullptr is this is not a subtexture.

Returns the parent texture of this subtexture.

◆ getSize()

Size cugl::Texture::getSize ( )

inline

Returns the size of this texture in pixels.

Returns: the size of this texture in pixels.

◆ getSubTexture()

std::shared_ptr< Texture > cugl::Texture::getSubTexture	(	GLfloat	minS,
		GLfloat	maxS,
		GLfloat	minT,
		GLfloat	maxT
	)

Returns a subtexture with the given dimensions.

The values must be 0 <= minS <= maxS <= 1 and 0 <= minT <= maxT <= 1. They specify the region of the texture to extract the subtexture.

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

It is possible to make a subtexture of a subtexture. However, in that case, the minS, maxS, minT and maxT values are all with respect to the original root texture. Furthermore, the parent of the new subtexture will be the original root texture. So no tree of subtextures is more than one level deep.

Returns a subtexture with the given dimensions.

◆ getWidth()

unsigned int cugl::Texture::getWidth ( ) const

inline

Returns the width of this texture in pixels.

Returns: the width of this texture in pixels.

◆ getWrapS()

GLuint cugl::Texture::getWrapS ( ) const

inline

Returns the horizontal wrap of this texture.

The default is GL_CLAMP_TO_EDGE.

Returns: the horizontal wrap of this texture.

◆ getWrapT()

GLuint cugl::Texture::getWrapT ( ) const

inline

Returns the vertical wrap of this texture.

The default is GL_CLAMP_TO_EDGE.

Returns: the vertical wrap of this texture.

◆ hasMipMaps()

bool cugl::Texture::hasMipMaps ( ) const

inline

Returns whether this texture has generated mipmaps.

If this texture is a subtexture of texture with mipmaps, this method will also return true (and vice versa).

Returns: whether this texture has generated mipmaps.

◆ init()

bool cugl::Texture::init	(	int	width,
		int	height,
		PixelFormat	format = `PixelFormat::RGBA`
	)

inline

Initializes an empty texture with the given dimensions.

Initializing a texture requires the use of the binding point at 0. Any texture bound to that point will be unbound. In addition, once initialization is done, this texture will not longer be bound as well.

You must use the set() method to load data into the texture.

Parameters

width	The texture width in pixels
height	The texture height in pixels
format	The texture data format

Returns: true if initialization was successful.

◆ initWithData()

bool cugl::Texture::initWithData	(	const void *	data,
		int	width,
		int	height,
		PixelFormat	format = `PixelFormat::RGBA`
	)

Initializes an texture with the given data.

Initializing a texture requires the use of the binding point at 0. Any texture bound to that point will be unbound. In addition, once initialization is done, this texture will not longer be bound as well.

The data format must match the one given.

Parameters

data	The texture data (size widthheightformat)
width	The texture width in pixels
height	The texture height in pixels
format	The texture data format

Returns: true if initialization was successful.

◆ initWithFile()

bool cugl::Texture::initWithFile ( const std::string filename )

Initializes an texture with the data from the given file.

Initializing a texture requires the use of the binding point at 0. Any texture bound to that point will be unbound. In addition, once initialization is done, this texture will not longer be bound as well.

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 texture will be stored in RGBA format, even if it is a file format that does not support transparency (e.g. JPEG).

IMPORTANT: In CUGL, relative path names always refer to the asset directory. If you wish to load a texture from somewhere else, you must use an absolute pathname.

Parameters

filename The file supporting the texture file.

Returns: true if initialization was successful.

◆ isActive()

bool cugl::Texture::isActive ( ) const

Returns true if this texture is currently active.

An active uniform block is the one that receives data from OpenGL calls (such as glTexImage2D). Many of the setter-like methods in this class require the texture to be active to work properly (because of how OpenGL calls are wrapped).

Unlike UniformBuffer, it is not possible for a texture to be active without being bound. To activate a texture simply call the bind method.

Returns: true if this texture is currently active.

◆ isBound()

bool cugl::Texture::isBound ( ) const

Returns true if this texture is currently bound.

A texture is bound if it is attached to a bind point. That means that the shader will pull sampler data for that bind point from this texture.

A texture can be bound without being active. This happens when another texture has subsequently been bound, but to a different bind point.

Returns: true if this texture is currently bound.

◆ isReady()

bool cugl::Texture::isReady ( ) const

inline

Returns true if this texture has been loaded into memory.

Returns: true if this texture has been loaded into memory.

◆ isSubTexture()

bool cugl::Texture::isSubTexture ( ) const

inline

Returns true if this texture is a subtexture.

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

Returns: true if this texture is a subtexture.

◆ operator std::string()

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

inline

Casts from Texture to a string.

◆ operator=()

const Texture & cugl::Texture::operator= ( const void * data )

inline

Sets this texture 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 is only successful if the texture is currently active.

Parameters

data	The buffer to read into the texture

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

◆ save()

bool cugl::Texture::save ( const std::string file )

Returns true if able to save the texture to the given file.

The image will be saved as a PNG file. If the suffix of file is not .png, then this suffix will be added.

This method is only successful if the texture is currently active.

IMPORTANT: In CUGL, relative path names always refer to the asset directory, which is a read-only directory. Therefore, the file must must be specified with an absolute path. Using a relative path for this method will cause this method to fail.

Parameters

file	The name of the file to write to

Returns: true if able to save the texture to the given file.

◆ set()

const Texture & cugl::Texture::set ( const void * data )

Sets this texture 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 is only successful if the texture is currently active.

Parameters

data	The buffer to read into the texture

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

◆ setBindPoint()

void cugl::Texture::setBindPoint ( GLuint point )

Sets the bind point for this texture.

Textures and shaders have a many-to-many relationship. This means that connecting them requires an intermediate table. The positions in this table are called bind points. A texture is associated with a bind point and a shader associates a bind point with a sampler variable. That sampler variable then pulls data from the appropriate texture. By default this value is 0.

The texture does not need to be active to call this method. This method only sets the bind point preference and does not actually bind the texture. However, if the texture is bound to another bind point, then it will be unbound from that point.

Parameters

point The bind point for this texture.

◆ setMagFilter()

void cugl::Texture::setMagFilter ( GLuint magFilter )

Sets the mag filter of this texture.

The mag filter is the algorithm hint that OpenGL uses to make an image larger. The default is GL_LINEAR.

This method may be safely called even if this texture is not active. The preference will be applied once the texture is activated.

Parameters

magFilter The mag filter of this texture.

◆ setMinFilter()

void cugl::Texture::setMinFilter ( GLuint minFilter )

Sets the min filter of this texture.

The min filter is the algorithm hint that OpenGL uses to make an image smaller. The default is GL_NEAREST.

This method may be safely called even if this texture is not active. The preference will be applied once the texture is activated.

Parameters

minFilter The min filter of this texture.

◆ setName()

void cugl::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.

◆ setWrapS()

void cugl::Texture::setWrapS ( GLuint wrap )

Sets the horizontal wrap of this texture.

The default is GL_CLAMP_TO_EDGE.

This method may be safely called even if this texture is not active. The preference will be applied once the texture is activated.

Parameters

wrap	The horizontal wrap setting of this texture

◆ setWrapT()

void cugl::Texture::setWrapT ( GLuint wrap )

Sets the vertical wrap of this texture.

The default is GL_CLAMP_TO_EDGE.

This method may be safely called even if this texture is not active. The preference will be applied once the texture is activated.

Parameters

wrap	The vertical wrap setting of this texture

◆ toString()

std::string cugl::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.

◆ unbind()

void cugl::Texture::unbind ( )

Unbinds this texture, making it neither bound nor active.

If another texture is active, calling this method will not effect that texture. But once unbound, the shader will no longer receive data from the bind point for this texture. A new texture must be bound for the shader to receive data.

Unlike UniformBuffer, it is not possible to unbind a texture without deactivating it.

This call is reentrant. If can be safely called multiple times.

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

cugl/include/cugl/render/CUTexture.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ PixelFormat

Constructor & Destructor Documentation

◆ Texture()

◆ ~Texture()

Member Function Documentation

◆ alloc()

◆ allocWithData()

◆ allocWithFile()

◆ bind()

◆ buildMipMaps()

◆ dispose()

◆ getBindPoint()

◆ getBlank()

◆ getBuffer()

◆ getByteSize()

◆ getFormat()

◆ getHeight()

◆ getMagFilter()

◆ getMaxS()

◆ getMaxT()

◆ getMinFilter()

◆ getMinS()

◆ getMinT()

◆ getName()

◆ getParent() [1/2]

◆ getParent() [2/2]

◆ getSize()

◆ getSubTexture()

◆ getWidth()

◆ getWrapS()

◆ getWrapT()

◆ hasMipMaps()

◆ init()

◆ initWithData()

◆ initWithFile()

◆ isActive()

◆ isBound()

◆ isReady()

◆ isSubTexture()

◆ operator std::string()

◆ operator=()

◆ save()

◆ set()

◆ setBindPoint()

◆ setMagFilter()

◆ setMinFilter()

◆ setName()

◆ setWrapS()

◆ setWrapT()

◆ toString()

◆ unbind()