MUniformParameter Class Reference
[OpenMayaRender - API module for rendering]

#include <MUniformParameter.h>

List of all members.


Detailed Description

Uniform parameter.

The MUniformParameter class provides a high-level interface to hardware shader uniform parameters. By defining your shader's uniform parameters through this class, you allow Maya to handle the attributes, editing, serialisation, and caching for you in a standard way that ensure you'll be able to leverage future performance and functionlity improvements.

At setup time (either initial load or when the effect/technique is changed), your shader simply creates the list of parameters it requires, specifying the name, type, semantic of the parameters. At render time, you can then use the parameters to directly access the appropriate buffers for that surface data.

If you include a custom Attribute Editor template for your shader node, you can include these surface parameters by calling the AEhwUniformTemplateParameters script function. The following sample code provides a basic template you can modify - however your AE template can use as much or as little of this as you like:

global int $yourUniformNameTemplateInitialised = 0;

global proc AEyourUniformNameTemplate ( string $node )
{
        global int $yourUniformNameTemplateInitialised;
        if( $yourUniformNameTemplateInitialised == 0)
        {
                source "AEhwUniformTemplate.mel";
                $yourUniformNameTemplateInitialised = 1;
        }

        AEhwUniformTemplateHeader( $node);

        // Insert custom attributes between the swatch and the parameters here

        AEhwUniformTemplateParameters( $node);

        // Insert custom attributes after the parameters here

        AEhwUniformTemplateFooter( $node);
}
Examples:

hlslShader.cpp.


Public Types

enum   DataType {
   kTypeUnknown, kTypeBool, kTypeInt, kTypeFloat,
   kType1DTexture, kType2DTexture, kType3DTexture, kTypeCubeTexture,
   kTypeEnvTexture, kTypeString
}
  Parameter data types. More...
enum   DataSemantic {
   kSemanticUnknown, kSemanticObjectDir, kSemanticWorldDir, kSemanticViewDir,
   kSemanticProjectionDir, kSemanticObjectPos, kSemanticWorldPos, kSemanticViewPos,
   kSemanticProjectionPos, kSemanticColor, kSemanticNormal, kSemanticBump,
   kSemanticEnvironment, kSemanticWorldMatrix, kSemanticWorldInverseMatrix, kSemanticWorldInverseTransposeMatrix,
   kSemanticViewMatrix, kSemanticViewInverseMatrix, kSemanticViewInverseTransposeMatrix, kSemanticProjectionMatrix,
   kSemanticProjectionInverseMatrix, kSemanticProjectionInverseTransposeMatrix, kSemanticWorldViewMatrix, kSemanticWorldViewInverseMatrix,
   kSemanticWorldViewInverseTransposeMatrix, kSemanticWorldViewProjectionMatrix, kSemanticWorldViewProjectionInverseMatrix, kSemanticWorldViewProjectionInverseTransposeMatrix,
   kSemanticColorTexture, kSemanticNormalTexture, kSemanticBumpTexture, kSemanticNormalizationTexture,
   kSemanticTime
}
  Parameter semantics (i.e. what the parameter represents). More...

Public Member Functions

  MUniformParameter ()
  MUniformParameter (const MString &name, DataType type, DataSemantic semantic, unsigned int numRows=1, unsigned int numColumns=1, void *userData=NULL)
  ~MUniformParameter ()
const MUniformParameter operator= (const MUniformParameter &other)
const MString name () const
MUniformParameter::DataType  type () const
MUniformParameter::DataSemantic  semantic () const
unsigned int  numRows () const
unsigned int  numColumns () const
unsigned int  numElements () const
void *  userData () const
bool  isATexture () const
bool  hasChanged (const MGeometryList &iterator) const
const float *  getAsFloatArray (const MGeometryList &iterator) const
void  setAsFloatArray (const float *value, unsigned int maxElements) const
float  getAsFloat (const MGeometryList &iterator) const
void  setAsFloat (float value) const
MString  getAsString (const MGeometryList &iterator) const
void  setAsString (const MString &value) const
bool  getAsBool (const MGeometryList &iterator) const
void  setAsBool (bool value) const
int  getAsInt (const MGeometryList &iterator) const
void  setAsInt (int value) const
MPlug  getSource () const
void  setDirty ()

