MShaderInstance Class Reference


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.

Static Public Member Functions

static const char * className ()
 Returns the name of this class.

Member Enumeration Documentation

Specifies parameter types.

Enumerator:
kInvalid 

Invalid element type (default value)

kBoolean 

Boolean.

kInteger 

Signed 32-bit integer.

kFloat 

IEEE single precision floating point.

kFloat2 

IEEE single precision floating point (x2)

kFloat3 

IEEE single precision floating point (x3)

kFloat4 

IEEE single precision floating point (x4)

kFloat4x4Row 

IEEE single precision floating point row-major matrix (4x4)

kFloat4x4Col 

IEEE single precision floating point column-major matrix (4x4)

kTexture1 

1D texture

kTexture2 

2D texture

kTexture3 

3D texture

kTextureCube 

Cube texture.

kSampler 

Sampler.


Member Function Documentation

MShaderInstance::DrawCallback preDrawCallback ( ) const

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

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

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

Parameters:
[out]listThe list to populate parameter names
Examples:
hwPhongShader.cpp.
MShaderInstance::ParameterType parameterType ( const MString parameterName) const

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

Parameters:
[in]parameterNameName of the parameter to query
Returns:
The type of the named parameter
Examples:
hwPhongShader.cpp.
bool isArrayParameter ( const MString parameterName) const

Determine whether the named parameter is an array.

Parameters:
[in]parameterNameName of the parameter to query
Returns:
True if the named parameter is an array
Examples:
hwPhongShader.cpp.
MString semantic ( const MString parameterName) const

Return the semantic for a named parameter.

Parameters:
[in]parameterNameName of the parameter to query
Returns:
Semantic string. String will be empty if there is no semantic.
MStatus setParameter ( const MString parameterName,
bool  value 
)

Set a named, boolean parameter on the shader instance.

Parameters:
[in]parameterNameName of the parameter to set
[in]valueValue of the parameter
Returns:
Status code
Status Codes:
MStatus setParameter ( const MString parameterName,
int  value 
)

Set a named, integer parameter on the shader instance.

Parameters:
[in]parameterNameName of the parameter to set
[in]valueValue of the parameter
Returns:
Status code
Status Codes:
MStatus setParameter ( const MString parameterName,
float  value 
)

Set a named, float parameter on the shader instance.

Parameters:
[in]parameterNameName of the parameter to set
[in]valueValue of the parameter
Returns:
Status code
Status Codes:
MStatus setParameter ( const MString parameterName,
const float *  value 
)

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]parameterNameName of the parameter to set
[in]valueValue of the parameter
Returns:
Status code
Status Codes:
MStatus setParameter ( const MString parameterName,
const MMatrix value 
)

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]parameterNameName of the parameter to set
[in]valueValue of the parameter
Returns:
Status code
Status Codes:
MStatus setParameter ( const MString parameterName,
MTextureAssignment textureAssignment 
)

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]parameterNameName of the parameter to set
[in]textureAssignmentTexture to assign
Returns:
Status code
Status Codes:
MStatus setParameter ( const MString parameterName,
MRenderTargetAssignment targetAssignment 
)

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]parameterNameName of the parameter to set
[in]targetAssignmentRender target to assign
Returns:
Status code
Status Codes:
MStatus setParameter ( const MString parameterName,
const MSamplerState sampler 
)

Set a sampler parameter on the shader instance.

Parameters:
[in]parameterNameName of the parameter to set
[in]samplerSampler state to assign
Returns:
Status code
Status Codes:
MStatus setArrayParameter ( const MString parameterName,
const bool *  values,
unsigned int  count 
)

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

Parameters:
[in]parameterNameName of the parameter to set
[in]valuesThe array of values to set
[in]countThe number of values in the array
Returns:
Status code
Status Codes:
MStatus setArrayParameter ( const MString parameterName,
const int *  values,
unsigned int  count 
)

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

Parameters:
[in]parameterNameName of the parameter to set
[in]valuesThe array of values to set
[in]countThe number of values in the array
Returns:
Status code
Status Codes:
MStatus setArrayParameter ( const MString parameterName,
const float *  values,
unsigned int  count 
)

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]parameterNameName of the parameter to set
[in]valuesThe array of values to set
[in]countThe number of floats stored in the array divided by the dimension of the data
Returns:
Status code
Status Codes:
MStatus setArrayParameter ( const MString parameterName,
const MMatrix values,
unsigned int  count 
)

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]parameterNameName of the parameter to set
[in]valuesThe array of values to set
[in]countThe number of values in the array
Returns:
Status code
Status Codes:
MStatus bind ( const MDrawContext context) const

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]contextThe current draw context
Returns:
Status code
Status Codes:
unsigned int getPassCount ( const MDrawContext context,
MStatus status = NULL 
) const

Returns the number of draw passes defined by the shader.

Parameters:
[in]contextThe current draw context
[out]statusStatus code
Returns:
The pass count
Status Codes:
MStatus activatePass ( const MDrawContext context,
unsigned int  pass 
) const

Activates the given pass of the shader.

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

Parameters:
[in]contextThe current draw context
[in]passThe index of the pass to activate
Returns:
Status code
Status Codes:
MStatus unbind ( const MDrawContext context) const

Unbinds the shader instance from the draw context.

Parameters:
[in]contextThe current draw context
Returns:
Status code
Status Codes:
MStatus updateParameters ( const MDrawContext context) const

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]contextThe current draw context
Returns:
Status code
Status Codes:
bool isTransparent ( ) const

Return whether the shader will render with transparency.

Returns:
true if shader will render with transparency
MStatus setIsTransparent ( bool  value)

Set whether the shader will render with transparency.

Parameters:
[in]valueValue to set
Returns:
Status code
Status Codes:
const char * className ( ) [static]

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