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

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Friends

# MUniformParameter Class Reference

# OpenMayaRender - API module for rendering

Search for all occurrences

## 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.

`#include <MUniformParameter.h>`

List of all members.

## 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, kSemanticWorldTransposeMatrix, kSemanticViewTransposeMatrix, kSemanticProjectionTransposeMatrix, kSemanticWorldViewTransposeMatrix, kSemanticWorldViewProjectionTransposeMatrix, kSemanticViewProjectionMatrix, kSemanticViewProjectionInverseMatrix, kSemanticViewProjectionTransposeMatrix, kSemanticViewProjectionInverseTransposeMatrix, kSemanticLocalViewer, kSemanticViewportPixelSize, kSemanticBackgroundColor, kSemanticFrameNumber }
| Parameter semantics (i.e. what the parameter represents). More...
## Public Member Functions
| MUniformParameter ()
| Create an uninitialised (i.e.
| MUniformParameter (const MString &name, DataType type, DataSemantic semantic, unsigned int numRows=1, unsigned int numColumns=1, void *userData=NULL)
| Create a new uniform parameter.
| ~MUniformParameter ()
| Class destructor.
const MUniformParameter & | operator= (const MUniformParameter &other)
| Assignment operator.
const MString & | name () const
| Get the name of this parameter.
MUniformParameter::DataType | type () const
| Get the type of this parameter.
MUniformParameter::DataSemantic | semantic () const
| Get the semantic of this parameter.
unsigned int | numRows () const
| Get the number of rows in this parameter.
unsigned int | numColumns () const
| Get the number of columns in this parameter.
unsigned int | numElements () const
| Get the number of elements in this parameter (including rows and columns)
void * | userData () const
| Get the user data for this parameter.
void | setRangeMin (double rangeMin) const
| Sets the hard range lower bound for a numeric uniform parameter.
void | setRangeMax (double rangeMax) const
| Sets the hard range upper bound for a numeric uniform parameter.
void | setUIHidden (bool hiddenState) const
| Sets the hidden state of this parameter.
bool | isATexture () const
| Test if this parameter stores a texture.
bool | hasChanged (const MGeometryList &iterator) const
| Has the value of this parameter changed since the last time it was accessed? This allows your shader to minimise state changes by only updating modified parameters.
bool | hasChanged (const MHWRender::MDrawContext &context) const
| Has the value of this parameter changed since the last time it was accessed? This allows your shader to minimise state changes by only updating modified parameters.
const float * | getAsFloatArray (const MGeometryList &iterator) const
| Get the value of this uniform parameter as one or more floating point values.
const float * | getAsFloatArray (const MHWRender::MDrawContext &context) const
| Get the value of this uniform parameter as one or more floating point values.
void | setAsFloatArray (const float *value, unsigned int maxElements) const
| Set the value of this uniform parameter as one or more floating point values.
float | getAsFloat (const MGeometryList &iterator) const
| Get the value of this uniform parameter as a float.
float | getAsFloat (const MHWRender::MDrawContext &context) const
| Get the value of this uniform parameter as a float.
void | setAsFloat (float value) const
| Set the value of this uniform parameter as a float.
MString | getAsString (const MGeometryList &iterator) const
| Get the value of this uniform parameter as a string.
MString | getAsString (const MHWRender::MDrawContext &context) const
| Get the value of this uniform parameter as a string.
void | setAsString (const MString &value) const
| Set the value of this uniform parameter as a string.
bool | getAsBool (const MGeometryList &iterator) const
| Get the value of this uniform parameter as a boolean value.
bool | getAsBool (const MHWRender::MDrawContext &context) const
| Get the value of this uniform parameter as a boolean value.
void | setAsBool (bool value) const
| Set the value of this uniform parameter as a boolean value.
int | getAsInt (const MGeometryList &iterator) const
| Get the value of this uniform parameter as an integer.
int | getAsInt (const MHWRender::MDrawContext &context) const
| Get the value of this uniform parameter as an integer.
void | setAsInt (int value) const
| Set the value of this uniform parameter as an integer value.
MPlug | getSource () const
| Get the source plug connected to this parameter.
void | setDirty ()
| Mark the data for this parameter as dirty.
## Friends
class | MUniformParameterList Search for all occurrences

## Member Enumeration Documentation

enum DataType

Search for all occurrences

Parameter data types.

Enumerator:

  kTypeUnknown | Search for all occurrences
  kTypeBool | Search for all occurrences
  kTypeInt | Search for all occurrences
  kTypeFloat | Search for all occurrences
  kType1DTexture | Search for all occurrences
  kType2DTexture | Search for all occurrences
  kType3DTexture | Search for all occurrences
  kTypeCubeTexture | Search for all occurrences
  kTypeEnvTexture | Search for all occurrences
  kTypeString | Search for all occurrences

enum DataSemantic

Search for all occurrences

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

Enumerator:

  kSemanticUnknown | Search for all occurrences
  kSemanticObjectDir | Search for all occurrences
  kSemanticWorldDir | Search for all occurrences
  kSemanticViewDir | Search for all occurrences
  kSemanticProjectionDir | Search for all occurrences
  kSemanticObjectPos | Search for all occurrences
  kSemanticWorldPos | Search for all occurrences
  kSemanticViewPos | Search for all occurrences
  kSemanticProjectionPos | Search for all occurrences
  kSemanticColor | Search for all occurrences
  kSemanticNormal | Search for all occurrences
  kSemanticBump | Search for all occurrences
  kSemanticEnvironment | Search for all occurrences
  kSemanticWorldMatrix | Search for all occurrences
  kSemanticWorldInverseMatrix | Search for all occurrences
  kSemanticWorldInverseTransposeMatrix | Search for all occurrences
  kSemanticViewMatrix | Search for all occurrences
  kSemanticViewInverseMatrix | Search for all occurrences
  kSemanticViewInverseTransposeMatrix | Search for all occurrences
  kSemanticProjectionMatrix | Search for all occurrences
  kSemanticProjectionInverseMatrix | Search for all occurrences
  kSemanticProjectionInverseTransposeMatrix | Search for all occurrences
  kSemanticWorldViewMatrix | Search for all occurrences
  kSemanticWorldViewInverseMatrix | Search for all occurrences
  kSemanticWorldViewInverseTransposeMatrix | Search for all occurrences
  kSemanticWorldViewProjectionMatrix | Search for all occurrences
  kSemanticWorldViewProjectionInverseMatrix | Search for all occurrences
  kSemanticWorldViewProjectionInverseTransposeMatrix | Search for all occurrences
  kSemanticColorTexture | Search for all occurrences
  kSemanticNormalTexture | Search for all occurrences
  kSemanticBumpTexture | Search for all occurrences
  kSemanticNormalizationTexture | Search for all occurrences
  kSemanticTime | Search for all occurrences
  kSemanticWorldTransposeMatrix | Search for all occurrences
  kSemanticViewTransposeMatrix | Search for all occurrences
  kSemanticProjectionTransposeMatrix | Search for all occurrences
  kSemanticWorldViewTransposeMatrix | Search for all occurrences
  kSemanticWorldViewProjectionTransposeMatrix | Search for all occurrences
  kSemanticViewProjectionMatrix | Search for all occurrences
  kSemanticViewProjectionInverseMatrix | Search for all occurrences
  kSemanticViewProjectionTransposeMatrix | Search for all occurrences
  kSemanticViewProjectionInverseTransposeMatrix | Search for all occurrences
  kSemanticLocalViewer | Search for all occurrences
  kSemanticViewportPixelSize | Search for all occurrences
  kSemanticBackgroundColor | Search for all occurrences
  kSemanticFrameNumber | Search for all occurrences

## Constructor & Destructor Documentation

MUniformParameter | ( |  | ) |

Create an uninitialised (i.e.

NULL) uniform parameter.

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 (e.g. 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)

## Member Function Documentation

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

Assignment operator.

Parameters:

  [in] | src | Right operand.

const MString & name | ( |  | ) | const

Search for all occurrences

Get the name of this parameter.

Returns:
  The name of this parameter

Examples:
  hlslShader.cpp.

MUniformParameter::DataType type | ( |  | ) | const

Search for all occurrences

Get the type of this parameter.

Returns:
  The type of this parameter

Examples:
  hlslShader.cpp.

MUniformParameter::DataSemantic semantic | ( |  | ) | const

Search for all occurrences

Get the semantic of this parameter.

Returns:
  The semantic of this parameter

unsigned int numRows | ( |  | ) | const

Search for all occurrences

Get the number of rows in this parameter.

Returns:
  The number of rows in this parameter

unsigned int numColumns | ( |  | ) | const

Search for all occurrences

Get the number of columns in this parameter.

Returns:
  The number of columns in this parameter

unsigned int numElements | ( |  | ) | const

Search for all occurrences

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

Returns:
  The number of elements in this parameter

Examples:
  hlslShader.cpp.

void * userData | ( |  | ) | const

Search for all occurrences

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:
  hlslShader.cpp.

void setRangeMin | ( | double | rangeMin | ) | const

Search for all occurrences

Sets the hard range lower bound for a numeric uniform parameter.

Parameters:

  [in] | rangeMin | The lower bound of the range.

void setRangeMax | ( | double | rangeMax | ) | const

Search for all occurrences

Sets the hard range upper bound for a numeric uniform parameter.

Parameters:

  [in] | rangeMax | The upper bound of the range.

void setUIHidden | ( | bool | hiddenState | ) | const

Search for all occurrences

Sets the hidden state of this parameter.

Parameters:

  [in] | hiddenState | True will hide the corresponding attribute in the attribute editor.

bool isATexture | ( |  | ) | const

Search for all occurrences

Test if this parameter stores a texture.

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

Examples:
  hlslShader.cpp.

bool hasChanged | ( | const MGeometryList & | iterator | ) | const

Search for all occurrences

Has the value of this parameter changed since the last time it was accessed? This allows 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:
  hlslShader.cpp.

bool hasChanged | ( | const MHWRender::MDrawContext & | context | ) | const

Search for all occurrences

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

Parameters:

  [in] | context | Draw context being used for render.

Returns:
  true if this parameter's value has changed since the last time its value was accessed. false otherwise.

const float * getAsFloatArray | ( | const MGeometryList & | iterator | ) | const

Search for all occurrences

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:
  A pointer to an array of floating point values for this uniform parameter.

Examples:
  hlslShader.cpp.

const float * getAsFloatArray | ( | const MHWRender::MDrawContext & | context | ) | const

Search for all occurrences

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 context being rendered.

Parameters:

  [in] | context | Draw context being used for render.

Returns:
  A pointer to an array of floating point values for this uniform parameter.

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

Search for all occurrences

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:
  hlslShader.cpp.

float getAsFloat | ( | const MGeometryList & | iterator | ) | const

Search for all occurrences

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.

float getAsFloat | ( | const MHWRender::MDrawContext & | context | ) | const

Search for all occurrences

Get the value of this uniform parameter as a float.

Because some parameters can be shape-dependent, the method requires access to the current context being rendered.

Parameters:

  [in] | context | Draw context being used for render.

Returns:
  The current float value of this uniform parameter.

void setAsFloat | ( | float | value | ) | const

Search for all occurrences

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 getAsString | ( | const MGeometryList & | iterator | ) | const

Search for all occurrences

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:
  hlslShader.cpp.

MString getAsString | ( | const MHWRender::MDrawContext & | context | ) | const

Search for all occurrences

Get the value of this uniform parameter as a string.

Because some parameters can be shape-dependent, the method requires access to the current context being rendered.

Parameters:

  [in] | context | Draw context being used for render.

Returns:
  The current string value of this uniform parameter.

void setAsString | ( | const MString & | value | ) | const

Search for all occurrences

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:
  hlslShader.cpp.

bool getAsBool | ( | const MGeometryList & | iterator | ) | const

Search for all occurrences

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:
  hlslShader.cpp.

bool getAsBool | ( | const MHWRender::MDrawContext & | context | ) | const

Search for all occurrences

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 context being rendered.

Parameters:

  [in] | context | Draw context being used for render.

Returns:
  The current boolean value of this uniform parameter.

void setAsBool | ( | bool | value | ) | const

Search for all occurrences

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:
  hlslShader.cpp.

int getAsInt | ( | const MGeometryList & | iterator | ) | const

Search for all occurrences

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:
  hlslShader.cpp.

int getAsInt | ( | const MHWRender::MDrawContext & | context | ) | const

Search for all occurrences

Get the value of this uniform parameter as an integer.

Because some parameters can be shape-dependent, the method requires access to the current context being rendered.

Parameters:

  [in] | context | Draw context being used for render.

Returns:
  The current integer value of this uniform parameter.

void setAsInt | ( | int | value | ) | const

Search for all occurrences

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:
  hlslShader.cpp.

MPlug getSource | ( |  | ) | const

Search for all occurrences

Get the source plug connected to this parameter.

Other than textures, this will typically be a NULL plug.

Examples:
  hlslShader.cpp.

void setDirty | ( |  | ) |

Search for all occurrences

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:
  hlslShader.cpp.

MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter
MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter MUniformParameter