Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes

MPxDeformerNode Class Reference

This reference page is linked to from the following overview topics: Parent class descriptions, Implementing a Deformer Node, Deformer Node Example, Using the Maya Python API.


Search for all occurrences

Detailed Description

Base class for user defined Deformers.

MPxDeformerNode allows the creation of user-defined deformers. A deformer is a node which takes any number of input geometries, deforms them, and places the output into the output geometry attribute.

If you write a deformer by deriving from MPxDeformerNode, your deformer will derive the benefit of Maya's internal deformer functionality, namely:

Deformers are full dependency nodes and can have attributes and a deform() method. In general, to derive the full benefit of the Maya deformer base class, it is suggested that you do not write your own compute() method. Instead, write the deform() method, which is called by the MPxDeformerNode's compute() method. However, there are some exceptions when you would instead write your own compute(), namely:

In the case where you cannot simply override the deform() method, the following example code shows one possible compute() method implementation. This compute() example creates an iterator for the deformer set corresponding to the output geometry being computed. Note that this sample compute() implementation does not do any deformation, and does not implement handling of the nodeState attribute. If you do choose to override compute() in your node, there is no reason to implement the deform() method, since it will not be called by the base class.

MStatus exampleDeformer::compute(const MPlug& plug, MDataBlock& dataBlock)
{
    MStatus status = MStatus::kUnknownParameter;
    if (plug.attribute() == outputGeom) {
        // get the input corresponding to this output
        //
        unsigned int index = plug.logicalIndex();
        MObject thisNode = this->thisMObject();
        MPlug inPlug(thisNode,input);
        inPlug.selectAncestorLogicalIndex(index,input);
        MDataHandle hInput = dataBlock.inputValue(inPlug);

        // get the input geometry and input groupId
        //
        MDataHandle hGeom = hInput.child(inputGeom);
        MDataHandle hGroup = hInput.child(groupId);
        unsigned int groupId = hGroup.asLong();
        MDataHandle hOutput = dataBlock.outputValue(plug);
        hOutput.copy(hGeom);

        // do the deformation
        //
        MItGeometry iter(hOutput,groupId,false);
        for ( ; !iter.isDone(); iter.next()) {
            MPoint pt = iter.position();

            //
            // insert deformation code here
            //

            iter.setPosition(pt);
        }
        status = MStatus::kSuccess;
    }
    return status;
}

For most deformers, implementing compute() is unnecessary. To create a deformer, derive from this class and override the deform() method as demonstrated in the "offsetNode.cpp" example plug-in. The other methods of the parent class MPxNode may also be overridden to perform standard dependency node capabilities.

When implementing the compute method for a deformer, another consideration is that the input geometry attribute is not cached. This means that all of the inputs will evaluate each time MDataBlock::inputArrayValue is called on "inputGeom". If you only want a single inputGeometry, you can prevent unneeded evaluations by avoiding calls to MDataBlock.inputArrayValue. For example, use the technique shown in the above example or use MDataBlock::outputArrayValue.

Examples:

offsetNode.cpp, and yTwistNode.cpp.

#include <MPxDeformerNode.h>

Inheritance diagram for MPxDeformerNode:
Inheritance graph
[legend]

List of all members.

Public Types

enum   DeformationDetails { kDeformsUVs = (1<<1), kDeformsColors = (1<<2) }
 

Deformation details.

More...

Public Member Functions

  MPxDeformerNode ()
  Class constructor.
virtual  ~MPxDeformerNode ()
  Class destructor.
virtual MPxNode::Type  type () const
  This method returns the type of the node.
virtual MStatus  deform (MDataBlock &block, MItGeometry &iter, const MMatrix &mat, unsigned int multiIndex)
  This method performs the deformation algorithm.
virtual MObject accessoryAttribute () const
  This method returns an MObject for the attribute to which an accessory shape is connected.
virtual MStatus  accessoryNodeSetup (MDagModifier &cmd)
  This method is called by the "deformer -type" command when your node is specified.
float  weightValue (MDataBlock &mblock, unsigned int multiIndex, unsigned int wtIndex)
  This method returns the weightValue stored in the datablock for the given geometry's lattice point/CV/vertex.
void  setUseExistingConnectionWhenSetEditing (bool state)
  This method allows the plugin node to request special treatment during set editing.
MStatus  setDeformationDetails (unsigned int flags)
  This method allows the plug-in node to inform the system that it intends to deform components other than just positions.
unsigned int  getDeformationDetails (MStatus *ReturnStatus=NULL)
  Retrieves the value set by setDeformationDetails().
virtual void  setModifiedCallback (MSelectionList &list, bool listAdded)
  This callback method can be overriden and is called whenever the set this deformer is operating on is modified.

Static Public Member Functions

static const char *  className ()
  Returns the name of this class.

Static Public Attributes

static MObject  input
  input attribute, multi
static MObject  inputGeom
  input geometry attribute
static MObject  groupId
  input group id attribute
static MObject  outputGeom
  geometry output attribute
static MObject  weightList
  weight list attribute, multi
static MObject  weights
  weight attribute, multi
static MObject  envelope
  envelope attribute

Member Enumeration Documentation

Deformation details.

Enumerator:
kDeformsUVs 

The deformer will deform UVs.

kDeformsColors 

The deformer will deform colors.


Member Function Documentation

MPxNode::Type type ( ) const [virtual]

This method returns the type of the node.

This method should not be overridden by the user. It will return MPxNode::kDeformerNode.

Returns:
The type of node

Reimplemented from MPxNode.

MStatus deform ( MDataBlock block,
MItGeometry iterator,
const MMatrix matrix,
unsigned int  multiIndex 
) [virtual]

This method performs the deformation algorithm.

A status code of MS::kSuccess should be returned unless there was a problem during the deformation, such as insufficient memory or required input data is missing or invalid.

NOTE: the geometry iterator passed to this method is in local space and not world space. To convert points to world space use the matrix that is suppied.

Parameters:
[in] block the node's datablock.
[in] iterator an iterator for the current geometry being deformed.
[in] matrix the geometry's world space transformation matrix.
[in] multiIndex the index corresponding to the requested output geometry.
Returns:
Status code
Status Codes:
Examples:
offsetNode.cpp, and yTwistNode.cpp.
MObject & accessoryAttribute ( ) const [virtual]

This method returns an MObject for the attribute to which an accessory shape is connected.

If the accessory shape is deleted, the deformer node will automatically be deleted.

If your node has no associated shape, there is no need to override this method.

Returns:
The accessory attribute
Examples:
offsetNode.cpp.
MStatus accessoryNodeSetup ( MDagModifier cmd ) [virtual]

This method is called by the "deformer -type" command when your node is specified.

This method can be used to create and attach accessory nodes if your plugin node requires them. To do so, override this method, and provide the creation and attachment commands to the MDagModifier that is passed as input to the method.

If your node has no associated nodes, there is no need to override this method.

Parameters:
[in] cmd the dag modifier to which the method will add commands
Returns:
Status code
Examples:
offsetNode.cpp.
float weightValue ( MDataBlock block,
unsigned int  multiIndex,
unsigned int  wtIndex 
)

This method returns the weightValue stored in the datablock for the given geometry's lattice point/CV/vertex.

Parameters:
[in] block the datablock for the node
[in] multiIndex the index corresponding to the geometry
[in] wtIndex the index corresponding to the component
Returns:
Weight
void setUseExistingConnectionWhenSetEditing ( bool  state )

This method allows the plugin node to request special treatment during set editing.

It controls the connection behavior if all of a geometry's points are removed from the deformer set, and then points are subsequently added back in to the set again. By default, Maya will reconnect the deformer to the shape using a new input/output index. If this method is called in the custom deformer's postConstructor method and the state is set to true, the deformer will attempt to use the original input/output index when reconnecting to the shape.

Parameters:
[in] state whether or not to use the existing connection
MStatus setDeformationDetails ( unsigned int  flags )

This method allows the plug-in node to inform the system that it intends to deform components other than just positions.

It should typically be called in advance of any deformation taking place (e.g. in postConstructor()), not in the deform() method. If it is called from deform(), the setting will take effect the next time the DG causes the deformation to be calculated.

Parameters:
[in] flags Bitwise OR of flags from the DeformationDetails enum
Returns:
Status code
Status Codes:
unsigned int getDeformationDetails ( MStatus ReturnStatus = NULL )

Retrieves the value set by setDeformationDetails().

See the documentation of that method for the interpretation of the value.

Parameters:
[out] ReturnStatus Status code.
Returns:
The deformation details
Status Codes:
void setModifiedCallback ( MSelectionList list,
bool  listAdded 
) [virtual]

This callback method can be overriden and is called whenever the set this deformer is operating on is modified.

It passes in a selection list of items that are either being added/removed.

Parameters:
[in] list list of items added/removed
[in] listAdded whether the list is being added or removed to the set.
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

Reimplemented from MPxNode.


MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode
MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode MPxDeformerNode