Texture Class Reference

This reference page is linked to from the following overview topics: Mudbox 2013, Textures, Sampling Texture Values, Render to Texture and Multi-Target Rendering.

---

Search for all occurrences

---

Detailed Description

Represents a texture tile inside a texture pool.

Textures are like images (see the Image class) in that they are a 2d array of pixel values. Like images, Textures support many formats. Textures can also be used internally as the target of OpenGL rendering operations -- that is, Mudbox scenes can be rendered into Textures. Textures have the ability to keep old versions of themselves around for undo/redo purposes.

Examples:

SampleViewportFilter/SampleViewportFilter.cpp, SampleViewportFilter/SampleViewportFilter.h, and TextureSwapperViewportFilter/TextureSwapperViewportFilter.h.

Definition at line 707 of file material.h.

#include <material.h>

Inheritance diagram for Texture:

List of all members.

Public Member Functions
virtual void	Create (unsigned int iWidth, unsigned int iHeight, unsigned int iChannelCount, enum Image::Format eFormat, const Color &cColor)
	Create/allocate the content of the texture.
virtual void	Create (unsigned int iWidth, unsigned int iHeight, unsigned int iChannelCount, enum Image::Format eFormat)
	Create/allocate the content of the texture.
virtual bool	CreateFromFile (const QString &sFileName, unsigned int iChannelCount=0, enum Image::Format eFormat=Image::eUnknown)
	Create the texture from an image file.
virtual const Image *	AsImage (void)
	Returns the content as an image.
virtual void	CopyTo (Texture &cTexture) const
	Copy the content of the texture into another one, using the current opengl pipeline settings.
virtual unsigned int	Width (void) const
	Returns the width of the texture in pixels.
virtual unsigned int	Height (void) const
	Returns the height of the texture in pixels.
virtual unsigned int	BitDepth (void) const
	Returns the bit depth of the texture (per channel)
virtual enum Image::Format	Format (void) const
	Returns the format of the texture.
virtual unsigned int	ChannelCount (void) const
	Returns the number of channels.
virtual bool	Activate (void) const
	Binds the texture node.
virtual bool	Deactivate (void) const
	UnBinds the texture node, but does not restore the previous active texture.
virtual unsigned int	OpenGLName (void) const
	Returns the opengl name of the texture.
virtual bool	SetAsRenderTarget (void)
	Sets the texture as a render target. Subsequent renderings will render into that texture.
virtual bool	RestoreRenderTarget (void)
	Restore previous render target.
virtual abool *	getFilteringPref ()
virtual void	CopyFrom (Image *pImage, const ImgTile *pRegion=0)
	Create the texture content from an image.
virtual void	ReplaceWith (Image *pImage, const ImgTile *pRegion=0)
	Replace the texture with the content from an image.
virtual void	CopyTo (Image *pImage, bool tiled=true, const ImgTile *region=0, ImageDescriptor::MemoryChannelOrder eOrder=ImageDescriptor::orderRGBA)
	Copy the texture or a region thereof to an image.
virtual void	SetLocation (unsigned int iLocation)
	Sets the location for the texture pool.
virtual unsigned int	Location (void) const
	Gets the location for the texture pool.
virtual int64	TotalMemoryUsage (void) const
	Return the memory usage of all texture instances of the class in bytes.
virtual qint64	VideoMemoryUsage (float fTCGrad=-1.0f) const
	Returns the GPU memory usage in bytes.
virtual void	SetLive (bool bLive)
	For internal use only.
virtual bool	IsLive (void) const
	For internal use only.
virtual void	SetFiltered (bool bFiltered)
	Set the texture filtering on this texture.
virtual void	SetConvert32To16bitFloat (bool bConvert)
	Set to true to automatically convert 32 bit floating point textures to 16 bit floating point textures on the gpu.
virtual bool	setProxyLevel (unsigned char level, bool bLazySet=false)
	Set the proxy level -- 0 == no proxy, 1 == 0.5x, 2 = 0.25x, 3 = 0.125 etc...
virtual void	SyncContent ()
	Syncronize texture in video memory with texture in system memory.
virtual unsigned char	getProxyLevel () const
	get the proxy level -- 0 == no proxy, 1 == 0.5x, 2 = 0.25x, 3 = 0.125 etc...
virtual void	Composite (const Texture *pTex, ImgDirtyRegion *pRegion=0, unsigned int iBlendMode=0, const Store< float > *aBlendParameters=0)
	Composites the given texture over this texture, and stores the final result into this texture.
virtual void	CopyGLTextureToImage (Image *pImage, bool tiled=true, const ImgTile *region=0, ImageDescriptor::MemoryChannelOrder eOrder=ImageDescriptor::orderRGBA) const
	Avoid using this function unless you know exactly what you are doing.
virtual bool	IsDirty (void) const
	Returns if the texture is modified since last load/save.
virtual void	SetDirty (bool bDirty)
	Returns if the texture is modified since last load/save.
Undo Mechanism
These methods provide a multi-level undo and redo system for textures.
virtual bool	NewVersion ()
	Caches a copy of the current texture.
virtual bool	PrevVersion ()
	Makes the previous version of the texture current.
virtual bool	NextVersion ()
	Makes the 'next' version of the texture current.
virtual int	NumVersions ()
	Returns the number of versions of this texture.
virtual bool	MergeOldestVersions ()
	Merges the oldest two versions of this texture.
virtual bool	PurgeNewerVersions ()
	Purges any versions of this texture after the current one (i.e.
virtual bool	PurgeAllButCurrentVersion ()
	Purges all but the current version of this Texture.
virtual bool	BeginUndoableOperation ()
	Notifies the texture that you are about to start making undoable changes to it (such as a brush stroke).
virtual bool	EndUndoableOperation ()
	Notifies the texture that you have finished making undoable changes to it (such as a brush stroke).
Dirty Region Methods
The dirty tile methods are used by the undo mechanism so that it only has to save those portions of the texture that has been modified.
void	ResetDirtyTile ()
	Resets the dirty region to be empty.
virtual void	AddDirtyPixel (int x, int y)
	Notifies the texture that part of it has changed.
virtual void	AddDirtyTile (const ImgTile &t)
	Notifies the texture that part of it has changed.
ImgTile	DirtyTile () const
	Returns the dirty rectangle of the texture. Deprecated.
ImgDirtyRegion *	DirtyRegion ()
	returns the dirty region.
Static Public Member Functions
static unsigned int	BitDepth (enum Image::Format eFormat)
	Returns the bit depth for the specified format (per channel)
static unsigned char	ProxyLevel (float fTCGrad, unsigned int iTextureSize)
	Computes the proxy level for the given TC gradient and texture size.
Protected Member Functions
	Texture (void)
	Constructor.
Protected Attributes
ImgDirtyRegion	m_DirtyRegion

---

Constructor & Destructor Documentation

Texture

(

void

)

[protected]

Constructor.

Do not use it directly; Use CreateInstance() instead.

        Texture *myTexture = CreateInstance<Texture>();

---

Member Function Documentation

virtual void Create	(	unsigned int	iWidth,
		unsigned int	iHeight,
		unsigned int	iChannelCount,
		enum Image::Format	eFormat,
		const Color &	cColor
	)		[virtual]

Search for all occurrences

Create/allocate the content of the texture.

Parameters:

[in]	iWidth	The width
[in]	iHeight	The height
[in]	iChannelCount	The number of channels (for example, RGBA would be 4)
[in]	eFormat	The image format (see the Image class for details)
[in]	cColor	The initial color that the texture should be set to

virtual void Create	(	unsigned int	iWidth,
		unsigned int	iHeight,
		unsigned int	iChannelCount,
		enum Image::Format	eFormat
	)		[virtual]

Search for all occurrences

Create/allocate the content of the texture.

Parameters:

[in]	iWidth	The width
[in]	iHeight	The height
[in]	iChannelCount	The number of channels (for example, RGBA would be 4)
[in]	eFormat	The image format (see the Image class for details)

virtual bool CreateFromFile	(	const QString &	sFileName,
		unsigned int	iChannelCount = 0,
		enum Image::Format	eFormat = Image::eUnknown
	)		[virtual]

Search for all occurrences

Create the texture from an image file.

Parameters:

[in]	sFileName	The name of the image file to be read in
[in]	iChannelCount	The channel count to coerce this texture into. By default, the channel count of the image specified by sFileName will be used.
[in]	eFormat	The format to coerce this texture into. By default the format of the image specified by sFileName will be used.

virtual const Image* AsImage

(

void

)

[virtual]

Search for all occurrences

Returns the content as an image.

virtual void CopyTo

(

Texture &

cTexture

)

const [virtual]

Search for all occurrences

Copy the content of the texture into another one, using the current opengl pipeline settings.

Parameters:

[in]

cTexture

The texture to be copied to

virtual unsigned int Width

(

void

)

const [virtual]

Search for all occurrences

Returns the width of the texture in pixels.

Examples:

SampleViewportFilter/SampleViewportFilter.cpp.

virtual unsigned int Height

(

void

)

const [virtual]

Search for all occurrences

Returns the height of the texture in pixels.

Examples:

SampleViewportFilter/SampleViewportFilter.cpp.

virtual unsigned int BitDepth

(

void

)

const [virtual]

Search for all occurrences

Returns the bit depth of the texture (per channel)

static unsigned int BitDepth

(

enum Image::Format

eFormat

)

[static]

Search for all occurrences

Returns the bit depth for the specified format (per channel)

virtual enum Image::Format Format

(

void

)

const [virtual]

Search for all occurrences

Returns the format of the texture.

virtual unsigned int ChannelCount

(

void

)

const [virtual]

Search for all occurrences

Returns the number of channels.

virtual bool Activate

(

void

)

const [virtual]

Search for all occurrences

Binds the texture node.

This call makes the texture active, so that opengl operations will be able to use it. It calls glBindTexture() internally.

virtual bool Deactivate

(

void

)

const [virtual]

Search for all occurrences

UnBinds the texture node, but does not restore the previous active texture.

The active opengl texture after this call is undefined.

virtual unsigned int OpenGLName

(

void

)

const [virtual]

Search for all occurrences

Returns the opengl name of the texture.

Examples:

SampleViewportFilter/SampleViewportFilter.cpp.

virtual bool SetAsRenderTarget

(

void

)

[virtual]

Search for all occurrences

Sets the texture as a render target. Subsequent renderings will render into that texture.

Examples:

SampleViewportFilter/SampleViewportFilter.cpp.

virtual bool RestoreRenderTarget

(

void

)

[virtual]

Search for all occurrences

Restore previous render target.

Examples:

SampleViewportFilter/SampleViewportFilter.cpp.

virtual abool* getFilteringPref

(

)

[virtual]

Search for all occurrences

virtual void CopyFrom	(	Image *	pImage,
		const ImgTile *	pRegion = 0
	)		[virtual]

Search for all occurrences

Create the texture content from an image.

Parameters:

[in]	pImage	the Image to copy the texture from
[in]	pRegion	the region of pImage to copy into the texture. By default the whole image is copied.

virtual void ReplaceWith	(	Image *	pImage,
		const ImgTile *	pRegion = 0
	)		[virtual]

Search for all occurrences

Replace the texture with the content from an image.

Parameters:

[in]	pImage	the Image to copy the texture from
[in]	pRegion	the region of pImage to copy, by default the whole image is used

virtual void CopyTo	(	Image *	pImage,
		bool	tiled = true,
		const ImgTile *	region = 0,
		ImageDescriptor::MemoryChannelOrder	eOrder = ImageDescriptor::orderRGBA
	)		[virtual]

Search for all occurrences

Copy the texture or a region thereof to an image.

If region == 0, it copies the entire texture

Parameters:

[in]	pImage	A pointer to the image target
[in]	tiled	Set to true if this is a tiled image
[in]	region	Specifies a region to copy (see the ImgTile class)
[in]	eOrder	Specify what order you want the color channels stored

virtual void SetLocation

(

unsigned int

iLocation

)

[virtual]

Search for all occurrences

Sets the location for the texture pool.

Parameters:

[in]

iLocation

Location can be one of TexturePool::locationGPU, TexturePool::locationCPU, or TexturePool::locationDisk

virtual unsigned int Location

(

void

)

const [virtual]

Search for all occurrences

Gets the location for the texture pool.

Possible values are TexturePool::locationUnknown, TexturePool::locationGPU, TexturePool::locationCPU, or TexturePool::locationDisk

virtual int64 TotalMemoryUsage

(

void

)

const [virtual]

Search for all occurrences

Return the memory usage of all texture instances of the class in bytes.

virtual qint64 VideoMemoryUsage

(

float

fTCGrad = -1.0f

)

const [virtual]

Search for all occurrences

Returns the GPU memory usage in bytes.

virtual void SetLive

(

bool

bLive

)

[virtual]

Search for all occurrences

For internal use only.

virtual bool IsLive

(

void

)

const [virtual]

Search for all occurrences

For internal use only.

virtual bool NewVersion

(

)

[virtual]

Search for all occurrences

Caches a copy of the current texture.

Returns true if successful.

This is part of a Texture's built-in undo mechanism. Effectively, the current version of the texture becomes the previous version, and a fresh copy is now the current version. Any 'next' versions are purged.

virtual bool PrevVersion

(

)

[virtual]

Search for all occurrences

Makes the previous version of the texture current.

Returns true if successful.

This is part of a Texture's built-in undo mechanism. The current version of the texture becomes the next version, and the previous version becomes the current version.

virtual bool NextVersion

(

)

[virtual]

Search for all occurrences

Makes the 'next' version of the texture current.

Returns true if successful.

This is part of a Texture's built-in undo mechanism. The current version of the texture becomes the previous version, and the next version becomes the current version.

virtual int NumVersions

(

)

[virtual]

Search for all occurrences

Returns the number of versions of this texture.

Returns 1 for unversioned textures.

virtual bool MergeOldestVersions

(

)

[virtual]

Search for all occurrences

Merges the oldest two versions of this texture.

Returns true if successful.

This is used to limit the number of items on the undo queue.

virtual bool PurgeNewerVersions

(

)

[virtual]

Search for all occurrences

Purges any versions of this texture after the current one (i.e.

all "next" versions). Returns true if successful.

Creating a new version will implicitly purge newer versions, but if another operation takes place that puts a new item on the undo queue, this should be called to purge newer versions of this texture.

virtual bool PurgeAllButCurrentVersion

(

)

[virtual]

Search for all occurrences

Purges all but the current version of this Texture.

Used to flush the undo queue. Returns true if successful.

virtual bool BeginUndoableOperation

(

)

[virtual]

Search for all occurrences

Notifies the texture that you are about to start making undoable changes to it (such as a brush stroke).

Returns true if successful.

This method calls NewVersion() internally.

virtual bool EndUndoableOperation

(

)

[virtual]

Search for all occurrences

Notifies the texture that you have finished making undoable changes to it (such as a brush stroke).

Returns true if successful.

virtual void SetFiltered

(

bool

bFiltered

)

[virtual]

Search for all occurrences

Set the texture filtering on this texture.

Parameters:

[in]

bFiltered

true to turn filtering on, false to turn filtering off.

virtual void SetConvert32To16bitFloat

(

bool

bConvert

)

[virtual]

Search for all occurrences

Set to true to automatically convert 32 bit floating point textures to 16 bit floating point textures on the gpu.

Parameters:

[in]

bConvert

true to convert, false to leave 32 bit float textures as is.

virtual bool setProxyLevel	(	unsigned char	level,
		bool	bLazySet = false
	)		[virtual]

Search for all occurrences

Set the proxy level -- 0 == no proxy, 1 == 0.5x, 2 = 0.25x, 3 = 0.125 etc...

Setting the proxy level can take a long time. Using the bLazySet parameter the caller can set the proxy level incrementally.

If bLazySet is false, the method always returns true. If bLazySet is true this method returns true when it has completed, otherwise it returns false.

Parameters:

[in]	level	The desired proxy level
[in]	bLazySet	set to false to update immediately, true to set incrementally

virtual void SyncContent

(

)

[virtual]

Search for all occurrences

Syncronize texture in video memory with texture in system memory.

virtual unsigned char getProxyLevel

(

)

const [virtual]

Search for all occurrences

get the proxy level -- 0 == no proxy, 1 == 0.5x, 2 = 0.25x, 3 = 0.125 etc...

virtual void Composite	(	const Texture *	pTex,
		ImgDirtyRegion *	pRegion = 0,
		unsigned int	iBlendMode = 0,
		const Store< float > *	aBlendParameters = 0
	)		[virtual]

Search for all occurrences

Composites the given texture over this texture, and stores the final result into this texture.

This can be used to modify parts of this texture in a paint stroke for example.

Parameters:

[in]	pTex	The source texture to composite over top of this texture
[in]	pRegion	The region of the source texture to composite, if none is specified, the entire image is used.
[in]	iBlendMode	The blend mode to use for compositing
[in]	aBlendParameters	Parameters for the blend mode.

static unsigned char ProxyLevel	(	float	fTCGrad,
		unsigned int	iTextureSize
	)		[static]

Search for all occurrences

Computes the proxy level for the given TC gradient and texture size.

The gradient indicates how quickly the texture is changing in screen space. Smaller gradients indicate the texture is closer to the camera and therefore results in lower (higher resolution) proxy levels being returned from this method. Larger gradients indicate the texture is further from the camera and therefore results in higher (lower resolution) proxy levels being returned from this method. Values from the Cg funtions ddy and ddx can be used directly for the gradient value.

Parameters:

[in]	fTCGrad	The texture coordinate gradient value
[in]	iTextureSize	The texture size, in pixels

virtual void CopyGLTextureToImage	(	Image *	pImage,
		bool	tiled = true,
		const ImgTile *	region = 0,
		ImageDescriptor::MemoryChannelOrder	eOrder = ImageDescriptor::orderRGBA
	)		const [virtual]

Search for all occurrences

Avoid using this function unless you know exactly what you are doing.

It can copy an out of date version of the texture or a reduced resolution version. Use AsImage or CopyTo to get the current and full size version of the texture into an image.

Parameters:

[in]	pImage	A pointer to the image target
[in]	tiled	Set to true if this is a tiled image
[in]	region	Specifies a region to copy (see the ImgTile class)
[in]	eOrder	Specify what order you want the color channels stored

virtual bool IsDirty

(

void

)

const [virtual]

Search for all occurrences

Returns if the texture is modified since last load/save.

virtual void SetDirty

(

bool

bDirty

)

[virtual]

Search for all occurrences

Returns if the texture is modified since last load/save.

void ResetDirtyTile

(

)

[inline]

Search for all occurrences

Resets the dirty region to be empty.

Definition at line 989 of file material.h.

        {
            m_DirtyRegion.ClearDirtyRegion();       
        }

virtual void AddDirtyPixel	(	int	x,
		int	y
	)		[inline, virtual]

Search for all occurrences

Notifies the texture that part of it has changed.

Call this when you are modifying a texture, to indicate what part has changed. Note: do not use this method if you are modifying a rectangle, by passing in the two corners. It will only mark those pixels dirty, and not any others. instead use AddDirtyTile

Parameters:

[in]	x	The X coordinate of the changed pixel
[in]	y	The Y coordinate of the changed pixel

Definition at line 1001 of file material.h.

        {
            m_DirtyRegion.AddToDirtyRegion(ImgTile(x, y, 1, 1));
        }

virtual void AddDirtyTile

(

const ImgTile &

t

)

[inline, virtual]

Search for all occurrences

Notifies the texture that part of it has changed.

This is used by the undo mechanism so that it only has to save those portions of the image that have been modified. Call this when you are modifying a texture.

Parameters:

[in]

t

The X coordinate of the changed pixel

Definition at line 1014 of file material.h.

        {
            m_DirtyRegion.AddToDirtyRegion(t);
        }

ImgTile DirtyTile

(

)

const [inline]

Search for all occurrences

Returns the dirty rectangle of the texture. Deprecated.

Definition at line 1023 of file material.h.

{ return m_DirtyRegion.GetTotalBounds(); }

ImgDirtyRegion* DirtyRegion

(

)

[inline]

Search for all occurrences

returns the dirty region.

Definition at line 1026 of file material.h.

{ return &m_DirtyRegion; }

---

Member Data Documentation

ImgDirtyRegion m_DirtyRegion [protected]

Search for all occurrences

Definition at line 970 of file material.h.

---

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

• Mudbox/material.h