MVaryingParameter Class Reference
[OpenMayaRender - API module for rendering]

#include <MVaryingParameter.h>

List of all members.


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:

hlslShader.cpp, and hlslShader.h.


Public Types

enum   MVaryingParameterType { kInvalidParameter = -1, kStructure = 0, kFloat }
  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 ()
  MVaryingParameter (const MString &name, MVaryingParameterType type, int minElements=1, int maxElements=1, MVaryingParameterSemantic semantic=kNoSemantic, bool invertTexCoords=false)
  ~MVaryingParameter ()
const MVaryingParameter operator= (const MVaryingParameter &other)
const MString name () const
MVaryingParameter::MVaryingParameterType  type () const
MVaryingParameter::MVaryingParameterSemantic  semantic () const
MStatus  getBuffer (MGeometry &geometry, const void *&data, unsigned int &elements, unsigned int &count) const
MVaryingParameter::MVaryingParameterSemantic  getSourceType () const
MString  getSourceSetName () const
MStatus  setSource (MVaryingParameter::MVaryingParameterSemantic type, const MString &setName)
unsigned int  getElementSize () const
unsigned int  getMaximumStride () const
MStatus  addElement (const MVaryingParameter &child)
unsigned int  numElements () const
MVaryingParameter  getElement (unsigned int i) const
MStatus  removeElements ()

Friends

class  MVaryingParameterList

Member Enumeration Documentation

Parameter types.

Enumerator:
kInvalidParameter   
kStructure   
kFloat   

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

Enumerator:
kNoSemantic   
kPosition   
kNormal   
kTexCoord   
kColor   
kWeight   
kTangent   
kBinormal   

Constructor & Destructor Documentation

MVaryingParameter::MVaryingParameter (  ) 

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

MVaryingParameter::MVaryingParameter ( const MString name,
MVaryingParameterType  type,
int  minElements = 1,
int  maxElements = 1,
MVaryingParameterSemantic  semantic = kNoSemantic,
bool  invertTexCoords = false  
)

Create a new geometry 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]  minElements  specifies the minimum number of elements 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 minElements value of 3, and a maxElements value of 4. This value is ignored for structures and elements inside structures (elements inside a structure are always maxElements size).
[in]  maxElements  specifies the maximum number of elements of the specified atomic type that should be used to populate this parameter. See minElements for more information. This value is ignored for structures.
[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.

MVaryingParameter::~MVaryingParameter (  ) 

Class destructor.


Member Function Documentation

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

Assignment operator

const MString & MVaryingParameter::name (  )  const

Get the name of this parameter

Returns:
The name of this parameter
Examples:

MVaryingParameter::MVaryingParameterType MVaryingParameter::type (  )  const

Get the type of this parameter

Returns:
The type of this parameter

MVaryingParameter::MVaryingParameterSemantic MVaryingParameter::semantic (  )  const

Get the semantic of this parameter

Returns:
The semantic of this parameter
Examples:

MStatus MVaryingParameter::getBuffer ( MGeometry geometry,
const void *&  data,
unsigned int &  elements,
unsigned int &  count  
) const

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

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

MVaryingParameter::MVaryingParameterSemantic MVaryingParameter::getSourceType (  )  const

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

MString MVaryingParameter::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

MStatus MVaryingParameter::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]  type  the type of data to populate this parameter with
[in]  setName  the specific data set to use for parameter types which support data sets, such as UV and color.
Returns:

unsigned int MVaryingParameter::getElementSize (  )  const

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

Returns:
The size in bytes of one element of this parameter.

unsigned int MVaryingParameter::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 MVaryingParameter::addElement ( const MVaryingParameter child  ) 

Add a child element to this parameter. This operation is only valid for parameters of type kStructure.

Parameters:
[in]  child  the parameter to add to the structure.
Returns:

unsigned int MVaryingParameter::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:

MVaryingParameter MVaryingParameter::getElement ( unsigned int  i  )  const

Get an element within a structure. This operation is only valid for parameters of type kStructure.

Parameters:
[in]  i  The index of the structure element to return.
Returns:
The structure element. This will be a NULL element if an invalid index was specified.
Examples:

MStatus MVaryingParameter::removeElements (  ) 

Remove all child elements from a structure. This operation is only valid for parameters of type kStructure.

Returns:

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