MTextureManager Class Reference

#include <MTextureManager.h>

Class Description

Public Member Functions

MStatus addImagePath (const MString &path)
 This method adds an additional search path for looking up images on disk. More...
 
MStatus imagePaths (MStringArray &paths) const
 The current set of image search paths can be retrieved using this method. More...
 
MTextureacquireTexture (const MString &filePath, int mipmapLevels=0, bool useExposureControl=true, const MString &layerName=MString(), int alphaChannelIdx=-1)
 obsolete, use the one with contextNodeFullName param More...
 
MTextureacquireTexture (const MTextureArguments &args)
 Ask the renderer to acquire a hardware texture. More...
 
MTextureacquireTexture (const MString &filePath, const MString &contextNodeFullName, int mipmapLevels=0, bool useExposureControl=true, const MString &layerName=MString(), int alphaChannelIdx=-1)
 Ask the renderer to acquire a hardware texture. More...
 
MTextureacquireTexture (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. More...
 
MTextureacquireTexture (const MObject &textureNode, bool allowBackgroundLoad=false)
 Acquire the texture associated with a given texture node. More...
 
MTextureacquireTexture (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. More...
 
MTextureacquireTiledTexture (const MString textureName, const MStringArray &tilePaths, const MFloatArray &tilePositions, const MColor &undefinedColor, unsigned int width, unsigned int height, MStringArray &failedTilePaths, MFloatArray &uvScaleOffset)
 Ask the renderer to acquire a tiled hardware texture. More...
 
MTextureacquireDepthTexture (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. More...
 
MTextureacquireDepthTexture (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. More...
 
void releaseTexture (MTexture *texture) const
 Deletes the MTexture and releases the reference to the underlying texture which is held by the MTexture object. More...
 
MStatus saveTexture (MTexture *texture, const MString &filePath)
 Ask the renderer to save a hardware texture to disk. More...
 
MTexturefindTexture (const MString &textureName)
 Search the texture caching system for a previously cached texture with the given name. More...
 

Static Public Member Functions

static const char * className ()
 Returns the name of this class. More...
 

Member Function Documentation

MStatus addImagePath ( const MString path)

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

Parameters
[in]pathImage search path.
Returns
Status code
Status Codes:
+ Examples:
MStatus imagePaths ( MStringArray paths) const

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

Parameters
[out]pathsA string array to be filled in with image path strings. Each array element will contain one image path string.
Returns
Status code
Status Codes:
MTexture * acquireTexture ( const MString textureName,
int  mipmapLevels = 0,
bool  useExposureControl = true,
const MString layerName = MString(),
int  alphaChannelIdx = -1 
)

obsolete, use the one with contextNodeFullName param

This method is obsolete.

Deprecated:
Context (owner Node full name) must be provided to the Maya resolver. Use the one with the contextNodeFullName input param.

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]textureNameImage file name
[in]mipmapLevelsMipmap 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]useExposureControlUse linear exposure control to convert HDR images
[in]layerNameThe name of the layer to load, this is only relevant for PSD files, otherwise it will have no effect
[in]alphaChannelIdxThe index of the alpha channel to load, this is only relevant for PSD files, otherwise it will have no effect
Returns
MTexture pointer
+ Examples:
MTexture * acquireTexture ( const MTextureArguments args)

Ask the renderer to acquire a hardware texture.

The input data is read from an image file.

To enable texture background loading, set the associated file texture node by calling MTextureArguments::setFileTextureNode().

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]argsThe structure containing the arguments to acquire a texture from disk.
Returns
MTexture pointer
MTexture * acquireTexture ( const MString textureName,
const MString contextNodeFullName,
int  mipmapLevels = 0,
bool  useExposureControl = true,
const MString layerName = MString(),
int  alphaChannelIdx = -1 
)

Ask the renderer to acquire a hardware texture.

The input data is read from an image file. This version of acquireTexture provides context (owner Node full name) to the Maya file resolvers.

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]textureNameImage file name
[in]contextNodeFullNamefull name of the texture owner Node to be provided as a context to the Maya resolver
[in]mipmapLevelsMipmap 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]useExposureControlUse linear exposure control to convert HDR images
[in]layerNameThe name of the layer to load, this is only relevant for PSD files, otherwise it will have no effect
[in]alphaChannelIdxThe index of the alpha channel to load, this is only relevant for PSD files, otherwise it will have no effect
Returns
MTexture pointer
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.

If a plug to a file texture node is provided then the name, width, height and generateMipMaps parameters will be ignored as this information will be based on the image on disk associated with texture node. If uv tiling is enabled, currently only the first tile will be returned.

Otherwise, an attempt to "bake" a texture will be made using the Maya's software renderer "convert-to-solid-texture" functionality.

In this case:

  • 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]textureNameName of the texture to create
[in]plugPlug which is attached with a texture
[in]widthWidth of the texture
[in]heightHeight of the texture
[in]generateMipMapsGenerate the mipmap levels
Returns
MTexture pointer
MTexture * acquireTexture ( const MObject textureNode,
bool  allowBackgroundLoad = false 
)

Acquire the texture associated with a given texture node.

Currently only file texture nodes are supported. If uv tiling is enabled, currently only the first tile will be returned.

Parameters
[in]textureNodeNode to acquire texture from
[in]allowBackgroundLoadAllow for background texture loading. The default value is false.
Returns
Pointer to MTexture if successful. Otherwise a null pointer is returned.
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.

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]textureNameName of the texture to create
[in]textureDescDescription of the texture
[in]pixelDataBlock of system memory data which matches the texture description
[in]generateMipMapsGenerate the mipmap levels
Returns
MTexture pointer
MTexture * acquireTiledTexture ( const MString  textureName,
const MStringArray tilePaths,
const MFloatArray tilePositions,
const MColor undefinedColor,
unsigned int  maxWidth,
unsigned int  maxHeight,
MStringArray failedTilePaths,
MFloatArray uvScaleOffset 
)

Ask the renderer to acquire a tiled hardware texture.

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().

If no pre-existing cached texture exists, then a new texture is created by tiling a set of images on disk. The images are specified by a set of file names and their tile position. The input images must be 2D textures.

The tile position is the lower left coordinate of each tile in UV space. The coordinates are assumed to be in a flat array of floats such that for tile 'n', the coordinate is given by : (tilePositions[n*2], tilePositions[n*2+1]).

Note that the function MRenderUtil::exactFileTextureUvTileData() can be used to retrieve a set of file texture names and positions from a file texture node.

The ordering of the file path names determines the order that tiles are written to the output texture. Tiles written later will overwrite any previously written tiles.

Any region in the output texture which are not covered by a tile will be filled with the specified 'undefined' color. If the image specified by the file name cannot be loaded or if the image does not represent a 2D texture then the 'undefined' color will be written to the output texture.

The maximum dimensions of the output texture are entered as input parameters.

  • These values are used to compute the dimensions of a tile, such that all tiles have identical size and are square. The actual output dimensions are computed as a multiple of the tile dimensions, and the number of tiles in U and V.

  • For example, if the maximum output dimensions provided are {256,256} and there are 5 tiles in U (width) and 6 tiles in V (height), the computed output tile dimensions would be {42,42}, and the computed output dimensions would be {5*42 = 210, 6*42=252}.

  • To help prevent image distortion it is suggested to provide input values which will result in a square output texture, and that the size is an even multiple of the number of tiles in U and V.

A scale and offset is returned which can be used to map a texture coordinate into the uv range of the texture. Any texture coordinate used to look up into this texture should undergo the following transform:

Transformed UV = ( UV + offset ) * scale
Parameters
[in]textureNameName to give to the texture
[in]tilePathsSet of path names to UV tiles
[in]tilePositionsSet of lower left coordinates for each UV tile.
[in]undefinedColorColor to fill tile region with if the image for a given UV tile cannot be acquired.
[in]maxWidthMaximum width of the output texture. The value is clamped to a minimum of 256.
[in]maxHeightMaximum height of the output texture. The value is clamped to a minimum of 256.
[out]failedTilePathsList of files which were not written to the output texture.
[out]uvScaleOffsetTransform to map to the uv range of the output texture. If the acquire is successful then 4 elements will be returned. The first 2 elements represent the scale in U and V, and the latter 2 elements represent the offset in U and V.
Returns
MTexture pointer
+ Examples:
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.

  • 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]textureNameName of the texture to create
[in]imageContains block of system memory data containing depth map information
[in]generateMipMapsGenerate the mipmap levels
[in]normalizationDescOptional information to perform normalization on the depth values. Default value is NULL.
Returns
MTexture pointer
+ Examples:
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.

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]textureNameName of the texture to create
[in]pixelDataContains block of system memory data containing depth information
[in]widthWidth of the texture
[in]heightHeight of the texture
[in]generateMipMapsGenerate the mipmap levels
[in]normalizationDescOptional information to perform normalization on the depth values. Default value is NULL.
Returns
MTexture pointer
MStatus saveTexture ( MTexture texture,
const MString filePath 
)

Ask the renderer to save a hardware texture to disk.

Parameters
[in]textureMTexture pointer
[in]filePathImage file name
Returns
Status code
Status Codes:
+ Examples:
MTexture * findTexture ( const MString textureName)

Search the texture caching system for a previously cached texture with the given name.

The renderer will add one reference to the texture for the returned MTexture instance. To release the reference, call releaseTexture().

Parameters
[in]textureNameName of the texture to search for
Returns
A pointer to the texture if found, NULL otherwise
+ Examples:
const char * className ( )
static

Returns the name of this class.

Returns
Name of this class.

The documentation for this class was generated from the following files:
  • MTextureManager.h
  • MTextureManager.cpp