- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files
- Directories
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes

# 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:
[legend]

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

Texture Texture Texture Texture Texture Texture Texture Texture Texture Texture
Texture Texture Texture Texture Texture Texture Texture Texture Texture Texture