Class which manages texture. More...

#include <MTextureManager.h>

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

MTexture *	acquireTexture (const MString &filePath, int mipmapLevels=0, bool useExposureControl=true, const MString &layerName=MString(), int alphaChannelIdx=-1)
	Deprecated in 2019.0 More...

MTexture *	acquireTexture (const MTextureArguments &args)
	Ask the renderer to acquire a hardware texture. More...

MTexture *	acquireTexture (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...

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

MTexture *	acquireTexture (const MObject &textureNode, bool allowBackgroundLoad=false)
	Acquire the texture associated with a given texture node. More...

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

MTexture *	acquireTiledTexture (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...

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

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

MTexture *	findTexture (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...

Detailed Description

Class which manages texture.

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, blast2Cmd/blast2Cmd.cpp, cgFx/cgfxShaderNode.cpp, customTextureShader/customTextureShaderOverride.cpp, dx11Shader/dx11Shader.cpp, fileTexture/fileTexture.cpp, glslShader/GLSLShader.cpp, hlslShader/hlslShader.cpp, hwApiTextureTest/hwApiTextureTest.cpp, hwApiTextureTest/hwRendererHelper.cpp, simpleNoiseShader/simpleNoiseShaderOverride.cpp, tessellatedQuad/TessellatedQuadGeomOverride.cpp, viewDX11DeviceAccess/viewDX11DeviceAccess.cpp, viewImageBlitOverride/viewImageBlitOverride.cpp, viewImageBlitOverride/viewImageBlitOverride.h, viewOverrideTrackTexture/viewOverrideTrackTexture.cpp, viewRenderOverride/viewRenderOverrideOperations.cpp, viewRenderOverrideFrameCache/viewRenderOverrideFrameCache.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, viewRenderOverrideShadows/viewRenderOverrideShadows.cpp, and viewRenderOverrideTargets/viewRenderOverrideTargets.cpp.

Member Function Documentation

MStatus addImagePath ( const MString & path )

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.

Examples:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and viewDX11DeviceAccess/viewDX11DeviceAccess.cpp.

MStatus imagePaths ( MStringArray & paths ) const

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`,
		const MString &	layerName = `MString()`,
		int	alphaChannelIdx = `-1`
	)

Deprecated in 2019.0

Ask the renderer to acquire a hardware texture.

Deprecated:: Use the one with the contextNodeFullName input parameter instead.

2019.0:: Deprecated in this version.

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!=1" == create and populate all possible levels, using file contents if available "mipmapLevels==1" == no mipmap chain
[in]	useExposureControl	Use linear exposure control to convert HDR images
[in]	layerName	The name of the layer to load, this is only relevant for PSD files, otherwise it will have no effect
[in]	alphaChannelIdx	The index of the alpha channel to load, this is only relevant for PSD files, otherwise it will have no effect

Returns: MTexture pointer

Examples:: apiMeshShape/apiMeshGeometryOverride.cpp, cgFx/cgfxShaderNode.cpp, customSpriteShader/customSpriteShader.cpp, customTextureShader/customTextureShaderOverride.cpp, dx11Shader/dx11Shader.cpp, fileTexture/fileTexture.cpp, glslShader/GLSLShader.cpp, hlslShader/hlslShader.cpp, hwApiTextureTest/hwApiTextureTest.cpp, hwApiTextureTest/hwRendererHelper.cpp, simpleNoiseShader/simpleNoiseShaderOverride.cpp, tessellatedQuad/TessellatedQuadGeomOverride.cpp, viewDX11DeviceAccess/viewDX11DeviceAccess.cpp, viewImageBlitOverride/viewImageBlitOverride.cpp, and viewOverrideTrackTexture/viewOverrideTrackTexture.cpp.

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] args The 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]	textureName	Image file name
[in]	contextNodeFullName	full name of the texture owner Node to be provided as a context to the Maya resolver
[in]	mipmapLevels	Mipmap generation levels "mipmapLevels!=1" == create and populate all possible levels, using file contents if available "mipmapLevels==1" == no mipmap chain
[in]	useExposureControl	Use linear exposure control to convert HDR images
[in]	layerName	The name of the layer to load, this is only relevant for PSD files, otherwise it will have no effect
[in]	alphaChannelIdx	The 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]	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 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]	textureNode	Node to acquire texture from
[in]	allowBackgroundLoad	Allow 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]	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 * 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 texture 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]	textureName	Name to give to the texture
[in]	tilePaths	Set of path names to UV tiles
[in]	tilePositions	Set of lower left coordinates for each UV tile.
[in]	undefinedColor	Color to fill tile region with if the image for a given UV tile cannot be acquired.
[in]	maxWidth	Maximum width of the output texture. The value is clamped to a minimum of 256.
[in]	maxHeight	Maximum height of the output texture. The value is clamped to a minimum of 256.
[out]	failedTilePaths	List of files which were not written to the output texture.
[out]	uvScaleOffset	Transform 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:: hwApiTextureTest/hwApiTextureTest.cpp.

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]	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

Examples:: viewImageBlitOverride/viewImageBlitOverride.cpp.

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]	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

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:: apiMeshShape/apiMeshGeometryOverride.cpp, blast2Cmd/blast2Cmd.cpp, cgFx/cgfxShaderNode.cpp, dx11Shader/dx11Shader.cpp, fileTexture/fileTexture.cpp, glslShader/GLSLShader.cpp, hwApiTextureTest/hwApiTextureTest.cpp, simpleNoiseShader/simpleNoiseShaderOverride.cpp, tessellatedQuad/TessellatedQuadGeomOverride.cpp, viewDX11DeviceAccess/viewDX11DeviceAccess.cpp, viewImageBlitOverride/viewImageBlitOverride.cpp, viewOverrideTrackTexture/viewOverrideTrackTexture.cpp, viewRenderOverride/viewRenderOverrideOperations.cpp, viewRenderOverrideFrameCache/viewRenderOverrideFrameCache.cpp, viewRenderOverridePointLightShadows/viewRenderOverridePointLightShadows.cpp, viewRenderOverrideShadows/viewRenderOverrideShadows.cpp, and viewRenderOverrideTargets/viewRenderOverrideTargets.cpp.

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

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.

Examples:: blast2Cmd/blast2Cmd.cpp, hwApiTextureTest/hwApiTextureTest.cpp, viewOverrideTrackTexture/viewOverrideTrackTexture.cpp, and viewRenderOverrideFrameCache/viewRenderOverrideFrameCache.cpp.

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] textureName Name of the texture to search for

Returns: A pointer to the texture if found, NULL otherwise

Examples:: simpleNoiseShader/simpleNoiseShaderOverride.cpp.

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

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation