MShaderManager Class Reference

This reference page is linked to from the following overview topics: Extension for Autodesk Maya 2013, Data Classes, Rendering Overrides, Framework Classes, 2.3 Shader Instances, 3.2 The Renderer.



Detailed Description

Provides access to MShaderInstance objects for use in Viewport 2.0.

This class generates MShaderInstance objects for use with user-created MRenderItem objects. Any MShaderInstance objects created by this class are owned by the caller.

The methods for adding shader and shader include paths will allow for additional search paths to be used with the "getEffectsFileShader()" method which searches for shader files on disk. The default search path is in the "Cg" and "HLSL" folders found in the runtime directory. It is recommended that user defined shaders not reside at this location to avoid any potential shader conflicts.

When acquiring a shader instance the caller may also specify pre-draw and post-draw callback functions. These functions will be invoked any time a render item that uses the shader instance is about to be drawn. These callbacks are passed an MDrawContext object as well as the render item being drawn and may alter the draw state in order to get different rendering effects. Accessing Maya nodes from within these callbacks is an error and may result in instability.

Examples:

hwPhongShader.cpp.

#include <MShaderManager.h>

List of all members.

Public Types

enum  MStockShader {
  k3dSolidShader, k3dBlinnShader, k3dDefaultMaterialShader, k3dSolidTextureShader,
  k3dCPVShader, k3dShadowerShader, k3dFatPointShader
}
 

Name of an available "stock" shader.

More...

Public Member Functions

MStatus addShaderPath (const MString &path) const
 Add a path to the list of shader search paths.
MStatus shaderPaths (MStringArray &paths) const
 Query the list of shader search paths.
MStatus addShaderIncludePath (const MString &path) const
 Add a path to the list of paths used for searching for shader include files.
MStatus shaderIncludePaths (MStringArray &paths) const
 Query the list of search paths user for searching for shader include files.
MShaderInstancegetEffectsFileShader (const MString &effectsFileName, const MString &techniqueName, MShaderCompileMacro *macros=0, unsigned int numberOfMacros=0, bool useEffectCache=true, MShaderInstance::DrawCallback preCb=0, MShaderInstance::DrawCallback postCb=0) const
 Get a new instance of a shader generated from an effects file stored on disk.
MShaderInstancegetEffectsBufferShader (const void *buffer, unsigned int size, const MString &techniqueName, MShaderCompileMacro *macros=0, unsigned int numberOfMacros=0, bool useEffectCache=true, MShaderInstance::DrawCallback preCb=0, MShaderInstance::DrawCallback postCb=0) const
 Get a new instance of a shader generated from a block of memory containing device-specific source code (as char*).
MShaderInstancegetStockShader (MStockShader name, MShaderInstance::DrawCallback preCb=0, MShaderInstance::DrawCallback postCb=0) const
 Get a new instance of a stock shader.
void releaseShader (MShaderInstance *shader) const
 Deletes the MShaderInstance and releases its reference to the underlying shader which is held by the MShaderInstance object.

Static Public Member Functions

static bool isSupportedShaderSemantic (const MString &value)
 Return if a given string is a supported shader semantic.
static const char * className ()
 Returns the name of this class.

Member Enumeration Documentation

Name of an available "stock" shader.

Enumerator:
k3dSolidShader 

An instance of a solid color shader for 3d rendering.

k3dBlinnShader 

An instance of a Blinn shader for 3d rendering.

k3dDefaultMaterialShader 

An instance of a stock "default material" shader for 3d rendering.

k3dSolidTextureShader 

An instance of a stock solid texture shader for 3d rendering.

k3dCPVShader 

An instance of a stock color per vertex shader for 3d rendering.

k3dShadowerShader 

An instance of a stock shader which can be used when rendering shadow maps.

k3dFatPointShader 

An instance of a stock fat point shader for 3d rendering.


Member Function Documentation

MStatus addShaderPath ( const MString path) const

Add a path to the list of shader search paths.

Parameters:
[in]pathShader search path.
Returns:
Status code
Status Codes:
MStatus shaderPaths ( MStringArray paths) const

Query the list of shader search paths.

Parameters:
[out]pathsA string array which is filled in with search path strings. Each array element will contain one shader path string.
Returns:
Status code
Status Codes:
MStatus addShaderIncludePath ( const MString path) const

Add a path to the list of paths used for searching for shader include files.

Parameters:
[in]pathShader include path.
Returns:
Status code
Status Codes:
MStatus shaderIncludePaths ( MStringArray paths) const

Query the list of search paths user for searching for shader include files.

Parameters:
[out]pathsA string array which is filled in with search path strings. Each array element will contain one shader include path string.
Returns:
Status code
Status Codes:
MShaderInstance * getEffectsFileShader ( const MString effectsFileName,
const MString techniqueName,
MShaderCompileMacro macros = 0,
unsigned int  numberOfMacros = 0,
bool  useEffectCache = true,
MShaderInstance::DrawCallback  preCb = 0,
MShaderInstance::DrawCallback  postCb = 0 
) const

