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