MShaderManager Class Reference

MShaderManager Class Reference
+ Related help topics:

#include <MShaderManager.h>

Class 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:

Public Types

enum  MStockShader {
  k3dSolidShader, k3dBlinnShader, k3dDefaultMaterialShader, k3dSolidTextureShader,
  k3dCPVFatPointShader, k3dColorLookupFatPointShader, k3dOpacityLookupFatPointShader, k3dColorOpacityLookupFatPointShader,
  k3dShadowerShader, k3dFatPointShader, k3dThickLineShader, k3dCPVThickLineShader,
  k3dDashLineShader, k3dCPVDashLineShader, k3dStippleShader, k3dThickDashLineShader,
  k3dCPVThickDashLineShader, k3dDepthShader, k3dCPVSolidShader, k3dIntegerNumericShader,
  k3dFloatNumericShader, k3dFloat2NumericShader, k3dFloat3NumericShader, k3dPointVectorShader,
  k3dPointLightShadowerShader
}
 Name of an available "stock" shader. More...
 
typedef void(* LinkLostCallback) (MShaderInstance *shaderInstance, MUserData *userData)
 Definition for callback function triggered when a MShaderInstance acquired by calling getShaderFromNode() is no longer valid for that node.
 

Public Member Functions

MStatus addShaderPath (const MString &path) const
 Add a path to the list of shader search paths. More...
 
MStatus shaderPaths (MStringArray &paths) const
 Query the list of shader search paths. More...
 
MStatus addShaderIncludePath (const MString &path) const
 Add a path to the list of paths used for searching for shader include files. More...
 
MStatus shaderIncludePaths (MStringArray &paths) const
 Query the list of search paths user for searching for shader include files. More...
 
MStatus clearEffectCache () const
 Clear the effect cache. More...
 
MStatus removeEffectFromCache (const MString &effectsFileName, const MString &techniqueName, MShaderCompileMacro *macros=0, unsigned int numberOfMacros=0) const
 Remove an effect from the cache. More...
 
void getEffectsTechniques (const MString &effectsFileName, MStringArray &techniqueNames, MShaderCompileMacro *macros=0, unsigned int numberOfMacros=0, bool useEffectCache=true) const
 Analyzes a given effect file to extract the names of the techniques that are defined. More...
 
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. More...
 
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*). More...
 
MShaderInstancegetFragmentShader (const MString &fragmentName, const MString &structOutputName, bool decorateFragment, MShaderInstance::DrawCallback preCb=0, MShaderInstance::DrawCallback postCb=0) const
 Get a new instance of a shader generated from a named shader fragment or fragment graph. More...
 
MShaderInstancegetShaderFromNode (const MObject &shaderNode, const MDagPath &path, LinkLostCallback linkLostCb=0, MUserData *linkLostUserData=0, MShaderInstance::DrawCallback preCb=0, MShaderInstance::DrawCallback postCb=0, bool nonTextured=false) const
 Get the shader instance assigned to a shader node. More...
 
MShaderInstancegetStockShader (MStockShader name, MShaderInstance::DrawCallback preCb=0, MShaderInstance::DrawCallback postCb=0) const
 Get a new instance of a stock shader. More...
 
void releaseShader (MShaderInstance *shader) const
 Deletes the MShaderInstance and releases its reference to the underlying shader which is held by the MShaderInstance object. More...
 

Static Public Member Functions

static bool isSupportedShaderSemantic (const MString &value)
 Return if a given string is a supported shader semantic. More...
 
static MString getLastError ()
 Get the description of the last error encountered by the shader manager regarding an effect. More...
 
static MString getLastErrorSource (bool displayLineNumber=false, bool filterSource=false, unsigned int numSurroundingLines=2)
 Get the source of the shader that generated the last error. More...
 
static const char * className ()
 Returns the name of this class. More...
 

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.

k3dCPVFatPointShader 

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

k3dColorLookupFatPointShader 

An instance of a stock fat point shader using a 1D color texture lookup.

