MPxDeformerNode Class Reference
[OpenMayaAnim - API module for animation, Proxy classes]

#include
<MPxDeformerNode.h>

Inheritance diagram for MPxDeformerNode:

[legend]

Collaboration diagram for MPxDeformerNode:

[legend]

List of all members.

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:

The Set Editing Tool and the Set Editor Window can be used to modify the membership of the deformer.
Association of a weight value with each CV. The weight values can be modified by the user using the set editing window or the percent command. This weight value can be used or ignored at the plugin's discretion.
"Has No Effect" mode is implemented in the base class, and disables the node.
When the deformer node is deleted, its inputs and outputs will be correctly reconnected in the dependency graph.
Reordering of the deformer node with other deformers via the Complete List window.
Placement and connection of the deformer node in the dependency graph via the "deformer -type" command. The deformer command also has the standard deformer options such as exclusive membership and parallel mode.

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:

Your node's deformation algorithm depends on the geometry type, which is not available in the deform() method.
Your node's deformation algorithm requires computing all of the output geometries simultaneously.

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.


Public Types
enum	DeformationDetails { kDeformsUVs = (1<<1), kDeformsColors = (1<<2) }
	Deformation details. More...
Public Member Functions
	MPxDeformerNode ()
virtual	~MPxDeformerNode ()
virtual MPxNode::Type	type () const
virtual MStatus	deform (MDataBlock &block, MItGeometry &iter, const MMatrix &mat, unsigned int multiIndex)
virtual MObject &	accessoryAttribute () const
virtual MStatus	accessoryNodeSetup (MDagModifier &cmd)
float	weightValue (MDataBlock &mblock, unsigned int multiIndex, unsigned int wtIndex)
void	setUseExistingConnectionWhenSetEditing (bool state)
MStatus	setDeformationDetails (unsigned int flags)
unsigned int	getDeformationDetails (MStatus *ReturnStatus=NULL)
virtual void	setModifiedCallback (MSelectionList &list, bool listAdded)
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

enum MPxDeformerNode::DeformationDetails

Deformation details.

Enumerator:

kDeformsUVs	The deformer will deform UVs.
kDeformsColors	The deformer will deform colors.

Constructor & Destructor Documentation

MPxDeformerNode::MPxDeformerNode ( )

Class constructor.

MPxDeformerNode::~MPxDeformerNode ( ) [virtual]

Class destructor.

Member Function Documentation

MPxNode::Type MPxDeformerNode::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 MPxDeformerNode::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:

MS::kSuccess The method was successful.
MS::kFailure An object error has occurred.

Examples:

offsetNode.cpp, and yTwistNode.cpp.

MObject & MPxDeformerNode::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 MPxDeformerNode::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 MPxDeformerNode::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 MPxDeformerNode::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 MPxDeformerNode::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:

MS::kSuccess Operation successful
MS::kInvalidParameter Invalid flags passed in
MS::kFailure The base stucture was not initialized properly

unsigned int MPxDeformerNode::getDeformationDetails ( MStatus * ReturnStatus = NULL )

Retrieves the value set by setDeformationDetails(). See the documentation of that method for the interpretation of the value.

Returns:: The deformation details

Status Codes:

MS::kSuccess Operation successful
MS::kFailure The base stucture was not initialized properly

void MPxDeformerNode::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.

MPxDeformerNode Class Reference [OpenMayaAnim - API module for animation, Proxy classes]

Detailed Description

Public Types

Public Member Functions

Static Public Attributes

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

MPxDeformerNode Class Reference
[OpenMayaAnim - API module for animation, Proxy classes]