C++ API Reference
MVaryingParameter Class Reference

Geometric data cache. More...

#include <MVaryingParameter.h>

Public Types

enum  MVaryingParameterType {
  kInvalidParameter = -1, kStructure = 0, kFloat, kDouble,
  kChar, kUnsignedChar, kInt16, kUnsignedInt16,
  kInt32, kUnsignedInt32
}
 Parameter types. More...
 
enum  MVaryingParameterSemantic {
  kNoSemantic = 0, kPosition, kNormal, kTexCoord,
  kColor, kWeight, kTangent = kWeight + 2, kBinormal
}
 Parameter semantics (i.e. what the parameter represents). More...
 

Public Member Functions

 MVaryingParameter ()
 Create an uninitialised (i.e. More...
 
 MVaryingParameter (const MString &name, MVaryingParameterType type, int minDimension=1, int maxDimension=1, MVaryingParameterSemantic semantic=kNoSemantic, bool invertTexCoords=false, const MString &semanticName="")
 Create a new varying parameter. More...
 
 MVaryingParameter (const MString &name, MVaryingParameterType type, int minDimension, int maxDimension, int dimension, MVaryingParameterSemantic semantic=kNoSemantic, const MString &destinationSet="", bool invertTexCoords=false, const MString &semanticName="")
 Create a new varying parameter. More...
 
 MVaryingParameter (const MVaryingParameter &src)
 Copy Constructor.
 
 ~MVaryingParameter ()
 Class destructor.
 
const MVaryingParameteroperator= (const MVaryingParameter &other)
 Assignment operator. More...
 
const MString name () const
 Get the name of this parameter. More...
 
MVaryingParameter::MVaryingParameterType type () const
 Get the type of this parameter. More...
 
MVaryingParameter::MVaryingParameterSemantic semantic () const
 Get the semantic of this parameter. More...
 
const MString semanticName () const
 Get the semantic name assigned to this parameter The semanticName is used to identify a custom vertex stream request in order to fill the stream with the appropriate data requested by a shader override. More...
 
MString destinationSet () const
 Get the destination Set of this parameter. More...
 
int dimension () const
 Get the dimension of this parameter. More...
 
MStatus getBuffer (MGeometryLegacy &geometry, const void *&data, unsigned int &elements, unsigned int &count) const
 Get the data for this parameter as a system memory buffer. More...
 
MVaryingParameter::MVaryingParameterSemantic getSourceType () const
 Get the type of data (e.g. More...
 
MString getSourceSetName () const
 If the current data type supports data sets (e.g. More...
 
MStatus setSource (MVaryingParameter::MVaryingParameterSemantic type, const MString &setName)
 While the source of geometry parameters is usually configured by the artist through Maya's user interface, this method allows you to programatically set the source of a geometry parameter, including both the data type (e.g. More...
 
unsigned int getElementSize () const
 Get the size in bytes of one element of this parameter. More...
 
unsigned int getMaximumStride () const
 Get the maximum stride of this parameter in bytes. More...
 
MStatus addElement (const MVaryingParameter &child)
 Add a child element to this parameter. More...
 
unsigned int numElements () const
 Get the number of elements in this structure. More...
 
MVaryingParameter getElement (unsigned int i) const
 Get an element within a structure. More...
 
MStatus removeElements ()
 Remove all child elements from a structure. More...
 
unsigned int getUpdateId () const
 Get the update id. More...
 

Detailed Description

Geometric data cache.

The MVaryingParameter class provides a high-level interface to hardware shader varying parameters. By defining your shader's varying data through this class, you allow Maya to handle the attributes, editing, serialisation, requirements setup, and cache management 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 AEhwShaderTemplateParameters 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 $yourShaderNameTemplateInitialised = 0;
global proc AEyourShaderNameTemplate ( string $node )
{
global int $yourShaderNameTemplateInitialised;
if( $yourShaderNameTemplateInitialised == 0)
{
source "AEhwShaderTemplate.mel";
$yourShaderNameTemplateInitialised = 1;
}
AEhwShaderTemplateHeader( $node);
// Insert custom attributes between the swatch and the parameters here
AEhwShaderTemplateParameters( $node);
// Insert custom attributes after the parameters here
AEhwShaderTemplateFooter( $node);
}
Examples:
dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, hlslShader/hlslShader.cpp, and hlslShader/hlslShader.h.

Member Enumeration Documentation

Parameter types.

Enumerator
kInvalidParameter 

 

kStructure 

 

kFloat 

 

kDouble 

 

kChar 

 

kUnsignedChar 

 

kInt16 

 

kUnsignedInt16 

 

kInt32 

 

kUnsignedInt32 

 

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

Enumerator
kNoSemantic 

 

kPosition 

 

kNormal 

 

kTexCoord 

 

kColor 

 

kWeight 

 

kTangent 

 

kBinormal 

 

Constructor & Destructor Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN MVaryingParameter ( )

Create an uninitialised (i.e.

NULL) varying parameter.

MVaryingParameter ( const MString name,
MVaryingParameterType  type,
int  minDimension = 1,
int  maxDimension = 1,
MVaryingParameterSemantic  semantic = kNoSemantic,
bool  invertTexCoords = false,
const MString semanticName = "" 
)

Create a new varying 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 maxDimension value (e.g. 4).
[in]minDimensionspecifies the minimum vector dimension of the specified atomic type that should be used to populate this parameter. Many hardware channels allow binding of a variable number of elements per value; for example you can bind a stream of float3s or float4s to a color register. In this case, you would specify a minDimension value of 3, and a maxDimension value of 4. This value is ignored for structures and elements inside structures (elements inside a structure are always maxDimension size).
[in]maxDimensionspecifies the maximum vector dimension of the specified atomic type that should be used to populate this parameter. See minDimension for more information. This value is ignored for structures.
[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]invertTexCoordsIf true the V texture coordinate will be inverted, so that it begins at the top of the texture rather than the bottom.
[in]semanticNameThe semanticName is used to identify a custom vertex stream request in order to fill the stream with the appropriate data requested by a shader override.
MVaryingParameter ( const MString name,
MVaryingParameterType  type,
int  minDimension,
int  maxDimension,
int  dimension,
MVaryingParameterSemantic  semantic = kNoSemantic,
const MString destinationSet = "",
bool  invertTexCoords = false,
const MString semanticName = "" 
)

Create a new varying 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 maxDimension value (e.g. 4).
[in]minDimensionspecifies the minimum vector dimension of the specified atomic type that should be used to populate this parameter. Many hardware channels allow binding of a variable number of elements per value; for example you can bind a stream of float3s or float4s to a color register. In this case, you would specify a minDimension value of 3, and a maxDimension value of 4. This value is ignored for structures and elements inside structures (elements inside a structure are always maxDimension size).
[in]maxDimensionspecifies the maximum vector dimension of the specified atomic type that should be used to populate this parameter. See minDimension for more information. This value is ignored for structures.
[in]dimensionspecifies the preferred dimension of the specified atomic type that should be used to populate this parameter. This value is ignored for structures.
[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]destinationSetspecifies the name of the destination data sets (e.g. uv sets 1,2,3,... color sets) we would like this Varying parameter bound to. For instance we could have a kTexCoord semantic with a destination data set of "map2" that would bind to the second uv corrdinate set. Ignored for Vertex and Normals.
[in]invertTexCoordsIf true the V texture coordinate will be inverted, so that it begins at the top of the texture rather than the bottom.
[in]semanticNameThe semanticName is used to identify a custom vertex stream request in order to fill the stream with the appropriate data requested by a shader override.

Member Function Documentation

const MVaryingParameter & operator= ( const MVaryingParameter src)

Assignment operator.

Parameters
[in]srcRight operand.
const 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.

Get the type of this parameter.

Returns
The type of this parameter
Examples:
dx11Shader/dx11Shader.cpp.

Get the semantic of this parameter.

Returns
The semantic of this parameter
Examples:
dx11Shader/dx11Shader.cpp, and hlslShader/hlslShader.cpp.
const MString semanticName ( ) const

Get the semantic name assigned to this parameter The semanticName is used to identify a custom vertex stream request in order to fill the stream with the appropriate data requested by a shader override.

Returns
The semantic name of this parameter
Examples:
dx11Shader/dx11Shader.cpp.
MString destinationSet ( ) const

Get the destination Set of this parameter.

Returns
The destination Set of this parameter
Examples:
dx11Shader/dx11Shader.cpp.
int dimension ( ) const

Get the dimension of this parameter.

Returns
The dimension of this parameter
Examples:
dx11Shader/dx11Shader.cpp.
MStatus getBuffer ( MGeometryLegacy geometry,
const void *&  data,
unsigned int &  elements,
unsigned int &  count 
) const

Get the data for this parameter as a system memory buffer.

Parameters
[in]geometrythe geometry cache the data should be retrieved from. This corresponds to the shape (e.g. mesh) you want the data for.
[out]datareturns a pointer to the data (or NULL if the parameter is not available).
[in]elementsthe number of elements specified for this parameter (e.g. is it 3 floats or 4 floats?)
[in]countthe number of values returned for this parameter (e.g. there are 426 normals)
Returns
  • MS::kFailure if the parameter could not be retrieved.
  • MS::kSuccess otherwise.

Get the type of data (e.g.

position, normal, uv) currently populating this parameter. This method will only return a useful value when called on leaf-level parameters (e.g. structures do not have sources, only the elements of a structure have sources).

Returns
The current data type populating of this parameter
Examples:
dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.
MString getSourceSetName ( ) const

If the current data type supports data sets (e.g.

uv sets, color sets), get the name of the data set populating this parameter. This method will only return a useful value when called on leaf-level parameters (e.g. structures do not have sources, only the elements of a structure have sources).

Returns
The current source set of this parameter
Examples:
dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.
MStatus setSource ( MVaryingParameter::MVaryingParameterSemantic  type,
const MString setName 
)

While the source of geometry parameters is usually configured by the artist through Maya's user interface, this method allows you to programatically set the source of a geometry parameter, including both the data type (e.g.

position, normal, etc) and an optional set name (e.g. UV set "map1"). This is useful for implementing custom default values or shader operations.

Parameters
[in]typethe type of data to populate this parameter with
[in]setNamethe specific data set to use for parameter types which support data sets, such as UV and color.
Returns
  • MS::kFailure if the source could not be set (e.g. the parameter is invalid).
  • MS::kSuccess otherwise.
unsigned int getElementSize ( ) const

Get the size in bytes of one element of this parameter.

Returns
The size in bytes of one element of this parameter.
Examples:
dx11Shader/dx11Shader.cpp.
unsigned int getMaximumStride ( ) const

Get the maximum stride of this parameter in bytes.

For parameter that accept a range of element counts, this corresponds to the maximum number of elements the parameter supports.

Returns
The maximum stride of this parameter in bytes.
MStatus addElement ( const MVaryingParameter child)

Add a child element to this parameter.

This operation is only valid for parameters of type kStructure.

Parameters
[in]childthe parameter to add to the structure.
Returns
  • MS::kFailure if an error occured (e.g. the parameter is not a structure)
  • MS::kSuccess otherwise.
unsigned int numElements ( ) const

Get the number of elements in this structure.

This operation is only valid for parameters of type kStructure.

Returns
The number of elements in this structure.
Examples:
hlslShader/hlslShader.cpp.
MVaryingParameter getElement ( unsigned int  i) const

Get an element within a structure.

This operation is only valid for parameters of type kStructure.

Parameters
[in]iThe index of the structure element to return.
Returns
The structure element. This will be a NULL element if an invalid index was specified.
Examples:
dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and hlslShader/hlslShader.cpp.
MStatus removeElements ( )

Remove all child elements from a structure.

This operation is only valid for parameters of type kStructure.

Returns
  • MS::kFailure if an error occured (e.g. the parameter is not a structure)
  • MS::kSuccess otherwise.
unsigned int getUpdateId ( ) const

Get the update id.

The update id is increased every time the parameter sources or sourceSet are changed. A plugin can compare the update id value between subsequent calls to this function to know if the source has changed since the last call.

Returns
The update id
Examples:
dx11Shader/dx11Shader.cpp, and glslShader/GLSLShader.cpp.

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