#include <material.h>

Class 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 716 of file material.h.

Inheritance diagram for Texture:

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. More...

virtual void	Create (unsigned int iWidth, unsigned int iHeight, unsigned int iChannelCount, enum Image::Format eFormat)
	Create/allocate the content of the texture. More...

virtual bool	CreateFromFile (const QString &sFileName, unsigned int iChannelCount=0, enum Image::Format eFormat=Image::eUnknown)
	Create the texture from an image file. More...

virtual const Image *	AsImage (void)
	Returns the content as an image. More...

virtual void	CopyTo (Texture &cTexture) const
	Copy the content of the texture into another one, using the current opengl pipeline settings. More...

virtual unsigned int	Width (void) const
	Returns the width of the texture in pixels. More...

virtual unsigned int	Height (void) const
	Returns the height of the texture in pixels. More...

virtual unsigned int	BitDepth (void) const
	Returns the bit depth of the texture (per channel) More...

virtual enum Image::Format	Format (void) const
	Returns the format of the texture. More...

virtual unsigned int	ChannelCount (void) const
	Returns the number of channels. More...

virtual bool	Activate (void) const
	Binds the texture node. More...

virtual bool	Deactivate (void) const
	UnBinds the texture node, but does not restore the previous active texture. More...

virtual unsigned int	OpenGLName (void) const
	Returns the opengl name of the texture. More...

virtual bool	SetAsRenderTarget (void)
	Sets the texture as a render target. Subsequent renderings will render into that texture. More...

virtual bool	RestoreRenderTarget (void)
	Restore previous render target. More...

virtual abool *	getFilteringPref ()

virtual void	CopyFrom (Image pImage, const ImgTile pRegion=0)
	Create the texture content from an image. More...

virtual void	ReplaceWith (Image pImage, const ImgTile pRegion=0)
	Replace the texture with the content from an image. More...

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. More...

virtual void	SetLocation (unsigned int iLocation)
	Sets the location for the texture pool. More...

virtual unsigned int	Location (void) const
	Gets the location for the texture pool. More...

virtual int64	TotalMemoryUsage (void) const
	Return the memory usage of all texture instances of the class in bytes. More...

virtual qint64	VideoMemoryUsage (float fTCGrad=-1.0f) const
	Returns the GPU memory usage in bytes. More...

virtual void	SetLive (bool bLive)
	For internal use only. More...

virtual bool	IsLive (void) const
	For internal use only. More...

virtual void	SetFiltered (bool bFiltered)
	Set the texture filtering on this texture. More...

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. More...

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... More...

virtual void	SyncContent ()
	Syncronize texture in video memory with texture in system memory. More...

virtual unsigned char	getProxyLevel () const
	get the proxy level – 0 == no proxy, 1 == 0.5x, 2 = 0.25x, 3 = 0.125 etc... More...

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. More...

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. More...

virtual bool	IsDirty (void) const
	Returns if the texture is modified since last load/save. More...

virtual void	SetDirty (bool bDirty)
	Returns if the texture is modified since last load/save. More...

Undo Mechanism
These methods provide a multi-level undo and redo system for textures.
virtual bool	NewVersion ()
	Caches a copy of the current texture. More...

virtual bool	PrevVersion ()
	Makes the previous version of the texture current. More...

virtual bool	NextVersion ()
	Makes the 'next' version of the texture current. More...

virtual int	NumVersions ()
	Returns the number of versions of this texture. More...

virtual bool	MergeOldestVersions ()
	Merges the oldest two versions of this texture. More...

