MUniformParameter Class Reference

#include <MUniformParameter.h>

Class 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:

Public Types

enum  DataType {
  kTypeUnknown, kTypeBool, kTypeInt, kTypeFloat,
  kType1DTexture, kType2DTexture, kType3DTexture, kTypeCubeTexture,
  kTypeEnvTexture, kTypeString, kTypeEnum
}
 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,
  kSemanticTranspDepthTexture, kSemanticOpaqueDepthTexture, kSemanticTime, kSemanticWorldTransposeMatrix,
  kSemanticViewTransposeMatrix, kSemanticProjectionTransposeMatrix, kSemanticWorldViewTransposeMatrix, kSemanticWorldViewProjectionTransposeMatrix,
  kSemanticViewProjectionMatrix, kSemanticViewProjectionInverseMatrix, kSemanticViewProjectionTransposeMatrix, kSemanticViewProjectionInverseTransposeMatrix,
  kSemanticLocalViewer, kSemanticViewportPixelSize, kSemanticBackgroundColor, kSemanticFrameNumber,
  kSemanticNearClipPlane, kSemanticFarClipPlane, kSemanticHWSPrimitiveBase, kSemanticHWSPrimitiveCountPerInstance,
  kSemanticHWSObjectLevel, kSemanticHWSFaceLevel, kSemanticHWSEdgeLevel, kSemanticHWSVertexLevel,
  kSemanticHWSOccluder, kSemanticHWSFrontCCW, kSemanticHWSInstancedDraw, kSemanticHWSHighlighting
}
 Parameter semantics (i.e. what the parameter represents). More...
 

Public Member Functions

 MUniformParameter ()
 Create an uninitialised (i.e. More...
 
 MUniformParameter (const MString &name, DataType type, DataSemantic semantic, unsigned int numRows=1, unsigned int numColumns=1, void *userData=NULL)
 Create a new uniform parameter. More...
 
 ~MUniformParameter ()
 Class destructor.
 
const MUniformParameteroperator= (const MUniformParameter &other)
 Assignment operator. More...
 
MString name () const
 Get the name of this parameter. More...
 
MUniformParameter::DataType type () const
 Get the type of this parameter. More...
 
MUniformParameter::DataSemantic semantic () const
 Get the semantic of this parameter. More...
 
unsigned int numRows () const
 Get the number of rows in this parameter. More...
 
unsigned int numColumns () const
 Get the number of columns in this parameter. More...
 
unsigned int numElements () const
 Get the number of elements in this parameter (including rows and columns) More...
 
void * userData () const
 Get the user data for this parameter. More...
 
void setRangeMin (double rangeMin) const
 Sets the hard range lower bound for a numeric uniform parameter. More...
 
void setRangeMax (double rangeMax) const
 Sets the hard range upper bound for a numeric uniform parameter. More...
 
void setSoftRangeMin (double softRangeMin) const
 Sets the soft range lower bound for a numeric uniform parameter. More...
 
void setSoftRangeMax (double softRangeMax) const
 Sets the soft range upper bound for a numeric uniform parameter. More...
 
void setUIHidden (bool hiddenState) const
 Sets the hidden state of this parameter. More...
 
bool UIHidden () const
 Gets the hidden state of this parameter. More...
 
void setEnumFieldNames (const MString &fieldNames)
 Sets the field names of an enum attribute. More...
 
void setKeyable (bool keyable) const
 Sets the keyable state of this parameter. More...
 
bool keyable () const
 Gets the keyable state of this parameter. More...
 
bool isATexture () const
 Test if this parameter stores a texture. More...
 
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. More...
 
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. More...
 
const float * getAsFloatArray (const MGeometryList &iterator) const
 Get the value of this uniform parameter as one or more floating point values. More...
 
const float * getAsFloatArray (const MHWRender::MDrawContext &context) const
 Get the value of this uniform parameter as one or more floating point values. More...
 
void setAsFloatArray (const float *value, unsigned int maxElements) const
 Set the value of this uniform parameter as one or more floating point values. More...
 
float getAsFloat (const MGeometryList &iterator) const
 Get the value of this uniform parameter as a float. More...
 
float getAsFloat (const MHWRender::MDrawContext &context) const
 Get the value of this uniform parameter as a float. More...
 
void setAsFloat (float value) const
 Set the value of this uniform parameter as a float. More...
 
MString getAsString (const MGeometryList &iterator) const
 Get the value of this uniform parameter as a string. More...
 
MString getAsString (const MHWRender::MDrawContext &context) const
 Get the value of this uniform parameter as a string. More...
 
void setAsString (const MString &value) const
 Set the value of this uniform parameter as a string. More...
 
bool getAsBool (const MGeometryList &iterator) const
 Get the value of this uniform parameter as a boolean value. More...
 
bool getAsBool (const MHWRender::MDrawContext &context) const
 Get the value of this uniform parameter as a boolean value. More...
 
void setAsBool (bool value) const
 Set the value of this uniform parameter as a boolean value. More...
 
int getAsInt (const MGeometryList &iterator) const
 Get the value of this uniform parameter as an integer. More...
 
int getAsInt (const MHWRender::MDrawContext &context) const
 Get the value of this uniform parameter as an integer. More...
 
void setAsInt (int value) const
 Set the value of this uniform parameter as an integer value. More...
 
void setUINiceName (const MString &name)
 Sets the UI Nice Name for the attribute. More...
 
MPlug getPlug () const
 Get the plug managed by this parameter.
 
MPlug getSource () const
 Get the source plug connected to this parameter. More...
 
void setDirty ()
 Mark the data for this parameter as dirty. More...
 

Friends

class MUniformParameterList
 

Member Enumeration Documentation

enum DataType

Parameter data types.

Enumerator
kTypeUnknown 

 

kTypeBool 

 

kTypeInt 

 

kTypeFloat 

 

kType1DTexture 

 

kType2DTexture 

 

kType3DTexture 

 

kTypeCubeTexture 

 

kTypeEnvTexture 

 

kTypeString 

 

kTypeEnum 

 

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 

 

kSemanticTranspDepthTexture 

 

kSemanticOpaqueDepthTexture 

 

kSemanticTime 

 

kSemanticWorldTransposeMatrix 

 

kSemanticViewTransposeMatrix 

 

kSemanticProjectionTransposeMatrix 

 

kSemanticWorldViewTransposeMatrix 

 

kSemanticWorldViewProjectionTransposeMatrix 

 

kSemanticViewProjectionMatrix 

 

kSemanticViewProjectionInverseMatrix 

 

kSemanticViewProjectionTransposeMatrix 

 

kSemanticViewProjectionInverseTransposeMatrix 

 

kSemanticLocalViewer 

 

kSemanticViewportPixelSize 

 

kSemanticBackgroundColor 

 

kSemanticFrameNumber 

 

kSemanticNearClipPlane 

 

kSemanticFarClipPlane 

 

kSemanticHWSPrimitiveBase 

 

kSemanticHWSPrimitiveCountPerInstance 

 

kSemanticHWSObjectLevel 

 

kSemanticHWSFaceLevel 

 

kSemanticHWSEdgeLevel 

 

kSemanticHWSVertexLevel 

 

kSemanticHWSOccluder 

 

kSemanticHWSFrontCCW 

 

kSemanticHWSInstancedDraw 

 

kSemanticHWSHighlighting 

 

Constructor & Destructor Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN 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]namethe 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]typethe 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]semanticspecifies 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]numRowsspecifies the number of row of the specified type to include (e.g. a vector would have 3 floats)
[in]numColumnsspecifies the number of columns of the specified type to include (e.g. a matrix would have 4 rows and 4 columns of floats)
[in]userDataopaque 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]srcRight operand.
MString name ( ) const

Get the name of this parameter.

Returns
The name of this parameter
+ Examples:

Get the type of this parameter.

Returns
The type of this parameter
+ Examples:
MUniformParameter::DataSemantic semantic ( ) const

Get the semantic of this parameter.

Returns
The semantic of this parameter
+ Examples:
unsigned int numRows ( ) const

Get the number of rows in this parameter.

Returns
The number of rows in this parameter
+ Examples:
unsigned int numColumns ( ) const

Get the number of columns in this parameter.

Returns
The number of columns in this parameter
+ Examples:
unsigned int numElements ( ) const

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

Returns
The number of elements in this parameter
+ Examples:
void * 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:
void setRangeMin ( double  rangeMin) const

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

Parameters
[in]rangeMinThe lower bound of the range.
+ Examples:
void setRangeMax ( double  rangeMax) const

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

Parameters
[in]rangeMaxThe upper bound of the range.
+ Examples:
void setSoftRangeMin ( double  softRangeMin) const

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

Parameters
[in]softRangeMinThe lower bound of the slider.
void setSoftRangeMax ( double  softRangeMax) const

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

Parameters
[in]softRangeMaxThe upper bound of the slider.
void setUIHidden ( bool  hiddenState) const

Sets the hidden state of this parameter.

Parameters
[in]hiddenStateTrue will hide the corresponding attribute in the attribute editor.
+ Examples:
bool UIHidden ( ) const

Gets the hidden state of this parameter.

Returns
True if the corresponding attribute is hidden in the attribute editor.
void setEnumFieldNames ( const MString fieldNames)

Sets the field names of an enum attribute.

The format of the string is the same as returned by the MEL command `attributeQuery -listEnum`.

Parameters
[in]fieldNamesA string of colon ":" delimited field names which can specify an index value separated by an equal sign "=". The indexing starts at zero and the index value of an item when it is not explicitely specified is the index of the previous item (if any) incremented by one. Example: "Shaded:Wireframe=8:Bounding Box" defines 3 values with index 0, 8, and 9.
void setKeyable ( bool  keyable) const

Sets the keyable state of this parameter.

Parameters
[in]keyableTrue if the attribute should be keyable
bool keyable ( ) const

Gets the keyable state of this parameter.

Returns
True if the corresponding attribute is keyable.
bool isATexture ( ) const

Test if this parameter stores a texture.

Returns
true if this parameter represents a texture, false otherwise.
+ Examples:
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.

Parameters
[in]iteratorthe current shape being rendered.
Returns
true if this parameter's value has changed since the last time its value was accessed. false otherwise.
+ Examples:
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.

Parameters
[in]contextDraw 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

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]iteratorthe current shape being rendered.
Returns
A pointer to an array of floating point values for this uniform parameter.
+ Examples:
const float * getAsFloatArray ( const MHWRender::MDrawContext context) 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 context being rendered.

Parameters
[in]contextDraw 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

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]valuea pointer an array of floats holding the new floating point value(s) for this parameter.
[in]maxElementsthe maximum number of elements in the value array.
+ Examples:
float 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]iteratorthe current shape being rendered.
Returns
The current float value of this uniform parameter.
+ Examples:
float getAsFloat ( const MHWRender::MDrawContext context) 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 context being rendered.

Parameters
[in]contextDraw context being used for render.
Returns
The current float value of this uniform parameter.
void 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]valuethe new float value for this parameter.
MString 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]iteratorthe current shape being rendered.
Returns
The current string value of this uniform parameter.
+ Examples:
MString getAsString ( const MHWRender::MDrawContext context) 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 context being rendered.

Parameters
[in]contextDraw context being used for render.
Returns
The current string value of this uniform parameter.
void 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]valuethe new string value for this parameter.
+ Examples:
bool 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]iteratorthe current shape being rendered.
Returns
The current boolean value of this uniform parameter.
+ Examples:
bool getAsBool ( const MHWRender::MDrawContext context) 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 context being rendered.

Parameters
[in]contextDraw context being used for render.
Returns
The current boolean value of this uniform parameter.
void 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]valuethe new value for this parameter.
+ Examples:
int 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]iteratorthe current shape being rendered.
Returns
The current integer value of this uniform parameter.
+ Examples:
int getAsInt ( const MHWRender::MDrawContext context) 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 context being rendered.

Parameters
[in]contextDraw context being used for render.
Returns
The current integer value of this uniform parameter.
void 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]valuethe new value for this parameter.
+ Examples:
void setUINiceName ( const MString name)

Sets the UI Nice Name for the attribute.

Parameters
[in]nameThe name that will be displayed in the Attribute Editor
+ Examples:
MPlug getSource ( ) const

Get the source plug connected to this parameter.

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

+ Examples:
void 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:

The documentation for this class was generated from the following files:
  • MUniformParameter.h
  • MUniformParameter.cpp