# Cinder

# cinder::gl::Texture Class Reference

Reference-counted OpenGL texture. More...

`#include <Texture.h>`

List of all members.

## Classes
struct | Format
struct | Obj
## Public Member Functions
| Texture ()
| Default initializer. Points to a null Obj.
| Texture (int aWidth, int aHeight, Format format=Format())
| Constructs a texture of size(aWidth, aHeight), storing the data in internal format aInternalFormat.
| Texture (const unsigned char *data, int dataFormat, int aWidth, int aHeight, Format format=Format())
| Constructs a texture of size(aWidth, aHeight), storing the data in internal format aInternalFormat. Pixel data is provided by data and is expected to be interleaved and in format dataFormat, for which `GL_RGB` or `GL_RGBA` would be typical values.
| Texture (const Surface8u &surface, Format format=Format())
| Constructs a texture based on the contents of surface. A default value of -1 for internalFormat chooses an appropriate internal format automatically.
| Texture (const Surface32f &surface, Format format=Format())
| Constructs a texture based on the contents of surface. A default value of -1 for internalFormat chooses an appropriate internal format automatically.
| Texture (const Channel8u &channel, Format format=Format())
| Constructs a texture based on the contents of channel. A default value of -1 for internalFormat chooses an appropriate internal format automatically.
| Texture (const Channel32f &channel, Format format=Format())
| Constructs a texture based on the contents of channel. A default value of -1 for internalFormat chooses an appropriate internal format automatically.
| Texture (ImageSourceRef imageSource, Format format=Format())
| Constructs a texture based on imageSource. A default value of -1 for internalFormat chooses an appropriate internal format based on the contents of imageSource.
| Texture (GLenum aTarget, GLuint aTextureID, int aWidth, int aHeight, bool aDoNotDispose)
| Constructs a Texture based on an externally initialized OpenGL texture. aDoNotDispose specifies whether the Texture is responsible for disposing of the associated OpenGL resource.
void | setDoNotDispose (bool aDoNotDispose=true)
| Determines whether the Texture will call glDeleteTextures() to free the associated texture objects on destruction.
void | setDeallocator (void(*aDeallocatorFunc)(void *), void *aDeallocatorRefcon)
| Installs an optional callback which fires when the texture is destroyed. Useful for integrating with external APIs.
void | setWrap (GLenum wrapS, GLenum wrapT)
| Sets the wrapping behavior when a texture coordinate falls outside the range of [0,1]. Possible values are `GL_CLAMP`, `GL_REPEAT` and `GL_CLAMP_TO_EDGE`.
void | setWrapS (GLenum wrapS)
| Sets the horizontal wrapping behavior when a texture coordinate falls outside the range of [0,1]. Possible values are `GL_CLAMP`, `GL_REPEAT` and `GL_CLAMP_TO_EDGE`.
void | setWrapT (GLenum wrapT)
| Sets the verical wrapping behavior when a texture coordinate falls outside the range of [0,1]. Possible values are `GL_CLAMP`, `GL_REPEAT` and `GL_CLAMP_TO_EDGE`.
void | setMinFilter (GLenum minFilter)
| Sets the filtering behavior when a texture is displayed at a lower resolution than its native resolution. Possible values are.
void | setMagFilter (GLenum magFilter)
void | setCleanTexCoords (float maxU, float maxV)
void | update (const Surface &surface)
| Replaces the pixels of a texture with contents of surface. Expects surface's size to match the Texture's.
void | update (const Surface &surface, const Area &area)
| Replaces the pixels of a texture with contents of surface. Expects area's size to match the Texture's.
void | update (const Channel8u &surface, const Area &area)
| Replaces the pixels of a texture with contents of channel. Expects area's size to match the Texture's.
GLint | getWidth () const
| the width of the texture in pixels
GLint | getHeight () const
| the height of the texture in pixels
Vec2i | getSize () const
| the size of the texture in pixels
float | getAspectRatio () const
| the aspect ratio of the texture (width / height)
Area | getBounds () const
| the Area defining the Texture's bounds in pixels: [0,0]-[width,height]
bool | hasAlpha () const
| whether the texture has an alpha channel
float | getLeft () const
| These return the right thing even when the texture coordinate space is flipped.
float | getRight () const
float | getTop () const
float | getBottom () const
float | getMaxU () const
| These do not correspond to "top" and "right" when the texture is flipped.
float | getMaxV () const
Rectf | getAreaTexCoords (const Area &area) const
| Returns the UV coordinates which correspond to the pixels contained in area.
GLint | getInternalFormat () const
| the Texture's internal format, which is the format that OpenGL stores the texture data in memory. Common values include `GL_RGB`, `GL_RGBA` and `GL_LUMINANCE`
GLuint | getTextureId () const
| the ID number for the texture, appropriate to pass to calls like `glBindTexture()`
GLenum | getTarget () const
| the target associated with texture. Typical values are `GL_TEXTURE_2D` and `GL_TEXTURE_RECTANGLE_ARB`
bool | isFlipped () const
| whether the texture is flipped vertically
void | setFlipped (bool aFlipped=true)
| Marks the texture as being flipped vertically or not.
void | enableAndBind () const
| Enables the Texture's target and binds its associated texture. Equivalent to calling.
void | disable () const
| Disables the Texture's target.
void | bind (GLuint textureUnit=0) const
| Binds the Texture's texture to its target in the multitexturing unit `GL_TEXTURE0` + textureUnit.
void | unbind (GLuint textureUnit=0) const
| Unbinds the Texture currently bound in the Texture's target.
Texture | weakClone () const
| Creates a clone of this texture which does not have ownership, but points to the same resource.
| operator ImageSourceRef () const
| Returns an ImageSource pointing to this Texture.
## Static Public Member Functions
static Texture | loadDds (IStreamRef ddsStream, Format format)
| Creates a new Texture from raw DirectDraw Stream data.
static void | SurfaceChannelOrderToDataFormatAndType (const SurfaceChannelOrder &sco, GLint *dataFormat, GLenum *type)
| Converts a SurfaceChannelOrder into an appropriate OpenGL dataFormat and type.
static bool | dataFormatHasAlpha (GLint dataFormat)
| Returns whether a given OpenGL dataFormat contains an alpha channel.
static bool | dataFormatHasColor (GLint dataFormat)
| Returns whether a give OpenGL dataFormat contains color channels.
## Protected Member Functions
void | init (const unsigned char *data, int unpackRowLength, GLenum dataFormat, GLenum type, const Format &format)
void | init (const float *data, GLint dataFormat, const Format &format)
void | init (ImageSourceRef imageSource, const Format &format)
## Protected Attributes
shared_ptr< Obj > | mObj
typedef shared_ptr< Obj > Texture::* | unspecified_bool_type
| Emulates shared_ptr-like behavior.
| operator unspecified_bool_type ()
| Emulates shared_ptr-like behavior.
void | reset ()
| Emulates shared_ptr-like behavior.

