#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:: dx11Shader/dx11Shader.cpp, dx11Shader/dx11ShaderUniformParamBuilder.cpp, dx11Shader/dx11ShaderUniformParamBuilder.h, glslShader/GLSLShader.cpp, glslShader/GLSLShader.h, hlslShader/hlslShader.cpp, and hlslShader/hlslShader.h.

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, 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 MUniformParameter &	operator= (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

enum DataSemantic

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
kSemanticHWSPrimitiveBase
kSemanticHWSPrimitiveCountPerInstance
kSemanticHWSObjectLevel
kSemanticHWSFaceLevel
kSemanticHWSEdgeLevel
kSemanticHWSVertexLevel
kSemanticHWSOccluder
kSemanticHWSFrontCCW
kSemanticHWSInstancedDraw
kSemanticHWSHighlighting

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.

MString name ( ) const

Get the name of this parameter.

Returns: The name of this parameter

Examples:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

MUniformParameter::DataType type ( ) const

Get the type of this parameter.

Returns: The type of this parameter

Examples:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

MUniformParameter::DataSemantic semantic ( ) const

Get the semantic of this parameter.

Returns: The semantic of this parameter

Examples:: dx11Shader/dx11Shader.cpp, and glslShader/GLSLShader.cpp.

unsigned int numRows ( ) const

Get the number of rows in this parameter.

Returns: The number of rows in this parameter

Examples:: dx11Shader/dx11Shader.cpp.

unsigned int numColumns ( ) const

Get the number of columns in this parameter.

Returns: The number of columns in this parameter

Examples:: dx11Shader/dx11Shader.cpp.

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:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

void setRangeMin ( double rangeMin ) const

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

Parameters

[in] rangeMin The lower bound of the range.

Examples:: hlslShader/hlslShader.cpp.

void setRangeMax ( double rangeMax ) const

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

Parameters

[in] rangeMax The upper bound of the range.

Examples:: hlslShader/hlslShader.cpp.

void setSoftRangeMin ( double softRangeMin ) const

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

Parameters

[in] softRangeMin The lower bound of the slider.

void setSoftRangeMax ( double softRangeMax ) const

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

Parameters

[in] softRangeMax The upper bound of the slider.

void setUIHidden ( bool hiddenState ) const

Sets the hidden state of this parameter.

Parameters

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

Examples:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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] fieldNames A 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] keyable True 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:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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] 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:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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] 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

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:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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] 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

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:: dx11Shader/dx11Shader.cpp, and hlslShader/hlslShader.cpp.

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] iterator the current shape being rendered.

Returns: The current float value of this uniform parameter.

Examples:: dx11Shader/dx11Shader.cpp.

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] context Draw 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] value the 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] iterator the current shape being rendered.

Returns: The current string value of this uniform parameter.

Examples:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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] context Draw 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] value the new string value for this parameter.

Examples:: dx11Shader/dx11Shader.cpp, and hlslShader/hlslShader.cpp.

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] iterator the current shape being rendered.

Returns: The current boolean value of this uniform parameter.

Examples:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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] context Draw 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] value the new value for this parameter.

Examples:: dx11Shader/dx11Shader.cpp, and hlslShader/hlslShader.cpp.

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] iterator the current shape being rendered.

Returns: The current integer value of this uniform parameter.

Examples:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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] context Draw 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] value the new value for this parameter.

Examples:: hlslShader/hlslShader.cpp.

void setUINiceName ( const MString & name )

Sets the UI Nice Name for the attribute.

Parameters

[in] name The name that will be displayed in the Attribute Editor

Examples:: glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

MPlug getSource ( ) const

Get the source plug connected to this parameter.

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

Examples:: dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.

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

The documentation for this class was generated from the following files:

MUniformParameter.h
MUniformParameter.cpp

MUniformParameter Class Reference

Class Description

Public Types

Public Member Functions

Friends

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation