Public Types | Public Member Functions | Protected Member Functions

MFnIkHandle Class Reference

Search for all occurrences

Detailed Description

Function set for inverse kinematics (IK) handles.

This is the function set for inverse kinematics (IK) handles. An ik handle specifies the joints in a skeleton that are effected by an attached ik solver.

Examples:

simpleSolverNode.cpp.

#include <MFnIkHandle.h>

Inheritance diagram for MFnIkHandle:
Inheritance graph
[legend]

List of all members.

Public Types

enum  Stickiness { kStickyOff, kStickyOn, kSuperSticky }
 

Specifies a handle's stickiness when the skeleton is being manipulated interactively.

More...

Public Member Functions

virtual MFn::Type type () const
 Function set type.
virtual ~MFnIkHandle ()
 Destructor.
 MFnIkHandle ()
 Default constructor.
 MFnIkHandle (MObject &object, MStatus *ReturnStatus=NULL)
 Constructor.
 MFnIkHandle (const MDagPath &object, MStatus *ret=NULL)
 Constructor.
MObject create (MDagPath &startJoint, MDagPath &effector, MStatus *ReturnStatus=NULL)
 Creates a new ik handle.
MStatus getStartJoint (MDagPath &jointPath)
 This method will get a dag path to the starting joint of the handle's joint chain.
MStatus setStartJoint (const MDagPath &jointPath)
 This method will set the dag path for the starting joint of the handle's joint chain.
MStatus getEffector (MDagPath &effectorPath)
 Get a dag path to the end-effector of the handle's joint chain.
MStatus setEffector (const MDagPath &effectorPath)
 Set the dag path to the end-effector of the handle's joint chain.
MStatus setStartJointAndEffector (const MDagPath &jointPath, const MDagPath &effectorPath)
 This method will set the dag path for the starting joint and the end-effector of the handle's joint chain.
unsigned int priority (MStatus *ReturnStatus=NULL)
 Get the priority of this handle in case a solution is affected by more than one handle.
MStatus setPriority (unsigned int priority)
 Set the priority of this handle in case a solution is affected by more than one handle.
Stickiness stickiness (MStatus *ReturnStatus=NULL)
 Get the stickiness of this handle.
MStatus setStickiness (Stickiness stickiness)
 Set the stickiness of this handle.
double weight (MStatus *ReturnStatus=NULL)
 Get the handles weight in error calculations.
MStatus setWeight (double weight)
 Specifies the handles weight in error calculations.
double poWeight (MStatus *ReturnStatus=NULL)
 Gets the position/orientation weight of a handle.
MStatus setPOWeight (double weight)
 Sets the position/orientation weight of a handle.
MObject solver (MStatus *ReturnStatus=NULL)
 Returns the solver attached to this handle.
MStatus setSolver (const MObject &solver)
 Set the solver for this handle.
MStatus setSolver (const MString &solverName)
 Set the solver associated with this handle by name.
 MFnIkHandle (const MObject &object, MStatus *ret=NULL)
 Constructor.

Protected Member Functions

virtual const char * className () const
 Class name.

Member Enumeration Documentation

enum Stickiness

Specifies a handle's stickiness when the skeleton is being manipulated interactively.

Enumerator:
kStickyOff 

Handle will move with skeleton's root.

kStickyOn 

Handle will try to stay where it is.

kSuperSticky 

Not used.


Constructor & Destructor Documentation

~MFnIkHandle ( ) [virtual]

Destructor.

Class destructor.

MFnIkHandle ( MObject object,
MStatus ReturnStatus = NULL 
)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters:
[in]objectThe MObject to attach the function set to
[out]ReturnStatusthe return status
Status Codes:
MFnIkHandle ( const MDagPath object,
MStatus ReturnStatus = NULL 
)

Constructor.

Class constructor that initializes the function set to the given constant MDagPath object.

Parameters:
[in]objectThe const MDagPath to attach the function set to
[out]ReturnStatusThe return status
Status Codes:
MFnIkHandle ( const MObject object,
MStatus ReturnStatus = NULL 
)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters:
[in]objectThe MObject to attach the function set to
[out]ReturnStatusthe return status
Status Codes:

Member Function Documentation

MFn::Type type ( ) const [virtual]

Function set type.

Return the class type : MFn::kIkHandle.

Reimplemented from MFnTransform.

const char * className ( ) const [protected, virtual]

Class name.

Return the class name : "MFnIkHandle".

Reimplemented from MFnTransform.

MObject create ( MDagPath startJoint,
MDagPath effector,
MStatus ReturnStatus = NULL 
)

Creates a new ik handle.

The effector and startJoint specify the joint chain controlled by this handle. The effector is the joint that is moved by the handle forcing the solver to recalculate the joint chain.

Parameters:
[in]startJointa path to the start joint in the joint chain
[in]effectora path to the end-effector (last joint) in the chain
[out]ReturnStatusStatus Code (see below)
Status Codes:
MStatus getStartJoint ( MDagPath jointPath)

This method will get a dag path to the starting joint of the handle's joint chain.

Parameters:
[out]jointPathstorage for the dag path to the joint
Returns:
Status Code (see below)
Status Codes:
  • MS::kSuccess The dag path was successfully returned
  • MS::kFailure This function set has not been attached to a valid object
MStatus setStartJoint ( const MDagPath jointPath)

This method will set the dag path for the starting joint of the handle's joint chain.

The start joint must be on the same skeletal chain as the end effector or this method will fail.

Parameters:
[in]jointPathThe dag path to the joint that will be set
Status Codes:
  • MS::kSuccess The joint path was successfully set
  • MS::kFailure This function set has not been attached to a valid object
MStatus getEffector ( MDagPath effectorPath)

Get a dag path to the end-effector of the handle's joint chain.

Parameters:
[out]effectorPathStorage for the effector path
Returns:
ReturnStatus Status Code (see below)
Status Codes:
  • MS::kSuccess The effector path was successfully returned
  • MS::kFailure This function set has not been attached to a valid object
MStatus setEffector ( const MDagPath effectorPath)

Set the dag path to the end-effector of the handle's joint chain.

The end-effector/joint must be on the same skeletal chain as the start joint or this method will fail.

The end effector may be specified with a joint or an end-effector. If a joint is used, an end-effector will be created at the same position as the joint and this new end-effector will be used as the end effector.

Parameters:
[in]effectorPathThe path for the effector
Returns:
ReturnStatus Status Code (see below)
Status Codes:
  • MS::kSuccess The effector path was successfully set
  • MS::kFailure This function set has not been attached to a valid object
MStatus setStartJointAndEffector ( const MDagPath jointPath,
const MDagPath effectorPath 
)

This method will set the dag path for the starting joint and the end-effector of the handle's joint chain.

This method must be used when setting the joints for a handle that are in a different skeletal chain then the current one.

The end effector may be specified with a joint or an end-effector. If a joint is used, an end-effector will be created at the same position as the joint and this new end-effector will be used as the end effector.

Parameters:
[in]jointPathThe dag path to the joint that will be set
[in]effectorPathThe path for the effector
Status Codes:
  • MS::kSuccess The joint and effector paths were successfully set
  • MS::kFailure This function set has not been attached to a valid object
unsigned int priority ( MStatus ReturnStatus = NULL)

Get the priority of this handle in case a solution is affected by more than one handle.

Logically, all handles with a lower number priority are solved before any handles with a higher numbered priority. (All handles of priority 1 are solved before any handles of priority 2 and so on.) Handle priorities must be > 0.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
The priority of this handle
Status Codes:
  • MS::kSuccess The priority was successfully returned
  • MS::kFailure This function set has not been attached to a valid object
MStatus setPriority ( unsigned int  priority)

Set the priority of this handle in case a solution is affected by more than one handle.

Logically, all handles with a lower number priority are solved before any handles with a higher numbered priority. (All handles of priority 1 are solved before any handles of priority 2 and so on.) Handle priorities must be > 0.

Parameters:
[in]priorityThe priority to set for this handle
Returns:
ReturnStatus Status Code (see below)
Status Codes:
MFnIkHandle::Stickiness stickiness ( MStatus ReturnStatus = NULL)

Get the stickiness of this handle.