Output is (RGB, 1.0f)

k3dOpacityLookupFatPointShader 

An instance of a stock fat point shader using a 1D color texture lookup.

Output is (InsColor, A) where InsColor is a shader parameter.

k3dColorOpacityLookupFatPointShader 

An instance of a stock fat point shader using two 1D color textures lookup.

Output is (RGB, A)

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.

k3dThickLineShader 

An instance of a stock thick line shader for 3d rendering.

k3dCPVThickLineShader 

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

k3dDashLineShader 

An instance of a stock dash line shader for 3d rendering.

k3dCPVDashLineShader 

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

k3dStippleShader 

An instance of a stipple shader for drawing 3d filled triangles.

k3dThickDashLineShader 

An instance of a stock thick dash line shader for 3d rendering.

k3dCPVThickDashLineShader 

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

k3dDepthShader 

An instance of a stock shader that can be used for 3d rendering of depth.

k3dCPVSolidShader 

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

k3dIntegerNumericShader 

An instance of a stock shader for drawing single integer values per vertex for 3d rendering.

k3dFloatNumericShader 

An instance of a stock shader for drawing single float values values per vertex for 3d rendering.

k3dFloat2NumericShader 

An instance of a stock shader for drawing 2 float values per vertex for 3d rendering.

k3dFloat3NumericShader 

An instance of a stock shader for drawing 3 float values per vertex for 3d rendering.

k3dPointVectorShader 

An instance of a stock shader that can be used for 3d rendering of lines based on a point and a vector stream.

k3dPointLightShadowerShader 

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

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:
+ Examples:
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:
+ Examples:
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:
MStatus clearEffectCache ( ) const

Clear the effect cache.

This will allow all relevant effects to be updated when the implementation of a shader fragment or fragment graph has been modified.

Returns
Status code
Status Codes:
MStatus removeEffectFromCache ( const MString effectsFileName,
const MString techniqueName,
MShaderCompileMacro macros = 0,
unsigned int  numberOfMacros = 0 
) const

Remove an effect from the cache.

This is particulary useful when calling the getEffectsTechniques() and/or getEffectsFileShader() with the flag useEffectCache set to true for maximum performance, and will allow reloading the effect from the disk when the shader file has been modified.

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.
  • If the underlying drawing API is OpenGLCoreProfile then ".ogsfx" is appended.

Note: each technique of a shader file is stored in a separate effect. Also, the macros are part of the caching key, so macros should match between getEffectsTechniques()/getEffectsFileShader() and removeEffectFromCache().

Parameters
[in]effectsFileNameThe effects file
[in]techniqueNameThe technique corresponding to the effect to remove
[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.
Returns
Status code
Status Codes:
+ Examples:
void getEffectsTechniques ( const MString effectsFileName,
MStringArray techniqueNames,
MShaderCompileMacro macros = 0,
unsigned int  numberOfMacros = 0,
bool  useEffectCache = true 
) const

Analyzes a given effect file to extract the names of the techniques that are defined.

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.
  • If the underlying drawing API is OpenGLCoreProfile then ".ogsfx" is appended.
Parameters
[in]effectsFileNameThe effects file
[in]techniqueNamesinput array of strings used to output the technique names.
[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.
Returns
void.
+ Examples:
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.
  • If the underlying drawing API is OpenGLCoreProfile then ".ogsfx" 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
+ Examples:
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 * getFragmentShader ( const MString fragmentName,
const MString structOutputName,
bool  decorateFragment,
MShaderInstance::DrawCallback  preCb = 0,
MShaderInstance::DrawCallback  postCb = 0 
) const

Get a new instance of a shader generated from a named shader fragment or fragment graph.

MFragmentManager can be used to query the names of registered fragments and fragment graphs and to add new fragments and graphs to Maya.

The named fragment must have a single 3-float or 4-float output. If the fragment has a struct output, callers may specify the name of a 3-float or 4-float member of the struct to use as the output for the final shader instance. If the fragment does not have a struct output, the struct member name parameter is ignored.

Callers may request that Maya decorate the fragment with additonal lighting information before creating the shader instance. This will allow the shader to work with Maya lights. Internal surface shader fragments require this decoration in order to function correctly. Please see the documentation for MPxSurfaceShadingNodeOverride for more details.

Parameters
[in]fragmentNameThe name of the fragment to generate a shader from
[in]structOutputNameIf the output of the fragment is a struct, use this parameter to specify which member of the struct to use. This parameter is ignored if the output of the fragment is not a struct.
[in]decorateFragmentIf true, Maya state fragments will be added
[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 fragment or NULL on failure
+ Examples:
MShaderInstance * getShaderFromNode ( const MObject shaderNode,
const MDagPath path,
LinkLostCallback  linkLostCb = 0,
MUserData linkLostUserData = 0,
MShaderInstance::DrawCallback  preCb = 0,
MShaderInstance::DrawCallback  postCb = 0,
bool  nonTextured = false 
) const

Get the shader instance assigned to a shader node.

Parameters
[in]shaderNodeThe surface shader node.
[in]pathThe path to the instance of the assigned geometry.
[in]linkLostCbA pointer to the function to be called when this shader instance is no longer connected to the node it was translated for.
[in]linkLostUserDataUser supplied data to be passed into the link lost callback. This data will not be deleted internally and the lifetime must be managed by the caller. The link lost callback will only be called once so it is safe to delete this data anytime after the callback has been triggered.
[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.
[in]nonTexturedWhether or not a non-textured effect instance is needed. The default value is false.
Returns
A pointer to a shader instance for the surface shader 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.

Some shaders have parameters set to specific default values when the instance is acquired. If these parameters are modified the results may be unpredictable.

For:

  • k3dDashLineShader, k3dCPVDashLineShader, k3dThickDashLineShader, k3dCPVThickDashLineShader : The dash pattern ("dashPattern") and the dash pattern factor ("dashPatternFactor") parameters are set.
  • k3dStippleShader : The stipple texture parameter ("map") and the associated sampler parameter ("sampler") are set.
  • k3dIntegerNumericShader, k3dFloatNumericShader, k3dFloat2NumericShader, k3dFloat3NumericShader : The texture parameter ("map") and associated sampler parameter ("sampler") which are used to render numbers are set.

Each numeric shader instance requires as input a vertex buffer which contains the number(s) to display per vertex. This buffer will be bound to an input parameter with a specific semantic name.

When vertex requirements need to be fullfilled, this same semantic name will be specified in a vertex buffer descriptor. The method MVertexBufferDescriptor::semanticName() can be used to query the semantic name on the descriptor. If a match is found then the appropriate numeric data should filled into the buffer.

  • For k3dIntegerNumericShader, k3dFloatNumericShader : The buffer requirement is a single float per vertex. The semantic name to compare against is "NumericValue".
  • For k3dFloat2NumericShader : The buffer requirement is 2 float values per vertex. The semantic name to compare against is "Numeric2Value".
  • For k3dFloat3NumericShader : The buffer requirement is 3 float values per vertex. The semantic name to compare against is "Numeric3Value".
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:
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:
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.
MString getLastError ( )
static

Get the description of the last error encountered by the shader manager regarding an effect.

This includes fragment and effect loading, technique query, and shader binding.

Returns
The last error
+ Examples:
MString getLastErrorSource ( bool  displayLineNumber = false,
bool  filterSource = false,
unsigned int  numSurroundingLines = 2 
)
static

Get the source of the shader that generated the last error.

See getLastError().

Parameters
[in]displayLineNumberIf true, add the number line at the beginning of each line. The default is false.
[in]filterSourceIf true, only display the lines surrounding the error(s). The default is false.
[in]numSurroundingLinesThe number of leading and trailing lines to display around filtered source. The default is 2.
Returns
The source of the shader that generated the last error.
+ 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:
  • MShaderManager.h
  • MShaderManager.cpp