C++ API Reference

Base class for user defined IK solvers. More...

#include <MPxIkSolverNode.h>

+ Inheritance diagram for MPxIkSolverNode:

Public Member Functions

 ~MPxIkSolverNode () override
 Destructor.
 
MPxNode::Type type () const override
 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 indicates whether this solver is a single chain solver. 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...
 
MIkHandleGrouphandleGroup () const
 Returns the handle group for this solver. More...
 
virtual void setHandleGroup (MIkHandleGroup *)
 Set the handle group of this solver. More...
 
const MMatrixtoWorldSpace () const
 Returns the world space matrix for this solver. More...
 
const MMatrixtoSolverSpace () 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...
 
virtual bool isAttributeCreatedBySolver (MObject &attr) const
 This function returns whether a certain attribute on the ikHandle was created by the solver (and affecting the result of the solve). More...
 
- Public Member Functions inherited from MPxNode
 MPxNode ()
 Constructor. More...
 
virtual ~MPxNode ()
 Destructor.
 
virtual void postConstructor ()
 Post constructor. More...
 
virtual MStatus compute (const MPlug &, MDataBlock &)
 This method should be overridden in user defined nodes. More...
 
virtual bool getInternalValue (const MPlug &, MDataHandle &)
 This method is overridden by nodes that store attribute data in some internal format. More...
 
virtual bool setInternalValue (const MPlug &, const MDataHandle &)
 This method is overridden by nodes that store attribute data in some internal format. More...
 
virtual int internalArrayCount (const MPlug &) 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 &, const MPlug &, 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 &, const MPlug &, 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 void getCacheSetup (const MEvaluationNode &, MNodeCacheDisablingInfo &, MNodeCacheSetupInfo &, MObjectArray &) const
 Provide node-specific setup info for the Cached Playback system. More...
 
virtual void configCache (const MEvaluationNode &, MCacheSchema &) const
 Defines the node's behavior when participating in Cached Playback. More...
 
virtual MTimeRange transformInvalidationRange (const MPlug &source, const MTimeRange &input) const
 Override this method to register this node as an Invalidation-Range-Transformation kernel (IRT kernel) An IRT kernel node will change the invalidation time range for its downstream nodes For example, Dynamics-solver will transform invalidation time range [a,b] to [a,+inf) And Clip-Time-Editor will send out the invalidation range for each of the clip [a,b] to ( [t0+a,t0+b] U [t1+a,t1+b] U [t2+a,t2+b] U ... More...
 
bool hasInvalidationRangeTransformation () const
 Checks if this MPxNode derived node overrides the MPxNode::transformInvalidationRange method.
 
virtual MStatus connectionMade (const MPlug &, const MPlug &, bool asSrc)
 This method gets called when connections are made to attributes of this node. More...
 
virtual MStatus connectionBroken (const MPlug &, const MPlug &, bool asSrc)
 This method gets called when connections are broken with attributes of this node. More...
 
virtual MStatus dependsOn (const MPlug &, const MPlug &, bool &depends) const
 This method may be overridden by the user defined node. More...
 
virtual bool isPassiveOutput (const MPlug &) 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 &, bool &isSaving)
 This method may be overridden by the user defined node. More...
 
virtual MPlug passThroughToOne (const MPlug &) 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 &, MPlugArray &) 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 bool isTrackingTopology () const
 Override this class to return true if this node wants to track topology. 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 &, const MObject &attr) const
 Adds content info to the specified table from a file path attribute. More...
 
bool setExternalContentForFileAttr (const MObject &attr, const MExternalContentLocationTable &)
 Sets content info in the specified attribute from the table. More...
 
virtual void setExternalContent (const MExternalContentLocationTable &)
 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...
 
void _setMPSafe (bool isMPSafe)
 This method is obsolete. More...
 
MDataBlock _forceCache (const MDGContext &)
 This method is obsolete. More...
 
virtual bool getInternalValueInContext (const MPlug &, MDataHandle &, MDGContext &)
 This method is obsolete. More...
 
virtual bool setInternalValueInContext (const MPlug &, const MDataHandle &, MDGContext &)
 This method is obsolete. More...
 
virtual int internalArrayCount (const MPlug &, const MDGContext &) const
 This method is obsolete. 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 MStatus attributeAffects (const MObject &whenChanges, const MObject &isAffected, bool affectsTopology)
 This method is an extension to the other version of the attributeAffects method. 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 ()
 USE _forceCache() 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...
 
virtual void setMPSafe (bool isMPSafe)
 This method is obsolete. More...
 
virtual MDataBlock forceCache (const MDGContext &)
 This method is obsolete. 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, kSerialize = kSerial, kGloballySerialize = kGloballySerial
}
 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
 

Detailed 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

Since Maya 2018, users no longer need to call the base class version of these functions if overriding them.

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:
ik2Bsolver/ik2Bsolver.cpp, and simpleSolverNode/simpleSolverNode.cpp.

Member Function Documentation

MPxNode::Type type ( ) const
overridevirtual

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.

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:
ik2Bsolver/ik2Bsolver.cpp, and simpleSolverNode/simpleSolverNode.cpp.
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.

The status argument indicates whether doSolve was successful.

Parameters
[out]statThe 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:
ik2Bsolver/ik2Bsolver.cpp, and simpleSolverNode/simpleSolverNode.cpp.
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]ReturnStatusStatus 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]rotatePlanewhether 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]ReturnStatusStatus 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]singleChainOnlywhether 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]ReturnStatusStatus 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]positionOnlywhether 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]ReturnStatusStatus 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]supportJointLimitswhether 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]ReturnStatusStatus 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]uniqueSolutionwhether 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 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.

Indicates whether the solver supports handle orientation.

[from before Maya 2016]

Deprecated:
Defaults to a false return.

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.

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

[from before Maya 2016]

Deprecated:
Defaults to a false return.

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.

This method indicates whether the solver provides a unique solution.

[from before Maya 2016]

Deprecated:
Defaults to a false return.

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.

Indicates whether the IK system should group handles according to skeletal topology.

[from before Maya 2016]

Deprecated:
Defaults to a false return.

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]toleranceError 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]valuevalue 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]groupThe 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]handlehandle to be set
bool isAttributeCreatedBySolver ( MObject attr) const
virtual

This function returns whether a certain attribute on the ikHandle was created by the solver (and affecting the result of the solve).

Parameters
[in]attrattribute to be queried
Returns
True if the attribute is created by the solver and affecting the solve
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]anglesThe 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]anglesThe 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: