Cinder  0.8.6
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
cinder::gl::Texture Class Reference

Represents an OpenGL Texture. Implicitly shared object. More...

#include <Texture.h>

Classes

struct  Format
 
struct  Obj
 

Public Member Functions

 Texture ()
 Default initializer. Points to a null Obj. More...
 
 Texture (int aWidth, int aHeight, Format format=Format())
 Constructs a texture of size(aWidth, aHeight), storing the data in internal format aInternalFormat. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
void setDoNotDispose (bool aDoNotDispose=true)
 Determines whether the Texture will call glDeleteTextures() to free the associated texture objects on destruction. More...
 
void setDeallocator (void(*aDeallocatorFunc)(void *), void *aDeallocatorRefcon)
 Installs an optional callback which fires when the texture is destroyed. Useful for integrating with external APIs. More...
 
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. More...
 
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. More...
 
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. More...
 
void setMinFilter (GLenum minFilter)
 Sets the filtering behavior when a texture is displayed at a lower resolution than its native resolution. Possible values are. More...
 
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. More...
 
void update (const Surface32f &surface)
 Replaces the pixels of a texture with contents of surface. Expects surface's size to match the Texture's. More...
 
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. More...
 
void update (const Channel32f &channel)
 Replaces the pixels of a texture with contents of channel. Expects channel's size to match the Texture's. More...
 
void update (const Channel8u &channel, const Area &area)
 Replaces the pixels of a texture with contents of channel. Expects area's size to match the Texture's. More...
 
GLint getWidth () const
 the width of the texture in pixels More...
 
GLint getHeight () const
 the height of the texture in pixels More...
 
GLint getCleanWidth () const
 the width of the texture in pixels accounting for its "clean" area - More...
 
GLint getCleanHeight () const
 the height of the texture in pixels accounting for its "clean" area - More...
 
Vec2i getSize () const
 the size of the texture in pixels More...
 
float getAspectRatio () const
 the aspect ratio of the texture (width / height) More...
 
Area getBounds () const
 the Area defining the Texture's bounds in pixels: [0,0]-[width,height] More...
 
Area getCleanBounds () const
 the Area defining the Texture's clean pixel bounds in pixels: [0,0]-[width*maxU,height*maxV] More...
 
bool hasAlpha () const
 whether the texture has an alpha channel More...
 
float getLeft () const
 These return the right thing even when the texture coordinate space is flipped. More...
 
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. More...
 
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. More...
 
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 More...
 
GLuint getId () const
 the ID number for the texture, appropriate to pass to calls like glBindTexture() More...
 
GLenum getTarget () const
 the target associated with texture. Typical values are GL_TEXTURE_2D and GL_TEXTURE_RECTANGLE_ARB More...
 
bool isFlipped () const
 whether the texture is flipped vertically More...
 
void setFlipped (bool aFlipped=true)
 Marks the texture as being flipped vertically or not. More...
 
void enableAndBind () const
 Enables the Texture's target and binds its associated texture. Equivalent to calling. More...
 
void disable () const
 Disables the Texture's target. More...
 
void bind (GLuint textureUnit=0) const
 Binds the Texture's texture to its target in the multitexturing unit GL_TEXTURE0 + textureUnit. More...
 
void unbind (GLuint textureUnit=0) const
 Unbinds the Texture currently bound in the Texture's target. More...
 
Texture weakClone () const
 Creates a clone of this texture which does not have ownership, but points to the same resource. More...
 
 operator ImageSourceRef () const
 Returns an ImageSource pointing to this Texture. More...
 

Static Public Member Functions

static TextureRef create (int width, int height, Format format=Format())
 Constructs a Texture of size(width, height) More...
 
static TextureRef create (const unsigned char *data, int dataFormat, int width, int height, Format format=Format())
 Constructs a Texture of size(width, height). 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. **/. More...
 
static TextureRef create (const Surface8u &surface, Format format=Format())
 Constructs a Texture based on the contents of surface. More...
 
static TextureRef create (const Surface32f &surface, Format format=Format())
 Constructs a Texture based on the contents of surface. More...
 
static TextureRef create (const Channel8u &channel, Format format=Format())
 Constructs a Texture based on the contents of channel. More...
 
static TextureRef create (const Channel32f &channel, Format format=Format())
 Constructs a Texture based on the contents of channel. More...
 
static TextureRef create (ImageSourceRef imageSource, Format format=Format())
 Constructs a texture based on imageSource. More...
 
static TextureRef create (GLenum target, GLuint textureId, int width, int height, bool doNotDispose)
 Constructs a Texture based on an externally initialized OpenGL texture. doNotDispose specifies whether the Texture destructor is responsible for disposing of the associated OpenGL resource. More...
 
static Texture loadDds (IStreamRef ddsStream, Format format)
 Creates a new Texture from raw DirectDraw Stream data. More...
 
static void SurfaceChannelOrderToDataFormatAndType (const SurfaceChannelOrder &sco, GLint *dataFormat, GLenum *type)
 Converts a SurfaceChannelOrder into an appropriate OpenGL dataFormat and type. More...
 
static bool dataFormatHasAlpha (GLint dataFormat)
 Returns whether a given OpenGL dataFormat contains an alpha channel. More...
 
static bool dataFormatHasColor (GLint dataFormat)
 Returns whether a give OpenGL dataFormat contains color channels. More...
 

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

std::shared_ptr< ObjmObj
 
typedef std::shared_ptr< Obj >
Texture::* 
unspecified_bool_type
 Emulates shared_ptr-like behavior. More...
 
 operator unspecified_bool_type () const
 Emulates shared_ptr-like behavior. More...
 
void reset ()
 Emulates shared_ptr-like behavior. More...
 

Detailed Description

Represents an OpenGL Texture. Implicitly shared object.

See also
Images in Cinder

Member Typedef Documentation

typedef std::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

static TextureRef cinder::gl::Texture::create ( int  width,
int  height,
Format  format = Format() 
)
static

Constructs a Texture of size(width, height)

static TextureRef cinder::gl::Texture::create ( const unsigned char *  data,
int  dataFormat,
int  width,
int  height,
Format  format = Format() 
)
static

Constructs a Texture of size(width, height). 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. **/.

static TextureRef cinder::gl::Texture::create ( const Surface8u surface,
Format  format = Format() 
)
static

Constructs a Texture based on the contents of surface.

static TextureRef cinder::gl::Texture::create ( const Surface32f surface,
Format  format = Format() 
)
static

Constructs a Texture based on the contents of surface.

static TextureRef cinder::gl::Texture::create ( const Channel8u channel,
Format  format = Format() 
)
static

Constructs a Texture based on the contents of channel.

static TextureRef cinder::gl::Texture::create ( const Channel32f channel,
Format  format = Format() 
)
static

Constructs a Texture based on the contents of channel.

static TextureRef cinder::gl::Texture::create ( ImageSourceRef  imageSource,
Format  format = Format() 
)
static

Constructs a texture based on imageSource.

static TextureRef cinder::gl::Texture::create ( GLenum  target,
GLuint  textureId,
int  width,
int  height,
bool  doNotDispose 
)
static

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

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 Surface32f 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 Channel32f channel)

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

void cinder::gl::Texture::update ( const Channel8u channel,
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

GLint cinder::gl::Texture::getCleanWidth ( ) const

the width of the texture in pixels accounting for its "clean" area -

See also
getCleanBounds()
GLint cinder::gl::Texture::getCleanHeight ( ) const

the height of the texture in pixels accounting for its "clean" area -

See also
getCleanBounds()
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
Rectf cinder::gl::Texture::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 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::getId ( ) 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 ( ) const

Emulates shared_ptr-like behavior.

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

Emulates shared_ptr-like behavior.

Member Data Documentation

std::shared_ptr<Obj> cinder::gl::Texture::mObj
protected

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