CUGL 2.1
Cornell University Game Library
Public Types | Public Member Functions | Static Public Member Functions | List of all members
cugl::Texture Class Reference

#include <CUTexture.h>

Inheritance diagram for cugl::Texture:

Public Types

enum  PixelFormat : GLenum {
  PixelFormat::RGBA = GL_RGBA, PixelFormat::RGB = GL_RGB, PixelFormat::RED = GL_RED, PixelFormat::RED_GREEN = GL_RG,
  PixelFormat::DEPTH = GL_DEPTH_COMPONENT, PixelFormat::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 Textureoperator= (const void *data)
 
const Textureset (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< TexturegetParent ()
 
std::shared_ptr< TexturegetSubTexture (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< Texturealloc (int width, int height, PixelFormat format=PixelFormat::RGBA)
 
static std::shared_ptr< TextureallocWithData (const void *data, int width, int height, PixelFormat format=PixelFormat::RGBA)
 
static std::shared_ptr< TextureallocWithFile (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 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
widthThe texture width in pixels
heightThe texture height in pixels
formatThe 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
dataThe texture data (size width*height*format)
widthThe texture width in pixels
heightThe texture height in pixels
formatThe 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
filenameThe 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
widthThe texture width in pixels
heightThe texture height in pixels
formatThe 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
dataThe texture data (size width*height*format)
widthThe texture width in pixels
heightThe texture height in pixels
formatThe 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
filenameThe 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
dataThe 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
fileThe 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
dataThe 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
pointThe 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
magFilterThe 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
minFilterThe 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
nameThe 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
wrapThe 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
wrapThe 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
verboseWhether 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: