- Main Page
- Related Pages
- Modules
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Protected Member Functions

# MFnIkHandle Class Reference
OpenMayaAnim - API module for animation | FunctionSet classes

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:
[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

Search for all occurrences

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

Enumerator:

  kStickyOff | Handle will move with skeleton's root. Search for all occurrences
  kStickyOn | Handle will try to stay where it is. Search for all occurrences
  kSuperSticky | Not used. Search for all occurrences

## 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] | object | The MObject to attach the function set to
  [out] | ReturnStatus | the return status

Status Codes:
  - MS::kSuccess if the function set is successfully attached
  - MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

MFnIkHandle | ( | const MDagPath & | object,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Constructor.

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

Parameters:

  [in] | object | The const MDagPath to attach the function set to
  [out] | ReturnStatus | The return status

Status Codes:
  - MS::kSuccess if the function set is successfully attached
  - MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

MFnIkHandle | ( | const MObject & | object,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Constructor.

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

Parameters:

  [in] | object | The MObject to attach the function set to
  [out] | ReturnStatus | the return status

Status Codes:
  - MS::kSuccess if the function set is successfully attached
  - MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

## Member Function Documentation

MFn::Type type | ( |  | ) | const`[virtual]`

Search for all occurrences

Function set type.

Return the class type : MFn::kIkHandle.

Reimplemented from MFnTransform.

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

Search for all occurrences

Class name.

Return the class name : "MFnIkHandle".

Reimplemented from MFnTransform.

MObject create | ( | MDagPath & | startJoint,
|  | MDagPath & | effector,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Search for all occurrences

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] | startJoint | a path to the start joint in the joint chain
  [in] | effector | a path to the end-effector (last joint) in the chain
  [out] | ReturnStatus | Status Code (see below)

Status Codes:
  - MS::kSuccess A new ik handle was successfully created and added to the dag
  - MS::kInvalidParameter The startJoint or effector are not valid joints
  - MS::kInsufficientMemory Not enough memory available to create the new handle
  - MS::kLicenseFailure Application not licensed for attempted operation
  - MS::kFailure An error occurred adding the new handle to the DAG.

MStatus getStartJoint | ( | MDagPath & | jointPath | ) |

Search for all occurrences

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

Parameters:

  [out] | jointPath | storage 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 | ) |

Search for all occurrences

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] | jointPath | The 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 | ) |

Search for all occurrences

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

Parameters:

  [out] | effectorPath | Storage 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 | ) |

Search for all occurrences

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] | effectorPath | The 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
| ) |  |

Search for all occurrences

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] | jointPath | The dag path to the joint that will be set
  [in] | effectorPath | The 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` | ) |

Search for all occurrences

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] | ReturnStatus | Status 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 | ) |

Search for all occurrences

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] | priority | The priority to set for this handle

Returns:
  ReturnStatus Status Code (see below)

Status Codes:
  - MS::kSuccess The priority was successfully set
  - MS::kFailure This function set has not been attached to a valid object

MFnIkHandle::Stickiness stickiness | ( | MStatus * | ReturnStatus = `NULL` | ) |

Search for all occurrences

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] | ReturnStatus | Status 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 | ) |

Search for all occurrences

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] | stickiness | The 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` | ) |

Search for all occurrences

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] | ReturnStatus | Status 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 | ) |

Search for all occurrences

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] | weight | The 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` | ) |

Search for all occurrences

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] | ReturnStatus | Status 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 | ) |

Search for all occurrences

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] | poWeight | The 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` | ) |

Search for all occurrences

Returns the solver attached to this handle.

Parameters:

  [out] | ReturnStatus | Status 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 | ) |

Search for all occurrences

Set the solver for this handle.

Parameters:

  [in] | solver | The 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 | ) |

Search for all occurrences

Set the solver associated with this handle by name.

Parameters:

  [in] | solverName | The 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