Sticky handles are solved when the skeleton is being manipulated interactively. If a character has sticky feet, the solver will attempt to keep them in the same position as the user moves the character's root. If they were not sticky, they would move along with the root.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
The stickiness value for this handle.
Status Codes:
  • MS::kSuccess The stickiness value was successfully returned
  • MS::kFailure This function set has not been attached to a valid object
MStatus setStickiness ( Stickiness  stickiness)

Set the stickiness of this handle.

Sticky handles are solved when the skeleton is being manipulated interactively. If a character has sticky feet, the solver will attempt to keep them in the same position as the user moves the character's root. If they were not sticky, they would move along with the root.

Parameters:
[in]stickinessThe stickiness value to be set.
Returns:
ReturnStatus Status Code (see below)
Status Codes:
  • MS::kSuccess The stickiness value was successfully set
  • MS::kFailure This function set has not been attached to a valid object
double weight ( MStatus ReturnStatus = NULL)

Get the handles weight in error calculations.

The weight only applies when handle goals are in conflict and cannot be solved simultaneously. When this happens, a solution is computed that weights the "distance" from each goal to the solution by the handle's weight and attempts to minimize this value. The weight must be >= 0.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
The weight value for this handle
Status Codes:
  • MS::kSuccess The weight value was successfully returned
  • MS::kFailure This function set has not been attached to a valid object
MStatus setWeight ( double  weight)

Specifies the handles weight in error calculations.

The weight only applies when handle goals are in conflict and cannot be solved simultaneously. When this happens, a solution is computed that weights the "distance" from each goal to the solution by the handle's weight and attempts to minimize this value. The weight must be >= 0.

Parameters:
[in]weightThe weight value to be set
Returns:
ReturnStatus Status Code (see below)
Status Codes:
  • MS::kSuccess The weight value was successfully set
  • MS::kFailure This function set has not been attached to a valid object
double poWeight ( MStatus ReturnStatus = NULL)

Gets the position/orientation weight of a handle.

This is used to compute the "distance" between the goal position and the end-effector position.

A positionWeight of 1.0 computes the distance as the distance between positions only and ignores the orientations.

A positionWeight of 0.0 computes the distance as the distance between the orientations only and ignores the positions.

A positionWeight of 0.5 attempts to weight the distances equally but cannot actually compute this due to units differences. Because there is no way to add linear units and angular units.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
The position/orientation weight
Status Codes:
  • MS::kSuccess The position/orientation weight was successfully returned
  • MS::kFailure This function set has not been attached to a valid object
MStatus setPOWeight ( double  poWeight)

Sets the position/orientation weight of a handle.

This is used to compute the "distance" between the goal position and the end-effector position.

A positionWeight of 1.0 computes the distance as the distance between positions only and ignores the orientations.

A positionWeight of 0.0 computes the distance as the distance between the orientations only and ignores the positions.

A positionWeight of 0.5 attempts to weight the distances equally but cannot actually compute this due to units differences. Because there is no way to add linear units and angular units.

Parameters:
[in]poWeightThe position/orientation weight to be set
Returns:
Status Code (see below)
Status Codes:
  • MS::kSuccess The position/orientation weight was successfully set
  • MS::kFailure This function set has not been attached to a valid object
MObject solver ( MStatus ReturnStatus = NULL)

Returns the solver attached to this handle.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
The solver associated with this handle
Status Codes:
  • MS::kSuccess The solver for this handle was successfully returned
  • MS::kFailure This function set has not been attached to a valid object
MStatus setSolver ( const MObject solver)

Set the solver for this handle.

Parameters:
[in]solverThe solver for this handle
Returns:
Status Code (see below)
Status Codes:
  • MS::kSuccess The solver for this handle was successfully set
  • MS::kFailure This function set has not been attached to a valid object
MStatus setSolver ( const MString solverName)

Set the solver associated with this handle by name.

Parameters:
[in]solverNameThe type name of the solver to be set
Returns:
Status Code (see below)
Status Codes:
  • MS::kSuccess The solver for this handle was successfully set
  • MS::kFailure This function set has not been attached to a valid object

MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle
MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle MFnIkHandle