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.

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