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< ObjmObj



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: