MPxIkSolverNode Class Reference

#include <MPxIkSolverNode.h>

Class Description

Base class for user defined IK solvers.

This is the base class for writing user-defined IK solvers. Users must at least override the following methods in order to write a solver:

• doSolve
• solverTypeName

Users can optionally override the following methods if they want to perform work before or after doSolve is called:

• preSolve
• postSolve

If users override these methods, they are responsible for calling the base class implementation of the overridden method(s). The base class handles a few things such as solver locking/unlocking and FK/IK solution blending. If users fail to call the base class implementation, instabilities can occur leading to wrong evaluation or even crashes.

Note that the following virtual methods (declared in MPxNode) are irrelevant for the MPxIkSolverNode. If these methods are overridden in a class derived from MPxIkSolverNode, they will be ignored.

• compute
• getInternalValue
• setInternalValue
• legalConnection
• legalDisconnection
• connectionMade
• connectionBroken

A creator method is necessary to return an instance of the user solver:

userSolver::creator() {
    return new userSolver;
}

In order to create and register the solver, execute the mel command:

createNode userSolver;

Once the solver is registered it can be assigned to IK handles and its solve methods will be called in the same manner as the solvers within Maya.

Examples:

Inheritance diagram for MPxIkSolverNode:

Public Member Functions
virtual	~MPxIkSolverNode ()
	Destructor.
virtual MPxNode::Type	type () const
	This method returns the type of the node. More...
virtual MStatus	preSolve ()
	This method is called before doSolve. More...
virtual MStatus	doSolve ()
	This is where the main solving takes place. More...
virtual MStatus	postSolve (MStatus)
	This method is called after doSolve has finished. More...
virtual MString	solverTypeName () const
	This method returns the type name of the solver. More...
bool	rotatePlane (MStatus *ReturnStatus=NULL) const
	This method indicates whether this solver supports the rotate plane. More...
MStatus	setRotatePlane (bool rotatePlane)
	This method sets whether or not this solver supports the rotate plane. More...
bool	singleChainOnly (MStatus *ReturnStatus=NULL) const
	This method indicates whether this solver is a single chain solver. More...
MStatus	setSingleChainOnly (bool singleChainOnly)
	This method sets whether or not this solver is a single chain solver. More...
bool	positionOnly (MStatus *ReturnStatus=NULL) const
	Indicates whether the ik solution is dependent on the ikHandle position only or also uses the orientation. More...
MStatus	setPositionOnly (bool positionOnly)
	Sets whether or not the solver supports handle orientation. More...
bool	supportJointLimits (MStatus *ReturnStatus=NULL) const
	This method indicates whether the solver supports limits on joint angles. More...
MStatus	setSupportJointLimits (bool supportJointLimits)
	This method sets whether or not the solver supports limits on joint angles. More...
bool	uniqueSolution (MStatus *ReturnStatus=NULL) const
	This method indicates whether the solver provides a unique solution. More...
MStatus	setUniqueSolution (bool uniqueSolution)
	This method sets whether or not the solver provides a unique solution. More...
virtual bool	isSingleChainOnly () const
	This method is obsolete. More...
virtual bool	isPositionOnly () const
	This method is obsolete. More...
virtual bool	hasJointLimitSupport () const
	This method is obsolete. More...
virtual bool	hasUniqueSolution () const
	This method is obsolete. More...
virtual bool	groupHandlesByTopology () const
	This method is obsolete. More...
virtual MStatus	setFuncValueTolerance (double tolerance)
	Set the error value for this solver. More...
virtual MStatus	setMaxIterations (int value)
	Set the maximum iterations for a solution by this solver. More...
MIkHandleGroup *	handleGroup () const
	Returns the handle group for this solver. More...
virtual void	setHandleGroup (MIkHandleGroup *)
	Set the handle group of this solver. More...
const MMatrix *	toWorldSpace () const
	Returns the world space matrix for this solver. More...
const MMatrix *	toSolverSpace () const
	Returns the local space matrix for this solver. More...
double	funcValueTolerance () const
	Return the error value for this solver. More...
int	maxIterations () const
	Return the the maximum nuber of itertations for a solution by this solver. More...
virtual void	snapHandle (MObject &handle)
	This function positions the handle at the end effector position. More...
Public Member Functions inherited from MPxNode
	MPxNode ()
	Constructor. More...
virtual	~MPxNode ()
	Destructor.
virtual void	postConstructor ()
	Post constructor. More...
virtual MStatus	compute (const MPlug &plug, MDataBlock &dataBlock)
	This method should be overridden in user defined nodes. More...
virtual bool	getInternalValueInContext (const MPlug &plug, MDataHandle &dataHandle, MDGContext &ctx)
	This method is overridden by nodes that store attribute data in some internal format. More...
virtual bool	setInternalValueInContext (const MPlug &plug, const MDataHandle &dataHandle, MDGContext &ctx)
	This method is overridden by nodes that store attribute data in some internal format. More...
virtual bool	getInternalValue (const MPlug &plug, MDataHandle &dataHandle)
	This method is obsolete. More...
virtual bool	setInternalValue (const MPlug &plug, const MDataHandle &dataHandle)
	This method is obsolete. More...
virtual int	internalArrayCount (const MPlug &plug, const MDGContext &ctx) const
	This method is overridden by nodes that have internal array attributes which are not stored in Maya's datablock. More...
virtual void	copyInternalData (MPxNode *)
	This method is overridden by nodes that store attribute data in some internal format. More...
virtual MStatus	legalConnection (const MPlug &plug, const MPlug &otherPlug, bool asSrc, bool &isLegal) const
	This method allows you to check for legal connections being made to attributes of this node. More...
virtual MStatus	legalDisconnection (const MPlug &plug, const MPlug &otherPlug, bool asSrc, bool &isLegal) const
	This method allows you to check for legal disconnections being made to attributes of this node. More...
virtual MStatus	setDependentsDirty (const MPlug &plug, MPlugArray &plugArray)
	This method can be overridden in user defined nodes to specify which plugs should be set dirty based upon an input plug {plugBeingDirtied} which Maya is marking dirty. More...
virtual MStatus	preEvaluation (const MDGContext &context, const MEvaluationNode &evaluationNode)
	Prepare a node's internal state for threaded evaluation. More...
virtual MStatus	postEvaluation (const MDGContext &context, const MEvaluationNode &evaluationNode, PostEvaluationType evalType)
	Clean up node's internal state after threaded evaluation. More...
virtual SchedulingType	schedulingType () const
	When overridden this method controls the degree of parallelism supported by the node during threaded evaluation. More...
virtual MStatus	connectionMade (const MPlug &plug, const MPlug &otherPlug, bool asSrc)
	This method gets called when connections are made to attributes of this node. More...
virtual MStatus	connectionBroken (const MPlug &plug, const MPlug &otherPlug, bool asSrc)
	This method gets called when connections are broken with attributes of this node. More...
virtual MStatus	dependsOn (const MPlug &plug, const MPlug &otherPlug, bool &depends) const
	This method may be overridden by the user defined node. More...
virtual bool	isPassiveOutput (const MPlug &plug) const
	This method may be overridden by the user defined node if it wants to provide output attributes which do not prevent value modifications to the destination attribute. More...
virtual MStatus	shouldSave (const MPlug &plug, bool &isSaving)
	This method may be overridden by the user defined node. More...
virtual MPlug	passThroughToOne (const MPlug &plug) const
	This method may be overridden by nodes that have a one-to-one relationship between an input attribute and a corresponding output attribute. More...
virtual bool	passThroughToMany (const MPlug &plug, MPlugArray &plugArray) const
	This method is overridden by nodes that want to control the traversal behavior of some Maya search algorithms which traverse the history/future of shape nodes looking for directly related nodes. More...
virtual bool	isAbstractClass () const
	Override this class to return true if this node is an abstract node. More...