virtual bool	PurgeNewerVersions ()
	Purges any versions of this texture after the current one (i.e. More...

virtual bool	PurgeAllButCurrentVersion ()
	Purges all but the current version of this Texture. More...

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

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

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. More...

virtual void	AddDirtyPixel (int x, int y)
	Notifies the texture that part of it has changed. More...

virtual void	AddDirtyTile (const ImgTile &t)
	Notifies the texture that part of it has changed. More...

ImgTile	DirtyTile () const
	Returns the dirty rectangle of the texture. Deprecated. More...

ImgDirtyRegion *	DirtyRegion ()
	returns the dirty region. More...

Public Member Functions inherited from Node
	Node (const QString &sStringID="", const QString &sDisplayName="")
	Standard constructor. More...

virtual	~Node (void)

virtual void	Initialize (void)

void	LoadTemplate (const QString &sFileName="", bool bStartEvent=false)
	Use an external XML file to initialize the attributes. More...

void	SaveTemplate (const QString &sFileName="", bool bSaveOnlyVisible=false)
	Save current attributes as an XML template. More...

unsigned int	Version (void) const
	Returns the current version of the node. This number increases when the content of the node changed (when ContentChanged() called). More...

void	SetVersion (unsigned int iVersion)
	Sets the current version number for the node. More...

unsigned int	ReferenceCount (void) const
	Returns the number of pointers referencing this node. More...

Attribute *	ReferencePointer (unsigned int iIndex) const
	Returns the address of an attribute which refers to this node. The type of the attribute is always aptr. More...

Node *	ReferenceNode (unsigned int iIndex) const
	Returns the address of a node referencing this node. More...

virtual QString	Name (const ClassDesc *pClass=0) const
	Deprecated. More...

virtual void	SetName (const QString &sName)
	Deprecated. More...

virtual QString	StringID (const ClassDesc *pClass=0) const
	Returns the string id of the node. More...

virtual void	SetStringID (const QString &sStringID)
	Sets the string id of the node. More...

virtual QString	DisplayName (void) const
	Returns the display name of the node. More...

virtual void	SetDisplayName (const QString &sDisplayName)
	Sets the display name of the node. More...

virtual QString	HelpID (void) const
	Returns the help entry id of the node. Can be overwritten in derived classes. More...

virtual void	SetHelpID (const QString &sHelpID)
	Sets the help entry id of the node. More...

void	Annex (Node *pSource, const QString &sCategory="")
	Relink all the attributes of the source node to this one. More...

virtual void	Serialize (Stream &s)
	Serializes the node. More...

bool	IsKindOf (const ClassDesc *pClass) const
	Returns true if this node is derived from the pClass class. More...

void	ContentChanged (void) const
	This function must be called if the content of the node is changed. More...

virtual void	CheckValidity (DiagnosticLevel iLevel=dgnLevel2) const
	Checks the validity of this node. More...

virtual void	CopyTo (Node *pNode) const

virtual Node *	Duplicate (void) const

virtual void	OnNodeEvent (const Attribute &cAttribute, NodeEventType cType)
	This function is called if an event occurs with any of the attributes of the node. More...

virtual void	OnEvent (const EventGate &cEvent)
	This function is called when a generic event occurs. See EventGate class. More...

void	RequestDeferredEvent (Attribute &cAttribute)
	Request for a deferred event, which will occur only in the main loop. More...

unsigned int	AttributeCount (void) const
	Returns the number of attributes owned by the node. More...

Attribute *	AttributeByIndex (int iIndex) const
	Returns a specified attribute (or 0 if iIndex is greater than the number of attributes). More...

Attribute *	AttributeByName (const QString &sName) const
	Returns a specified attribute by its name. Returns 0 if the attribute not found. More...

Attribute *	AttributeByID (const QString &sID) const
	Returns a specified attribute by its ID. Returns 0 if the attribute not found. More...

void	SetAttributeValue (const QString &sAttributeID, const QString &sNewValue)
	Set the value of an attribute from a string. More...

QString	AttributeValue (const QString &sAttributeID) const
	Returns the current value of an attribute as a string. More...

void	LogAttributes (void) const
	Write all attributes into the log file. More...

virtual QWidget *	CreatePropertiesWindow (QWidget *pParent)
	Create a window which displays the attributes of the node. Can be overriden to provide a custom interface. More...

Attribute *	AddAttribute (Attribute::AttributeType type, const QString &id)
	Allows SDK users to add attributes at runtime. More...

Node *	Next (void) const
	Returns the next node in the chain. Used to enumerate the current nodes. See also First(). More...

int	ID (void) const
	Returns an ID for the node. The ID is unique in the whole application life. More...

bool	SetID (int iID)
	Set ID for the node. More...

Static Public Member Functions
static unsigned int	BitDepth (enum Image::Format eFormat)
	Returns the bit depth for the specified format (per channel) More...

static unsigned char	ProxyLevel (float fTCGrad, unsigned int iTextureSize)
	Computes the proxy level for the given TC gradient and texture size. More...

Static Public Member Functions inherited from Node
static void	StartHashing ()
	This is called once in main once static ctors are done. More...

static Node *	First (void)
	This function will return the first node in the memory. Used to enumerate all the current nodes. See also Next(). More...

static Node *	ByID (int iID)
	Returns the node with the specified ID, or zero if such a node does not exists. More...

static Node *	ByName (const QString &sClass, const QString &sName)
	Search for a node with the name sName. More...

Protected Member Functions
	Texture (void)
	Constructor. More...

Protected Attributes
ImgDirtyRegion	m_DirtyRegion

Additional Inherited Members
Public Types inherited from Node
enum	DiagnosticLevel { dgnLevel1, dgnLevel2, dgnLevel3 }
	Indicates the level of validity checking that is performed in CheckValidity() More...

Public Attributes inherited from Node
AttributeThisPointer	m_pThis

	DECLARE_CLASS

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

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

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

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

Returns the content as an image.

virtual void CopyTo ( Texture & cTexture ) const

virtual

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

Returns the width of the texture in pixels.

Examples:: SampleViewportFilter/SampleViewportFilter.cpp.

virtual unsigned int Height ( void ) const

virtual

Returns the height of the texture in pixels.

Examples:: SampleViewportFilter/SampleViewportFilter.cpp.

virtual unsigned int BitDepth ( void ) const

virtual

Returns the bit depth of the texture (per channel)

static unsigned int BitDepth ( enum Image::Format eFormat )

static

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

virtual enum Image::Format Format ( void ) const

virtual

Returns the format of the texture.

virtual unsigned int ChannelCount ( void ) const

virtual

Returns the number of channels.

virtual bool Activate ( void ) const

virtual

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

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

Returns the opengl name of the texture.

Examples:: SampleViewportFilter/SampleViewportFilter.cpp.

virtual bool SetAsRenderTarget ( void )

virtual

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

Examples:: SampleViewportFilter/SampleViewportFilter.cpp.

virtual bool RestoreRenderTarget ( void )

virtual

Restore previous render target.

Examples:: SampleViewportFilter/SampleViewportFilter.cpp.

virtual abool* getFilteringPref ( )

virtual

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

virtual

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

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

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

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

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

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

virtual qint64 VideoMemoryUsage ( float fTCGrad = -1.0f ) const

virtual

Returns the GPU memory usage in bytes.

virtual void SetLive ( bool bLive )

virtual

For internal use only.

virtual bool IsLive ( void ) const

virtual

For internal use only.

virtual bool NewVersion ( )

virtual

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

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

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

Returns the number of versions of this texture.

Returns 1 for unversioned textures.

virtual bool MergeOldestVersions ( )

virtual

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

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

Purges all but the current version of this Texture.

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

virtual bool BeginUndoableOperation ( )

virtual

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

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

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

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

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

Syncronize texture in video memory with texture in system memory.

virtual unsigned char getProxyLevel ( ) const

virtual

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

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

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

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

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

virtual void SetDirty ( bool bDirty )

virtual

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

void ResetDirtyTile ( )

inline

Resets the dirty region to be empty.

Definition at line 998 of file material.h.

         {
             m_DirtyRegion.ClearDirtyRegion();       
         }

virtual void AddDirtyPixel	(	int	x,
		int	y
	)

inlinevirtual

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 1010 of file material.h.

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

virtual void AddDirtyTile ( const ImgTile & t )

inlinevirtual

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 1023 of file material.h.

         {
             m_DirtyRegion.AddToDirtyRegion(t);
         }

ImgTile DirtyTile ( ) const

inline

Returns the dirty rectangle of the texture. Deprecated.

Definition at line 1032 of file material.h.

1032 { return m_DirtyRegion.GetTotalBounds(); }

mudbox::ImgDirtyRegion::GetTotalBounds

ImgTile GetTotalBounds() const

return the total bounds of the dirty region as one rectangle.

Definition: image.h:1144

mudbox::Texture::m_DirtyRegion

ImgDirtyRegion m_DirtyRegion

Definition: material.h:979

ImgDirtyRegion* DirtyRegion ( )

inline

returns the dirty region.

Definition at line 1035 of file material.h.

1035 { return &m_DirtyRegion; }

mudbox::Texture::m_DirtyRegion

ImgDirtyRegion m_DirtyRegion

Definition: material.h:979

Member Data Documentation

ImgDirtyRegion m_DirtyRegion

protected

Definition at line 979 of file material.h.

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

Mudbox/material.h

Texture Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation