- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Static Public Member Functions

# MShaderInstance Class Reference
OpenMayaRender - API module for rendering

This reference page is linked to from the following overview topics: Autodesk Maya 2014, Extension for Autodesk Maya 2013, Framework Classes, 2.3 Shader Instances, 2.4 Texture creation and texture manager, 3.3 Geometry Overrides, 3.5 Shading Node Overrides, 3.8 Render Loop Overrides, 4.2 Lighting Interfaces, 4.4 Effects interfaces, 4.5 Handling custom renderables for object overrides, Shader semantics supported by Viewport 2.0.

Search for all occurrences

## Detailed Description

An instance of a shader that may be used with Viewport 2.0.

This class represents a shader that may be used with the MRenderItem class for rendering in Viewport 2.0.

Examples:

  hwPhongShader.cpp.

`#include <MShaderManager.h>`

List of all members.

## Public Types
enum | ParameterType { kInvalid, kBoolean, kInteger, kFloat, kFloat2, kFloat3, kFloat4, kFloat4x4Row, kFloat4x4Col, kTexture1, kTexture2, kTexture3, kTextureCube, kSampler }
| Specifies parameter types. More...
typedef void(* | DrawCallback )(MDrawContext &context, const MRenderItemList &renderItemList, MShaderInstance *shaderInstance)
| Definition for pre/post draw callback functions.
## Public Member Functions
DrawCallback | preDrawCallback () const
| Access the pre-draw callback function pointer set for the this shader instance.
DrawCallback | postDrawCallback () const
| Access the post-draw callback function pointer set for the this shader instance.
void | parameterList (MStringArray &list) const
| Get the names of all parameters that are settable on this shader instance.
ParameterType | parameterType (const MString &parameterName) const
| Get the type of the named parameter, returns kInvalid if parameter is not found.
bool | isArrayParameter (const MString &parameterName) const
| Determine whether the named parameter is an array.
MString | semantic (const MString &parameterName) const
| Return the semantic for a named parameter.
MStatus | setParameter (const MString &parameterName, bool value)
| Set a named, boolean parameter on the shader instance.
MStatus | setParameter (const MString &parameterName, int value)
| Set a named, integer parameter on the shader instance.
MStatus | setParameter (const MString &parameterName, float value)
| Set a named, float parameter on the shader instance.
MStatus | setParameter (const MString &parameterName, const float *value)
| Set a named, float2, float3 or float4 parameter on the shader instance.
MStatus | setParameter (const MString &parameterName, const MMatrix &value)
| Set a named, matrix parameter on the shader instance.
MStatus | setParameter (const MString &parameterName, MTextureAssignment &textureAssignment)
| Set a texture parameter on the shader instance.
MStatus | setParameter (const MString &parameterName, MRenderTargetAssignment &targetAssignment)
| Set a named, texture parameter on the shader instance to a render target.
MStatus | setParameter (const MString &parameterName, const MSamplerState &sampler)
| Set a sampler parameter on the shader instance.
MStatus | setArrayParameter (const MString &parameterName, const bool *values, unsigned int count)
| Set a named, bool array parameter on the shader instance.
MStatus | setArrayParameter (const MString &parameterName, const int *values, unsigned int count)
| Set a named, integer array parameter on the shader instance.
MStatus | setArrayParameter (const MString &parameterName, const float *values, unsigned int count)
| Set a named, float array parameter on the shader instance.
MStatus | setArrayParameter (const MString &parameterName, const MMatrix *values, unsigned int count)
| Set a named, matrix array parameter on the shader instance.
MStatus | bind (const MDrawContext &context) const
| Binds the shader instance to the draw context, so that it is the active shader.
unsigned int | getPassCount (const MDrawContext &context, MStatus *status=NULL) const
| Returns the number of draw passes defined by the shader.
MStatus | activatePass (const MDrawContext &context, unsigned int pass) const
| Activates the given pass of the shader.
MStatus | unbind (const MDrawContext &context) const
| Unbinds the shader instance from the draw context.
MStatus | updateParameters (const MDrawContext &context) const
| Updates the bound shader instance with the current parameter data.
bool | isTransparent () const
| Return whether the shader will render with transparency.
MStatus | setIsTransparent (bool value)
| Set whether the shader will render with transparency.
MShaderInstance * | clone () const
| Clone the shader.
## Static Public Member Functions
static const char * | className ()
| Returns the name of this class. Search for all occurrences

## Member Enumeration Documentation

enum ParameterType

Search for all occurrences

Specifies parameter types.