virtual MStringArray	getFilesToArchive (bool shortName=false, bool unresolvedName=false, bool markCouldBeImageSequence=false) const
	Use this method to return all external files used by this node. More...
virtual void	getExternalContent (MExternalContentInfoTable &table) const
	Returns the external content (files) that this node depends on. More...
bool	addExternalContentForFileAttr (MExternalContentInfoTable &table, const MObject &attr) const
	Adds content info to the specified table from a file path attribute. More...
bool	setExternalContentForFileAttr (const MObject &attr, const MExternalContentLocationTable &table)
	Sets content info in the specified attribute from the table. More...
virtual void	setExternalContent (const MExternalContentLocationTable &table)
	Changes the location of external content in batch. More...
virtual MTypeId	typeId () const
	Returns the TYPEID of this node. More...
virtual MString	typeName () const
	Returns the type name of this node. More...
virtual MString	name () const
	Returns the name of this particular instance of this class. More...
virtual MObject	thisMObject () const
	Returns the MObject associated with this user defined node. More...
virtual MStatus	setExistWithoutInConnections (bool flag)
	This method specifies whether or not the node can exist without input connections. More...
virtual bool	existWithoutInConnections (MStatus *ReturnStatus=NULL) const
	Determines whether or not this node can exist without input connections. More...
virtual MStatus	setExistWithoutOutConnections (bool flag)
	This method specifies whether or not the node can exist without output connections. More...
virtual bool	existWithoutOutConnections (MStatus *ReturnStatus=NULL) const
	Determines whether or not this node can exist without output connections. More...

Static Public Member Functions
static const char *	className ()
	Returns the name of this class. More...
Static Public Member Functions inherited from MPxNode
static MStatus	addAttribute (const MObject &attr)
	This method adds a new attribute to a user defined node type during the type's initialization. More...
static MStatus	inheritAttributesFrom (const MString &parentClassName)
	This method allows a class of plugin node to inherit all of the attributes of a second class of plugin node. More...
static MStatus	attributeAffects (const MObject &whenChanges, const MObject &isAffected)
	This method specifies that a particular input attribute affects a specific output attribute. More...
static const char *	className ()
	Returns the name of this class. More...

Protected Member Functions
MStatus	getJointAngles (MDoubleArray &) const
	This method is not available in Python. More...
MStatus	setJointAngles (const MDoubleArray &)
	This method is not available in Python. More...
void	setToRestAngles ()
	This method is not available in Python. More...
	MPxIkSolverNode ()
	Constructor.
Protected Member Functions inherited from MPxNode
virtual MDataBlock	forceCache (MDGContext &ctx=MDGContext::fsNormal)
	USE _forceCache() IN SCRIPT. More...
virtual void	setMPSafe (bool flag)
	USE _setMPSafe() IN SCRIPT. More...
virtual MStatus	setDoNotWrite (bool flag)
	USE _setDoNotWrite() IN SCRIPT. More...
virtual bool	doNotWrite (MStatus *ReturnStatus=NULL) const
	USE _doNotWrite() IN SCRIPT. More...

Additional Inherited Members
Public Types inherited from MPxNode
enum	Type {   kDependNode, kLocatorNode, kDeformerNode, kManipContainer,   kSurfaceShape, kFieldNode, kEmitterNode, kSpringNode,   kIkSolverNode, kHardwareShader, kHwShaderNode, kTransformNode,   kObjectSet, kFluidEmitterNode, kImagePlaneNode, kParticleAttributeMapperNode,   kCameraSetNode, kConstraintNode, kManipulatorNode, kMotionPathNode,   kClientDeviceNode, kThreadedDeviceNode, kAssembly, kSkinCluster,   kGeometryFilter, kBlendShape, kLast }
	Defines the type of node. More...
enum	SchedulingType {   kParallel, kSerial, kGloballySerial, kUntrusted,   kDefaultScheduling = kSerial }
	Defines the degree of parallelism of a node. More...
Static Public Attributes inherited from MPxNode
static MObject	message
	message attribute
static MObject	isHistoricallyInteresting
	is historically interesting attribute
static MObject	caching
	caching attribute
static MObject	state
	state attribute
static MObject	frozen
	frozen attribute

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::kIkSolverNode.

Returns

The type of node

Status Codes:

• MS::kSuccess The undo was successful
• MS::kFailure This method is not undoable

Reimplemented from MPxNode.

MStatus preSolve ( )

virtual

This method is called before doSolve.

Users should override this method if there is any preprocessing that needs to be done before solving.

If this method is overridden, users are responsible for calling base class version MPxIkSolverNode::preSolve.

Returns

The status code which indicates if the pre-processing was successful

MStatus doSolve ( )

virtual

This is where the main solving takes place.

The user must override this method.

The purpose of this method is to calculate joint angles in a skeleton based upon the position of the end effector of the handle associated with this solver.

Returns

The status code which indicates if the solver was successful

Examples:

MStatus postSolve ( MStatus  stat )

virtual

This method is called after doSolve has finished.

The user should override this method if there are any post calculations to be done.

If this method is overridden, users are responsible for calling base class version MPxIkSolverNode::postSolve.

The status argument indicates whether doSolve was successful.

Parameters

[out]

stat

The status returned from doSolve

Returns

Status code to indicate whether the post calculations were successful

MString solverTypeName ( ) const

virtual

This method returns the type name of the solver.

The user must override this method in order for the solver to be identifiable when it is registered.

Once the solver is registered, the type name can be used to assign the solver to an IK handle.

Returns

The type name of this solver

Examples:

bool rotatePlane

(

MStatus *

ReturnStatus = NULL

)

const

This method indicates whether this solver supports the rotate plane.

Solvers that support the rotate plane allow the user to manipulate the IK handle's pole vector with the rotate plane manipulators.

Parameters

[in]

ReturnStatus

Status code.

Returns

Boolean value: true if the solver supports the rotate plane, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus setRotatePlane

(

bool

rotatePlane

)

This method sets whether or not this solver supports the rotate plane.

Solvers that support the rotate plane allow the user to manipulate the IK handle's pole vector with the rotate plane manipulators.

Parameters

[in]

rotatePlane

whether or not the solver supports the rotate plane

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

bool singleChainOnly

(

MStatus *

ReturnStatus = NULL

)

const

This method indicates whether this solver is a single chain solver.

Single chain solvers are solvers which act on one handle only, i.e. the handle groups have only one handle if they are for single chain solvers.

Parameters

[in]

ReturnStatus

Status code.

Returns

Boolean value: true if the solver is a single chain solver, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus setSingleChainOnly

(

bool

singleChainOnly

)

This method sets whether or not this solver is a single chain solver.

Single chain solvers are solvers which act on one handle only, i.e. the handle groups have only one handle if they are for single chain solvers.

Parameters

[in]

singleChainOnly

whether or not the solver is a single chain solver

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

bool positionOnly

(

MStatus *

ReturnStatus = NULL

)

const

Indicates whether the ik solution is dependent on the ikHandle position only or also uses the orientation.

Parameters

[in]

ReturnStatus

Status code.

Returns

Boolean value: true if the solver does not support handle orientation, false otherwise

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus setPositionOnly

(

bool

positionOnly

)

Sets whether or not the solver supports handle orientation.

Parameters

[in]

positionOnly

whether or not the solver is positionOnly

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

bool supportJointLimits

(

MStatus *

ReturnStatus = NULL

)

const

This method indicates whether the solver supports limits on joint angles.

Parameters

[in]

ReturnStatus

Status code.

Returns

Boolean value. true if the solver supports limits on joint angles, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus setSupportJointLimits

(

bool

supportJointLimits

)

This method sets whether or not the solver supports limits on joint angles.

Parameters

[in]

supportJointLimits

whether or not the solver supports joint limits

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

bool uniqueSolution

(

MStatus *

ReturnStatus = NULL

)

const

This method indicates whether the solver provides a unique solution.

Parameters

[in]

ReturnStatus

Status code.

Returns

