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: Dependency Graph Plug-in Basics, Example: Voxelizer Node, Example: Bounding Box Deformer, Parent class descriptions, MPxNode and its derived classes, Deformers and Topology, 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 MObjectaccessoryAttribute () 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]blockthe node's datablock.
[in]iteratoran iterator for the current geometry being deformed.
[in]matrixthe geometry's world space transformation matrix.
[in]multiIndexthe 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]cmdthe 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]blockthe datablock for the node
[in]multiIndexthe index corresponding to the geometry
[in]wtIndexthe 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]statewhether 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]flagsBitwise 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]ReturnStatusStatus 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]listlist of items added/removed
[in]listAddedwhether 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