Enumerator:

  kInvalid | Invalid element type (default value) Search for all occurrences
  kBoolean | Boolean. Search for all occurrences
  kInteger | Signed 32-bit integer. Search for all occurrences
  kFloat | IEEE single precision floating point. Search for all occurrences
  kFloat2 | IEEE single precision floating point (x2) Search for all occurrences
  kFloat3 | IEEE single precision floating point (x3) Search for all occurrences
  kFloat4 | IEEE single precision floating point (x4) Search for all occurrences
  kFloat4x4Row | IEEE single precision floating point row-major matrix (4x4) Search for all occurrences
  kFloat4x4Col | IEEE single precision floating point column-major matrix (4x4) Search for all occurrences
  kTexture1 | 1D texture Search for all occurrences
  kTexture2 | 2D texture Search for all occurrences
  kTexture3 | 3D texture Search for all occurrences
  kTextureCube | Cube texture. Search for all occurrences
  kSampler | Sampler. Search for all occurrences

## Member Function Documentation

MShaderInstance::DrawCallback preDrawCallback | ( |  | ) | const

Search for all occurrences

Access the pre-draw callback function pointer set for the this shader instance.

Returns:
  The pre-draw callback function pointer or NULL if not set

MShaderInstance::DrawCallback postDrawCallback | ( |  | ) | const

Search for all occurrences

Access the post-draw callback function pointer set for the this shader instance.

Returns:
  The post-draw callback function pointer or NULL if not set

void parameterList | ( | MStringArray & | list | ) | const

Search for all occurrences

Get the names of all parameters that are settable on this shader instance.

Parameters:

  [out] | list | The list to populate parameter names

Examples:
  hwPhongShader.cpp.

MShaderInstance::ParameterType parameterType | ( | const MString & | parameterName | ) | const

Search for all occurrences

Get the type of the named parameter, returns kInvalid if parameter is not found.

Parameters:

  [in] | parameterName | Name of the parameter to query

Returns:
  The type of the named parameter

Examples:
  hwPhongShader.cpp.

bool isArrayParameter | ( | const MString & | parameterName | ) | const

Search for all occurrences

Determine whether the named parameter is an array.

Parameters:

  [in] | parameterName | Name of the parameter to query

Returns:
  True if the named parameter is an array

Examples:
  hwPhongShader.cpp.

MString semantic | ( | const MString & | parameterName | ) | const

Search for all occurrences

Return the semantic for a named parameter.

Parameters:

  [in] | parameterName | Name of the parameter to query

Returns:
  Semantic string. String will be empty if there is no semantic.

MStatus setParameter | ( | const MString & | parameterName,
|  | bool | value
| ) |  |

Search for all occurrences

Set a named, boolean parameter on the shader instance.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | value | Value of the parameter

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a boolean parameter.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter | ( | const MString & | parameterName,
|  | int | value
| ) |  |

Search for all occurrences

Set a named, integer parameter on the shader instance.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | value | Value of the parameter

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not an integer parameter.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter | ( | const MString & | parameterName,
|  | float | value
| ) |  |

Search for all occurrences

Set a named, float parameter on the shader instance.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | value | Value of the parameter

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a float parameter.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter | ( | const MString & | parameterName,
|  | const float * | value
| ) |  |

Search for all occurrences

Set a named, float2, float3 or float4 parameter on the shader instance.

The floating point data stored in "value" will be interpreted based on the type of the named parameter. For example, for a parameter of type kFloat3, the data will be assumed to be an array containing three floats.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | value | Value of the parameter

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a compound float parameter.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter | ( | const MString & | parameterName,
|  | const MMatrix & | value
| ) |  |

Search for all occurrences

Set a named, matrix parameter on the shader instance.

Note that this method does not alter the matrix and it is up to the caller to set the values correctly depending on whether the parameter is row-major or column-major.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | value | Value of the parameter

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a matrix parameter.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter | ( | const MString & | parameterName,
|  | MTextureAssignment & | textureAssignment
| ) |  |

Search for all occurrences

Set a texture parameter on the shader instance.

If the texture assignment contains a NULL value for texture then the shader parameter will be set to NULL.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | textureAssignment | Texture to assign

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a texture parameter.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter | ( | const MString & | parameterName,
|  | MRenderTargetAssignment & | targetAssignment
| ) |  |

Search for all occurrences

Set a named, texture parameter on the shader instance to a render target.

If the render target assignment contains a NULL value then the shader parameter will be set to NULL.

Note, there is a significant performance penalty when binding MSAA targets (i.e. targets where multiSampleCount > 1).

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | targetAssignment | Render target to assign

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a texture parameter.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setParameter | ( | const MString & | parameterName,
|  | const MSamplerState & | sampler
| ) |  |

Search for all occurrences

Set a sampler parameter on the shader instance.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | sampler | Sampler state to assign

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a sampler parameter.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setArrayParameter | ( | const MString & | parameterName,
|  | const bool * | values,
|  | unsigned int | count
| ) |  |

Search for all occurrences

Set a named, bool array parameter on the shader instance.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | values | The array of values to set
  [in] | count | The number of values in the array

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a bool array parameter or count is out of bounds.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setArrayParameter | ( | const MString & | parameterName,
|  | const int * | values,
|  | unsigned int | count
| ) |  |

Search for all occurrences