## Detailed Description

Reference-counted OpenGL texture.

Texture represents an OpenGL texture object. It maintains an internal reference-counted pointer which supports copying and assignment and properly frees the associated OpenGL resources.
Example Usage:

        gl::Texture myTexture = gl::Texture( loadImage( loadFile( "someFile.png" ) ) ); // creates an OpenGL texture based on a file
        myTexture.enableAndBind();
        ... // OpenGL commands using the texture
        myTexture.unbind();
        gl::Texture myOtherTexture = myTexture; // this does the right thing and does not risk a double-free of the OpenGL resource

## Member Typedef Documentation

typedef shared_ptr<Obj> Texture::* cinder::gl::Texture::unspecified_bool_type

Emulates shared_ptr-like behavior.

## Constructor & Destructor Documentation

cinder::gl::Texture::Texture | ( |  | ) |

Default initializer. Points to a null Obj.

cinder::gl::Texture::Texture | ( | int | aWidth,
|  | int | aHeight,
|  | Format | format = `Format()` |
| ) |  |  |

Constructs a texture of size(aWidth, aHeight), storing the data in internal format aInternalFormat.

cinder::gl::Texture::Texture | ( | const unsigned char * | data,
|  | int | dataFormat,
|  | int | aWidth,
|  | int | aHeight,
|  | Format | format = `Format()` |
| ) |  |  |

Constructs a texture of size(aWidth, aHeight), storing the data in internal format aInternalFormat. Pixel data is provided by data and is expected to be interleaved and in format dataFormat, for which `GL_RGB` or `GL_RGBA` would be typical values.

cinder::gl::Texture::Texture | ( | const Surface8u & | surface,
|  | Format | format = `Format()` |
| ) |  |  |

Constructs a texture based on the contents of surface. A default value of -1 for internalFormat chooses an appropriate internal format automatically.

cinder::gl::Texture::Texture | ( | const Surface32f & | surface,
|  | Format | format = `Format()` |
| ) |  |  |

Constructs a texture based on the contents of surface. A default value of -1 for internalFormat chooses an appropriate internal format automatically.

cinder::gl::Texture::Texture | ( | const Channel8u & | channel,
|  | Format | format = `Format()` |
| ) |  |  |

