Reference-counted OpenGL texture. More...
#include <Texture.h>
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 | |
GLint | getCleanWidth () const |
the width of the texture in pixels accounting for its "clean" area - | |
GLint | getCleanHeight () const |
the height of the texture in pixels accounting for its "clean" area - | |
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] | |
Area | getCleanBounds () const |
the Area defining the Texture's clean pixel bounds in pixels: [0,0]-[width*maxU,height*maxV] | |
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. Does not compensate for clean coordinates. Does compensate for flipping. | |
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. |
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
typedef shared_ptr<Obj> Texture::* cinder::gl::Texture::unspecified_bool_type |
Emulates shared_ptr-like behavior.
cinder::gl::Texture::Texture | ( | ) |
Default initializer. Points to a null Obj.
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.
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.
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 | |||
) |
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.
Replaces the pixels of a texture with contents of surface. Expects area's size to match the Texture's.
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
GLint cinder::gl::Texture::getCleanWidth | ( | ) | const |
the width of the texture in pixels accounting for its "clean" area -
GLint cinder::gl::Texture::getCleanHeight | ( | ) | const |
the height of the texture in pixels accounting for its "clean" area -
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]
Area cinder::gl::Texture::getCleanBounds | ( | ) | const |
the Area defining the Texture's clean pixel bounds in pixels: [0,0]-[width*maxU,height*maxV]
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 |
Returns the UV coordinates which correspond to the pixels contained in area. Does not compensate for clean coordinates. Does compensate for flipping.
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.
shared_ptr<Obj> cinder::gl::Texture::mObj [protected] |