Set a named, integer array parameter on the shader instance.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | values | The array of values to set
  [in] | count | The number of values in the array

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not an integer array parameter or count is out of bounds.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setArrayParameter | ( | const MString & | parameterName,
|  | const float * | values,
|  | unsigned int | count
| ) |  |

Search for all occurrences

Set a named, float array parameter on the shader instance.

This method is used for setting not just float arrays but float2, float3 and float4 array parameters as well. The floating point data stored in "values" will be interpreted based on the type of the named parameter. For example, for a parameter of type kFloat3, the data will be assumed to be a list of float-triples containing a total of "count" float-triples. So if "count" in this example is 5, that means the total number of raw floats is 3*5=15.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | values | The array of values to set
  [in] | count | The number of floats stored in the array divided by the dimension of the data

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a float array parameter or count is out of bounds.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus setArrayParameter | ( | const MString & | parameterName,
|  | const MMatrix * | values,
|  | unsigned int | count
| ) |  |

Search for all occurrences

Set a named, matrix array parameter on the shader instance.

Note that this method does not alter the matrices and it is up to the caller to set the values correctly depending on whether the parameter is row-major or column-major.

Parameters:

  [in] | parameterName | Name of the parameter to set
  [in] | values | The array of values to set
  [in] | count | The number of values in the array

Returns:
  Status code

Status Codes:
  - MS::kSuccess The parameter was set.
  - MS::kInvalidParameter The named parameter is not a matrix array parameter or count is out of bounds.
  - MS::kUnknownParameter The named parameter is not a parameter of the shader instance.
  - MS::kFailure An internal error prevented the parameter from being set.

MStatus bind | ( | const MDrawContext & | context | ) | const

Search for all occurrences

Binds the shader instance to the draw context, so that it is the active shader.

The typical call sequence is

bind() getPassCount() activatePass( 0 ) do drawing activatePass( 1 ) do drawing ... unbind()

Note that it is the plug-in author's responsibility to call unbind() at the appropriate time. Failing to do so may corrupt subsequent drawing.

Parameters:

  [in] | context | The current draw context

Returns:
  Status code

Status Codes:
  - MS::kSuccess The bind operation succeeded
  - MS::kFailure The shader instance or draw context was invalid

unsigned int getPassCount | ( | const MDrawContext & | context,
|  | MStatus * | status = `NULL`
| ) |  | const

Search for all occurrences

Returns the number of draw passes defined by the shader.

Parameters:

  [in] | context | The current draw context
  [out] | status | Status code

Returns:
  The pass count

Status Codes:
  - MS::kSuccess The operation succeeded
  - MS::kFailure The shader instance or draw context was invalid

MStatus activatePass | ( | const MDrawContext & | context,
|  | unsigned int | pass
| ) |  | const

Search for all occurrences

Activates the given pass of the shader.

Must be called between calls to bind() and unbind().

Parameters:

  [in] | context | The current draw context
  [in] | pass | The index of the pass to activate

Returns:
  Status code

Status Codes:
  - MS::kSuccess The operation succeeded
  - MS::kFailure The shader instance or draw context was invalid

MStatus unbind | ( | const MDrawContext & | context | ) | const

Search for all occurrences

Unbinds the shader instance from the draw context.

Parameters:

  [in] | context | The current draw context

Returns:
  Status code

Status Codes:
  - MS::kSuccess The unbind operation succeeded
  - MS::kFailure The shader instance or draw context was invalid

MStatus updateParameters | ( | const MDrawContext & | context | ) | const

Search for all occurrences

Updates the bound shader instance with the current parameter data.

This is useful in cases where the same shader instance is reusable but with different input parameters.

Must be called between calls to bind() and unbind().

Calling this method will invalidate any currently active pass. Must invoke activatePass() after calling this method.

Parameters:

  [in] | context | The current draw context

Returns:
  Status code

Status Codes:
  - MS::kSuccess The update operation succeeded
  - MS::kFailure The shader instance or draw context was invalid

bool isTransparent | ( |  | ) | const

Search for all occurrences

Return whether the shader will render with transparency.

Returns:
  true if shader will render with transparency

MStatus setIsTransparent | ( | bool | value | ) |

Search for all occurrences

Set whether the shader will render with transparency.

Parameters:

  [in] | value | Value to set

Returns:
  Status code

Status Codes:
  - MS::kSuccess The value was set.
  - MS::kFailure The value could not be set.

MShaderInstance * clone | ( |  | ) | const

Search for all occurrences

Clone the shader.

This will return a new MShaderInstance object which is identical to the existing shader. The new shader is completely independent of the original. Setting parameter values on either shader after calling clone will have no effect on the other.

Using clone can improve performance when many copies of the same shader are needed. When requesting MShaderInstance objects from MShaderManager the shader is recompiled for each request. The clone() method does not cause a recompilation.

Returns:
  A clone of this shader or NULL on failure

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  Name of this class.

MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance
MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance MShaderInstance