MShaderInstance Class Reference

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.