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

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions

# MTextureManager Class Reference
OpenMayaRender - API module for rendering

This reference page is linked to from the following overview topics: Autodesk Maya 2014, Extension for Autodesk Maya 2013, 2.4 Texture creation and texture manager, 3.2 The Renderer, 3.6 Draw Overrides.

Search for all occurrences

## Detailed Description

Class which manages texture.

Examples:

  hwPhongShader.cpp.

`#include <MTextureManager.h>`

List of all members.

## Public Member Functions
MStatus | addImagePath (const MString &path)
| This method adds an additional search path for looking up images on disk.
MStatus | imagePaths (MStringArray &paths) const
| The current set of image search paths can be retrieved using this method.
MTexture * | acquireTexture (const MString &filePath, int mipmapLevels=0, bool useExposureControl=true)
| Ask the renderer to acquire a hardware texture.
MTexture * | acquireTexture (const MString &textureName, const MPlug &plug, int width, int height, bool generateMipMaps=true)
| Sample the shading network connected to a plug to produce a texture.
MTexture * | acquireTexture (const MString &textureName, const MHWRender::MTextureDescription &textureDesc, const void *pixelData, bool generateMipMaps=true)
| Ask the renderer to acquire a hardware texture by providing a texture description and a block of system memory data which matches the texture description.
MTexture * | acquireDepthTexture (const MString &textureName, const MImage &image, bool generateMipMaps, const MDepthNormalizationDescription *normalizationDesc)
| Ask the renderer to acquire a hardware texture from an MImage's depth buffer.
MTexture * | acquireDepthTexture (const MString &textureName, float *pixelData, unsigned int width, unsigned int height, bool generateMipMaps, const MDepthNormalizationDescription *normalizationDesc)
| Ask the renderer to acquire a hardware texture from an array of depth values.
void | releaseTexture (MTexture *texture) const
| Deletes the MTexture and releases the reference to the underlying texture which is held by the MTexture object.
MStatus | saveTexture (MTexture *texture, const MString &filePath)
| Ask the renderer to save a hardware texture to disk.
## Static Public Member Functions
static const char * | className ()
| Returns the name of this class.

## Member Function Documentation

MStatus addImagePath | ( | const MString & | path | ) |

Search for all occurrences

This method adds an additional search path for looking up images on disk.

Parameters:

  [in] | path | Image search path.

Returns:
  Status code

Status Codes:
  - MS::kSuccess The path was added.
  - MS::kFailure The path could not be added.

MStatus imagePaths | ( | MStringArray & | paths | ) | const

Search for all occurrences

The current set of image search paths can be retrieved using this method.

Parameters:

  [out] | paths | A string array to be filled in with image path strings. Each array element will contain one image path string.

Returns:
  Status code

Status Codes:
  - MS::kSuccess The image paths could be retrieved.
  - MS::kFailure The image paths could not be retrieved.

MTexture * acquireTexture | ( | const MString & | textureName,
|  | int | mipmapLevels = `0`,
|  | bool | useExposureControl = `true`
| ) |  |

Search for all occurrences

Ask the renderer to acquire a hardware texture.

The input data is read from an image file.

The renderer will add 1 reference to this texture on creation. If the texture has already been acquired then no new texture will be created, and a new reference will be added. To release the reference, call releaseTexture().

Parameters:

  [in] | textureName | Image file name
  [in] | mipmapLevels | Mipmap generation levels "mipmapLevels==0" == create and populate all possible levels, using file contents if available "mipmapLevels>1" == create the specified number of levels, using file contents if available "mipmapLevels==1" == no mipmap chain
  [in] | useExposureControl | Use linear exposure control to convert HDR images

Returns:
  MTexture pointer

Examples:
  hwPhongShader.cpp.

MTexture * acquireTexture | ( | const MString & | textureName,
|  | const MPlug & | plug,
|  | int | width,
|  | int | height,
|  | bool | generateMipMaps = `true`
| ) |  |

Search for all occurrences

Sample the shading network connected to a plug to produce a texture.

The sample resolution is the specified width and height input parameters.

If the texure name provided is an empty string then the texture will not be cached as part of the internal texture caching system. Thus each such call to this method will create a new texture.

If a non-empty texture name is specified then the caching system will attempt to return any previously cached texture with that name.

The renderer will add 1 reference to this texture on creation. If the texture has already been acquired then no new texture will be created, and a new reference will be added. To release the reference, call releaseTexture().

Parameters:

  [in] | textureName | Name of the texture to create
  [in] | plug | Plug which is attached with a texture
  [in] | width | Width of the texture
  [in] | height | Height of the texture
  [in] | generateMipMaps | Generate the mipmap levels

Returns:
  MTexture pointer

MTexture * acquireTexture | ( | const MString & | textureName,
|  | const MHWRender::MTextureDescription & | textureDesc,
|  | const void * | pixelData,
|  | bool | generateMipMaps = `true`
| ) |  |

Search for all occurrences

Ask the renderer to acquire a hardware texture by providing a texture description and a block of system memory data which matches the texture description.

If the texure name provided is an empty string then the texture will not be cached as part of the internal texture caching system. Thus each such call to this method will create a new texture.

If a non-empty texture name is specified then the caching system will attempt to return any previously cached texture with that name.

The renderer will add 1 reference to the texture for each method call. If the texture resides in the cache then no new texture will be created, but a new reference will still be added. To release the reference, call releaseTexture().

The creation of a new texture involves copying the block of system memory data to a hardware texture. The caller is free to deallocate the system memory as the renderer itself does not keep any references to it.

It is generally faster to update a texture using the update() method on MTexture than to try and discard a previous version, and then acquire a new version.

Parameters:

  [in] | textureName | Name of the texture to create
  [in] | textureDesc | Description of the texture
  [in] | pixelData | Block of system memory data which matches the texture description
  [in] | generateMipMaps | Generate the mipmap levels

Returns:
  MTexture pointer

MTexture * acquireDepthTexture | ( | const MString & | textureName,
|  | const MImage & | image,
|  | bool | generateMipMaps,
|  | const MDepthNormalizationDescription * | normalizationDesc
| ) |  |

Search for all occurrences

Ask the renderer to acquire a hardware texture from an MImage's depth buffer.

- If there is a depth buffer associated with the data in the MImage then a new single channel 32-bit floating point texture will be created.
- If the MImage does not contain a depth buffer then a NULL pointer will be returned.

There is the option to normalize the data to the [0..1] range during creation.

If the texure name provided is an empty string then the texture will not be cached as part of the internal texture caching system. Thus each such call to this method will create a new texture.

If a non-empty texture name is specified then the caching system will attempt to return any previously cached texture with that name.

The renderer will add 1 reference to the texture for each method call. If the texture resides in the cache then no new texture will be created, but a new reference will still be added. To release the reference, call releaseTexture().

The creation of a new texture involves copying the block of system memory data stored in the MImage to a hardware texture. The caller is free to deallocate the system memory as the renderer itself does not keep any references to it.

Parameters:

  [in] | textureName | Name of the texture to create
  [in] | image | Contains block of system memory data containing depth map information
  [in] | generateMipMaps | Generate the mipmap levels
  [in] | normalizationDesc | Optional information to perform normalization on the depth values. Default value is NULL.

Returns:
  MTexture pointer

MTexture * acquireDepthTexture | ( | const MString & | textureName,
|  | float * | pixelData,
|  | unsigned int | width,
|  | unsigned int | height,
|  | bool | generateMipMaps,
|  | const MDepthNormalizationDescription * | normalizationDesc
| ) |  |

Search for all occurrences

Ask the renderer to acquire a hardware texture from an array of depth values.

If sucessful, a new single channel 32-bit floating point texture will be created. There is the option to normalize the data to the [0..1] range during creation.

If the texure name provided is an empty string then the texture will not be cached as part of the internal texture caching system. Thus each such call to this method will create a new texture.

If a non-empty texture name is specified then the caching system will attempt to return any previously cached texture with that name.

The renderer will add 1 reference to the texture for each method call. If the texture resides in the cache then no new texture will be created, but a new reference will still be added. To release the reference, call releaseTexture().

The creation of a new texture involves copying the block of system memory data to a hardware texture. The caller is free to deallocate the system memory as the renderer itself does not keep any references to it.

Parameters:

  [in] | textureName | Name of the texture to create
  [in] | pixelData | Contains block of system memory data containing depth information
  [in] | width | Width of the texture
  [in] | height | Height of the texture
  [in] | generateMipMaps | Generate the mipmap levels
  [in] | normalizationDesc | Optional information to perform normalization on the depth values. Default value is NULL.

Returns:
  MTexture pointer

void releaseTexture | ( | MTexture * | texture | ) | const

Search for all occurrences

Deletes the MTexture and releases the reference to the underlying texture which is held by the MTexture object.

After calling this method it is an error to try to use the MTexture and attempting to do so will result in instability. The underlying texture might not be deleted immediately if it is in use by the renderer.

Parameters:

  [in] | texture | The texture to release

Examples:
  hwPhongShader.cpp.

MStatus saveTexture | ( | MTexture * | texture,
|  | const MString & | filePath
| ) |  |

Search for all occurrences

Ask the renderer to save a hardware texture to disk.

Parameters:

  [in] | texture | MTexture pointer
  [in] | filePath | Image file name

Returns:
  Status code

Status Codes:
  - MS::kSuccess The texture was successfuly saved to disk.
  - MS::kFailure The texture was could not be saved.

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  Name of this class.

MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager
MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager MTextureManager