Boolean value: true if the solver provides a unique solution, false otherwise.

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus setUniqueSolution

(

bool

uniqueSolution

)

This method sets whether or not the solver provides a unique solution.

Parameters

[in]

uniqueSolution

whether or not the solver provides a unique solution

Returns

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

bool isSingleChainOnly ( ) const

virtual

This method is obsolete.

Deprecated:

This method indicates whether this solver is a single chain solver. Single chain solvers are solvers which act on one handle only, i.e. the handle groups have only one handle if they are for single chain solvers.

Returns

Boolean value true if this is a single chain solver, false otherwise.

bool isPositionOnly ( ) const

virtual

This method is obsolete.

Deprecated:

Indicates whether the solver supports handle orientation. This method must be overridden to reflect the users solver.

Returns

Boolean value true if solver does not support handle orientation, false otherwise.

bool hasJointLimitSupport ( ) const

virtual

This method is obsolete.

Deprecated:

This method indicates whether the solver supports limits on joint angles. This method must be overridden to reflect the users solver.

Returns

Boolean value true if solver supports joint limits, false otherwise.

bool hasUniqueSolution ( ) const

virtual

This method is obsolete.

Deprecated:

This method indicates whether the solver provides a unique solution. This method must be overridden to reflect the users solver.

Returns

Boolean value true if solver has a unique solution, false otherwise.

bool groupHandlesByTopology ( ) const

virtual

This method is obsolete.

Deprecated:

Indicates whether the IK system should group handles according to skeletal topology. This method must be overridden to reflect the users solver.

Returns

Boolean value true if solver group handles by topology, false otherwise.

MStatus setFuncValueTolerance ( double  tolerance )

virtual

Set the error value for this solver.

The user can override this if any other calculations should be done here.

Parameters

[in]

tolerance

Error value

Returns

Status code

MStatus setMaxIterations ( int  value )

virtual

Set the maximum iterations for a solution by this solver.

The user can override this if any other calculations should be done here.

Parameters

[in]

value

value to set

Returns

Status code

MIkHandleGroup * handleGroup

(

)

const

Returns the handle group for this solver.

The handle group provides access to handles associated with the solver.

Returns

A pointer to the IK handle group for this solver

void setHandleGroup ( MIkHandleGroup *  group )

virtual

Set the handle group of this solver.

Parameters

[in]

group

The handle group to be set

const MMatrix * toWorldSpace

(

)

const

Returns the world space matrix for this solver.

Returns

The world space matrix

const MMatrix * toSolverSpace

(

)

const

Returns the local space matrix for this solver.

Returns

The local space matrix

double funcValueTolerance

(

)

const

Return the error value for this solver.

Returns

The error value

int maxIterations

(

)

const

Return the the maximum nuber of itertations for a solution by this solver.

Returns

The maximum number of iterations

void snapHandle ( MObject &  handle )

virtual

This function positions the handle at the end effector position.

The user can override this method.

Parameters

[in]

handle

handle to be set

const char * className ( )

static

Returns the name of this class.

Returns

The name of this class.

MStatus getJointAngles ( MDoubleArray &  angles ) const

protected

This method is not available in Python.

Returns the joint angles. Use MPxIkSolverNode::_getJointAngles in scripts.

Parameters

[out]

angles

The array of doubles to hold the angles.

Returns

Status code

Status Codes:

• MS::kSuccess The operation was successfull.
• MS::kFailure The operation failed.

MStatus setJointAngles ( const MDoubleArray &  angles )

protected

This method is not available in Python.

Set joint angles to the given values. Use MPxIkSolverNode::_setJointAngles in scripts.

Parameters

[in]

angles

The array of angles to set the joints to.

Returns

Status code

Status Codes:

• MS::kSucces the joint angles were set
• MS::kFailure the joint angles were not set

void setToRestAngles ( )

protected

This method is not available in Python.

Sets all joints to thier prefered orientations. Use MPxIkSolverNode::_setToRestAngles in scripts.

---

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

• MPxIkSolverNode.h
• MPxIkSolverNode.cpp