Get a new instance of a shader generated from an effects file stored on disk.

If a file extension is not supplied as part of the file name argument then the following strings are appended to the file name based on the drawing API which is currently being used by the renderer:

  • If the underlying drawing API is OpenGL then ".cgfx" is appended.
  • If the underlying drawing API is DirectX 10 or higher then "10.fx" is appended.

When the object is no longer needed, MShaderManager::releaseShader() should be called to notify the shader manager that the caller is done with the shader.

Optionally, a pre-draw and post-draw callback function may be associated with the shader. The callbacks will be invoked any time a render item using the shader is drawn.

Parameters:
[in]effectsFileNameThe effects file
[in]techniqueNameThe name of a technique in the effects file. If an empty string is specified then the first technique in the effects file will be used.
[in]macrosPointer to an array of shader macros structures. The default value is 0, meaning that no macros are specified.
[in]numberOfMacrosNumber of macros. The default value is 0.
[in]useEffectCacheUse the internal effect cache to prevent reloading the effect file every time it is requested. Unless you are changing the effect, this should always be set to true for maximum performance.
[in]preCbA pointer to the function to be called before render items are drawn with this shader.
[in]postCbA pointer to the function to be called after render items are drawn with this shader.
Returns:
A pointer to a shader instance for the effects file, or NULL on failure
MShaderInstance * getEffectsBufferShader ( const void *  buffer,
unsigned int  size,
const MString techniqueName,
MShaderCompileMacro macros = 0,
unsigned int  numberOfMacros = 0,
bool  useEffectCache = true,
MShaderInstance::DrawCallback  preCb = 0,
MShaderInstance::DrawCallback  postCb = 0 
) const

Get a new instance of a shader generated from a block of memory containing device-specific source code (as char*).

When the object is no longer needed, MShaderManager::releaseShader() should be called to notify the shader manager that the caller is done with the shader.

Optionally, a pre-draw and post-draw callback function may be associated with the shader. The callbacks will be invoked any time a render item using the shader is drawn.

Parameters:
[in]bufferA pointer to the block of memory from which to load the effect.
[in]sizeThe size of the effect to load in bytes.
[in]techniqueNameThe name of a technique in the effect. If an empty string is specified then the first technique in the effects file will be used.
[in]macrosPointer to an array of shader macros structures. The default value is 0, meaning that no macros are specified.
[in]numberOfMacrosNumber of macros. The default value is 0.
[in]useEffectCacheUse the internal effect cache to prevent reloading the effect every time it is requested. Unless you are changing the effect, this should always be set to true for maximum performance.
[in]preCbA pointer to the function to be called before render items are drawn with this shader.
[in]postCbA pointer to the function to be called after render items are drawn with this shader.
Returns:
A pointer to a shader instance for the effects file, or NULL on failure
MShaderInstance * getStockShader ( MStockShader  name,
MShaderInstance::DrawCallback  preCb = 0,
MShaderInstance::DrawCallback  postCb = 0 
) const

Get a new instance of a stock shader.

When the object is no longer needed, MShaderManager::releaseShader() should be called to notify the shader manager that the caller is done with the shader.

Optionally, a pre-draw and post-draw callback function may be associated with the shader. The callbacks will be invoked any time a render item using the shader is drawn.

Parameters:
[in]nameName of stock shader
[in]preCbA pointer to the function to be called before render items are drawn with this shader.
[in]postCbA pointer to the function to be called after render items are drawn with this shader.
Returns:
A pointer to an instance of the requested shader, or NULL on failure
Examples:
hwPhongShader.cpp.
void releaseShader ( MShaderInstance shader) const

Deletes the MShaderInstance and releases its reference to the underlying shader which is held by the MShaderInstance object.

After calling this method it is an error to try to use the MShaderInstance and attempting to do so will result in instability. The underlying shader might not be deleted immediately if it is in use by the renderer (for example if it is assigned to a render item).

Parameters:
[in]shaderThe shader to release
Examples:
hwPhongShader.cpp.
bool isSupportedShaderSemantic ( const MString value) [static]

Return if a given string is a supported shader semantic.

To be supported means that, for a shader parameter which has this semantic, the renderer will automatically set the parameter's value before the shader is used for rendering.

The plugin writer should not be explicitly setting the values for parameters with supported shader semantics.

For example a matrix parameter with the "projection" semantic will have its value updated with the current camera projection matrix before the shader is used.

Parameters:
valueString to check
Returns:
True if the string is a supported.
const char * className ( ) [static]

Returns the name of this class.

Returns:
Name of this class.

MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager
MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager MShaderManager