Friends

class  MUniformParameterList

Member Enumeration Documentation

Parameter data types.

Enumerator:
kTypeUnknown   
kTypeBool   
kTypeInt   
kTypeFloat   
kType1DTexture   
kType2DTexture   
kType3DTexture   
kTypeCubeTexture   
kTypeEnvTexture   
kTypeString   

Parameter semantics (i.e. what the parameter represents).

Enumerator:
kSemanticUnknown   
kSemanticObjectDir   
kSemanticWorldDir   
kSemanticViewDir   
kSemanticProjectionDir   
kSemanticObjectPos   
kSemanticWorldPos   
kSemanticViewPos   
kSemanticProjectionPos   
kSemanticColor   
kSemanticNormal   
kSemanticBump   
kSemanticEnvironment   
kSemanticWorldMatrix   
kSemanticWorldInverseMatrix   
kSemanticWorldInverseTransposeMatrix   
kSemanticViewMatrix   
kSemanticViewInverseMatrix   
kSemanticViewInverseTransposeMatrix   
kSemanticProjectionMatrix   
kSemanticProjectionInverseMatrix   
kSemanticProjectionInverseTransposeMatrix   
kSemanticWorldViewMatrix   
kSemanticWorldViewInverseMatrix   
kSemanticWorldViewInverseTransposeMatrix   
kSemanticWorldViewProjectionMatrix   
kSemanticWorldViewProjectionInverseMatrix   
kSemanticWorldViewProjectionInverseTransposeMatrix   
kSemanticColorTexture   
kSemanticNormalTexture   
kSemanticBumpTexture   
kSemanticNormalizationTexture   
kSemanticTime   

Constructor & Destructor Documentation

MUniformParameter::MUniformParameter (  ) 

Create an uninitialised (i.e. NULL) uniform parameter.

MUniformParameter::MUniformParameter ( const MString name,
DataType  type,
DataSemantic  semantic,
unsigned int  numRows = 1,
unsigned int  numColumns = 1,
void *  userData = NULL  
)

Create a new uniform parameter.

Parameters:
[in]  name  the name of the new parameter. For independently configurable inputs, this must be unique across all parameters on the shader. If multiple parameters share the same name, only a single input will be presented to the user, and the value used to populate the set of commonly named parameters.
[in]  type  the type of the new parameter. This can either be an atomic type (e.g. float), or a structure containing other parameters. Vectors of atomic types (e.g. float4) are defined by setting the atomic type to kFloat, and specifying the maxElements value of 4.
[in]  semantic  specifies the expected usage of the paramter (e.g. we expect this to be a colour, or a tangent, etc). This gives Maya a hint as to how the input should be presented to the user, and possibly even which input data is valid for this parameter. This value is ignored for structures.
[in]  numRows  specifies the number of row of the specified type to include (e.g. a vector would have 3 floats)
[in]  numColumns  specifies the number of columns of the specified type to include (e.g. a matrix would have 4 rows and 4 columns of floats)
[in]  userData  opaque data your plugin can use to store the relationship between this parameter and your shader (e.g. a parameter handle)

MUniformParameter::~MUniformParameter (  ) 

Class destructor.


Member Function Documentation

const MUniformParameter & MUniformParameter::operator= ( const MUniformParameter src  ) 

Assignment operator

const MString & MUniformParameter::name (  )  const

Get the name of this parameter

Returns:
The name of this parameter
Examples:

MUniformParameter::DataType MUniformParameter::type (  )  const

Get the type of this parameter

Returns:
The type of this parameter
Examples:

MUniformParameter::DataSemantic MUniformParameter::semantic (  )  const

Get the semantic of this parameter

Returns:
The semantic of this parameter

unsigned int MUniformParameter::numRows (  )  const

Get the number of rows in this parameter

Returns:
The number of rows in this parameter

unsigned int MUniformParameter::numColumns (  )  const

Get the number of columns in this parameter

Returns:
The number of columns in this parameter

unsigned int MUniformParameter::numElements (  )  const

Get the number of elements in this parameter (including rows and columns)

Returns:
The number of elements in this parameter
Examples:

void * MUniformParameter::userData (  )  const

Get the user data for this parameter. User data can be used to store plugin specific information that you want to associate with this parameter. Typically this will be used to store a handle to the effect parameter.

Returns:
The user data for this parameter
Examples:

bool MUniformParameter::isATexture (  )  const

Test if this parameter stores a texture.

Returns:
true if this parameter represents a texture, false otherwise.
Examples:

bool MUniformParameter::hasChanged ( const MGeometryList iterator  )  const

Has the value of this parameter changed since the last time it was accessed? This allow your shader to minimise state changes by only updating modified parameters.

Parameters:
[in]  iterator  the current shape being rendered.
Returns:
true if this parameter's value has changed since the last time its value was accessed. false otherwise.
Examples:

const float * MUniformParameter::getAsFloatArray ( const MGeometryList iterator  )  const

Get the value of this uniform parameter as one or more floating point values. Because some parameters can be shape-dependent, the method requires access to the current geometry item being rendered.

Parameters:
[in]  iterator  the current shape being rendered.
Returns:
The current floating point value of this uniform parameter.
Examples:

void MUniformParameter::setAsFloatArray ( const float *  value,
unsigned int  maxElements  
) const

Set the value of this uniform parameter as one or more floating point values. Note that it is not possible to set shape-specific parameters.

Parameters:
[in]  value  a pointer an array of floats holding the new floating point value(s) for this parameter.
[in]  maxElements  the maximum number of elements in the value array.
Examples:

float MUniformParameter::getAsFloat ( const MGeometryList iterator  )  const

Get the value of this uniform parameter as a float. Because some parameters can be shape-dependent, the method requires access to the current geometry item being rendered.

Parameters:
[in]  iterator  the current shape being rendered.
Returns:
The current float value of this uniform parameter.

void MUniformParameter::setAsFloat ( float  value  )  const

Set the value of this uniform parameter as a float. Note that it is not possible to set shape-dependent parameters.

Parameters:
[in]  value  the new float value for this parameter.

MString MUniformParameter::getAsString ( const MGeometryList iterator  )  const

Get the value of this uniform parameter as a string. Because some parameters can be shape-dependent, the method requires access to the current geometry item being rendered.

Parameters:
[in]  iterator  the current shape being rendered.
Returns:
The current string value of this uniform parameter.
Examples:

void MUniformParameter::setAsString ( const MString value  )  const

Set the value of this uniform parameter as a string. Note that it is not possible to set shape-dependent parameters.

Parameters:
[in]  value  the new string value for this parameter.
Examples:

bool MUniformParameter::getAsBool ( const MGeometryList iterator  )  const

Get the value of this uniform parameter as a boolean value. Because some parameters can be shape-dependent, the method requires access to the current geometry item being rendered.

Parameters:
[in]  iterator  the current shape being rendered.
Returns:
The current boolean value of this uniform parameter.
Examples:

void MUniformParameter::setAsBool ( bool  value  )  const

Set the value of this uniform parameter as a boolean value. Note that it is not possible to set shape-dependent parameters.

Parameters:
[in]  value  the new value for this parameter.
Examples:

int MUniformParameter::getAsInt ( const MGeometryList iterator  )  const

Get the value of this uniform parameter as an integer. Because some parameters can be shape-dependent, the method requires access to the current geometry item being rendered.

Parameters:
[in]  iterator  the current shape being rendered.
Returns:
The current integer value of this uniform parameter.
Examples:

void MUniformParameter::setAsInt ( int  value  )  const

Set the value of this uniform parameter as an integer value. Note that it is not possible to set shape-dependent parameters.

Parameters:
[in]  value  the new value for this parameter.
Examples:

MPlug MUniformParameter::getSource (  )  const

Get the source plug connected to this parameter. Other than textures, this will typically be a NULL plug.

Examples:

void MUniformParameter::setDirty (  ) 

Mark the data for this parameter as dirty. This will force the parameter to report that it has been changed the next time it is accessed. This allows external events (e.g. device lost, texture management, etc) to force a shader to re-set parameters tied to externally managed resources.

Examples:

Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6