Constructs a texture based on the contents of channel. A default value of -1 for internalFormat chooses an appropriate internal format automatically.

cinder::gl::Texture::Texture | ( | const Channel32f & | channel,
|  | Format | format = `Format()` |
| ) |  |  |

Constructs a texture based on the contents of channel. A default value of -1 for internalFormat chooses an appropriate internal format automatically.

cinder::gl::Texture::Texture | ( | ImageSourceRef | imageSource,
|  | Format | format = `Format()` |
| ) |  |  |

Constructs a texture based on imageSource. A default value of -1 for internalFormat chooses an appropriate internal format based on the contents of imageSource.

cinder::gl::Texture::Texture | ( | GLenum | aTarget,
|  | GLuint | aTextureID,
|  | int | aWidth,
|  | int | aHeight,
|  | bool | aDoNotDispose |
| ) |  |  |

Constructs a Texture based on an externally initialized OpenGL texture. aDoNotDispose specifies whether the Texture is responsible for disposing of the associated OpenGL resource.

## Member Function Documentation

void cinder::gl::Texture::setDoNotDispose | ( | bool | aDoNotDispose = `true` | ) |

Determines whether the Texture will call glDeleteTextures() to free the associated texture objects on destruction.

void cinder::gl::Texture::setDeallocator | ( | void(*)(void *) | aDeallocatorFunc,
|  | void * | aDeallocatorRefcon |
| ) |  |  |

Installs an optional callback which fires when the texture is destroyed. Useful for integrating with external APIs.

void cinder::gl::Texture::setWrap | ( | GLenum | wrapS,
|  | GLenum | wrapT |
| ) |  |  |

Sets the wrapping behavior when a texture coordinate falls outside the range of [0,1]. Possible values are `GL_CLAMP`, `GL_REPEAT` and `GL_CLAMP_TO_EDGE`.

void cinder::gl::Texture::setWrapS | ( | GLenum | wrapS | ) |

Sets the horizontal wrapping behavior when a texture coordinate falls outside the range of [0,1]. Possible values are `GL_CLAMP`, `GL_REPEAT` and `GL_CLAMP_TO_EDGE`.

void cinder::gl::Texture::setWrapT | ( | GLenum | wrapT | ) |

Sets the verical wrapping behavior when a texture coordinate falls outside the range of [0,1]. Possible values are `GL_CLAMP`, `GL_REPEAT` and `GL_CLAMP_TO_EDGE`.

void cinder::gl::Texture::setMinFilter | ( | GLenum | minFilter | ) |

Sets the filtering behavior when a texture is displayed at a lower resolution than its native resolution. Possible values are.

- `GL_NEAREST`
- `GL_LINEAR`
- `GL_NEAREST_MIPMAP_NEAREST`
- `GL_LINEAR_MIPMAP_NEAREST`
- `GL_NEAREST_MIPMAP_LINEAR`
- `GL_LINEAR_MIPMAP_LINEAR`

void cinder::gl::Texture::setMagFilter | ( | GLenum | magFilter | ) |

Sets the filtering behavior when a texture is displayed at a higher resolution than its native resolution. Possible values are

- `GL_NEAREST`
- `GL_LINEAR`
- `GL_NEAREST_MIPMAP_NEAREST`
- `GL_LINEAR_MIPMAP_NEAREST`
- `GL_NEAREST_MIPMAP_LINEAR`
- `GL_LINEAR_MIPMAP_LINEAR`

void cinder::gl::Texture::setCleanTexCoords | ( | float | maxU,
|  | float | maxV |
| ) |  |  |

Designed to accommodate texture where not all pixels are "clean", meaning the maximum texture coordinate value may not be 1.0 (or the texture's width in `GL_TEXTURE_RECTANGLE_ARB`)

void cinder::gl::Texture::update | ( | const Surface & | surface | ) |

Replaces the pixels of a texture with contents of surface. Expects surface's size to match the Texture's.

void cinder::gl::Texture::update | ( | const Surface & | surface,
|  | const Area & | area |
| ) |  |  |

Replaces the pixels of a texture with contents of surface. Expects area's size to match the Texture's.

void cinder::gl::Texture::update | ( | const Channel8u & | surface,
|  | const Area & | area |
| ) |  |  |

Replaces the pixels of a texture with contents of channel. Expects area's size to match the Texture's.

GLint cinder::gl::Texture::getWidth | ( |  | ) | const

the width of the texture in pixels

GLint cinder::gl::Texture::getHeight | ( |  | ) | const

the height of the texture in pixels

Vec2i cinder::gl::Texture::getSize | ( |  | ) | const

the size of the texture in pixels

float cinder::gl::Texture::getAspectRatio | ( |  | ) | const

the aspect ratio of the texture (width / height)

Area cinder::gl::Texture::getBounds | ( |  | ) | const

the Area defining the Texture's bounds in pixels: [0,0]-[width,height]

bool cinder::gl::Texture::hasAlpha | ( |  | ) | const

whether the texture has an alpha channel

float cinder::gl::Texture::getLeft | ( |  | ) | const

These return the right thing even when the texture coordinate space is flipped.

float cinder::gl::Texture::getRight | ( |  | ) | const

float cinder::gl::Texture::getTop | ( |  | ) | const

float cinder::gl::Texture::getBottom | ( |  | ) | const

float cinder::gl::Texture::getMaxU | ( |  | ) | const

These do not correspond to "top" and "right" when the texture is flipped.

float cinder::gl::Texture::getMaxV | ( |  | ) | const

Rectf cinder::gl::Texture::getAreaTexCoords | ( | const Area & | area | ) | const

Returns the UV coordinates which correspond to the pixels contained in area.

GLint cinder::gl::Texture::getInternalFormat | ( |  | ) | const

the Texture's internal format, which is the format that OpenGL stores the texture data in memory. Common values include `GL_RGB`, `GL_RGBA` and `GL_LUMINANCE`

GLuint cinder::gl::Texture::getTextureId | ( |  | ) | const

the ID number for the texture, appropriate to pass to calls like `glBindTexture()`

GLenum cinder::gl::Texture::getTarget | ( |  | ) | const

the target associated with texture. Typical values are `GL_TEXTURE_2D` and `GL_TEXTURE_RECTANGLE_ARB`

bool cinder::gl::Texture::isFlipped | ( |  | ) | const

whether the texture is flipped vertically

void cinder::gl::Texture::setFlipped | ( | bool | aFlipped = `true` | ) |

Marks the texture as being flipped vertically or not.

void cinder::gl::Texture::enableAndBind | ( |  | ) | const

Enables the Texture's target and binds its associated texture. Equivalent to calling.

     glEnable( target ); glBindTexture( target, textureID );

void cinder::gl::Texture::disable | ( |  | ) | const

Disables the Texture's target.

void cinder::gl::Texture::bind | ( | GLuint | textureUnit = `0` | ) | const

Binds the Texture's texture to its target in the multitexturing unit `GL_TEXTURE0` + textureUnit.

void cinder::gl::Texture::unbind | ( | GLuint | textureUnit = `0` | ) | const

Unbinds the Texture currently bound in the Texture's target.

Texture cinder::gl::Texture::loadDds | ( | IStreamRef | ddsStream,
|  | Format | format |
| ) |  |  | `[static]`

Creates a new Texture from raw DirectDraw Stream data.

void cinder::gl::Texture::SurfaceChannelOrderToDataFormatAndType | ( | const SurfaceChannelOrder & | sco,
|  | GLint * | dataFormat,
|  | GLenum * | type |
| ) |  |  | `[static]`

Converts a SurfaceChannelOrder into an appropriate OpenGL dataFormat and type.

bool cinder::gl::Texture::dataFormatHasAlpha | ( | GLint | dataFormat | ) | `[static]`

Returns whether a given OpenGL dataFormat contains an alpha channel.

bool cinder::gl::Texture::dataFormatHasColor | ( | GLint | dataFormat | ) | `[static]`

Returns whether a give OpenGL dataFormat contains color channels.

Texture cinder::gl::Texture::weakClone | ( |  | ) | const

Creates a clone of this texture which does not have ownership, but points to the same resource.

cinder::gl::Texture::operator ImageSourceRef | ( |  | ) | const

Returns an ImageSource pointing to this Texture.

void cinder::gl::Texture::init | ( | const unsigned char * | data,
|  | int | unpackRowLength,
|  | GLenum | dataFormat,
|  | GLenum | type,
|  | const Format & | format |
| ) |  |  | `[protected]`

void cinder::gl::Texture::init | ( | const float * | data,
|  | GLint | dataFormat,
|  | const Format & | format |
| ) |  |  | `[protected]`

void cinder::gl::Texture::init | ( | ImageSourceRef | imageSource,
|  | const Format & | format |
| ) |  |  | `[protected]`

cinder::gl::Texture::operator unspecified_bool_type | ( |  | ) |

Emulates shared_ptr-like behavior.

void cinder::gl::Texture::reset | ( |  | ) |

Emulates shared_ptr-like behavior.

## Member Data Documentation

shared_ptr<Obj> cinder::gl::Texture::mObj`[protected]`

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

- include/cinder/gl/Texture.h
- src/cinder/gl/Texture.cpp