MFnIkHandle Class Reference
[OpenMayaAnim - API module for animation, FunctionSet classes]

#include <MFnIkHandle.h>

Inheritance diagram for MFnIkHandle:

[legend]

Collaboration diagram for MFnIkHandle:

[legend]

List of all members.

---

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.

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)
MStatus	getStartJoint (MDagPath &jointPath)
MStatus	setStartJoint (const MDagPath &jointPath)
MStatus	getEffector (MDagPath &effectorPath)
MStatus	setEffector (const MDagPath &effectorPath)
MStatus	setStartJointAndEffector (const MDagPath &jointPath, const MDagPath &effectorPath)
unsigned int	priority (MStatus *ReturnStatus=NULL)
MStatus	setPriority (unsigned int priority)
Stickiness	stickiness (MStatus *ReturnStatus=NULL)
MStatus	setStickiness (Stickiness stickiness)
double	weight (MStatus *ReturnStatus=NULL)
MStatus	setWeight (double weight)
double	poWeight (MStatus *ReturnStatus=NULL)
MStatus	setPOWeight (double weight)
MObject	solver (MStatus *ReturnStatus=NULL)
MStatus	setSolver (const MObject &solver)
MStatus	setSolver (const MString &solverName)
	MFnIkHandle (const MObject &object, MStatus *ret=NULL)
	Constructor.
Protected Member Functions
virtual const char *	className () const
	Class name.

---

Member Enumeration Documentation

enum MFnIkHandle::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::~MFnIkHandle

(

)

[virtual]

Destructor.

Class destructor.

MFnIkHandle::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::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::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 MFnIkHandle::type

(

)

const [virtual]

Function set type.

Return the class type : MFn::kIkHandle

Reimplemented from MFnTransform.

const char * MFnIkHandle::className

(

)

const [protected, virtual]

Class name.

Return the class name : "MFnIkHandle"

Reimplemented from MFnTransform.

MObject MFnIkHandle::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]	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 MFnIkHandle::getStartJoint

(

MDagPath &

jointPath

)

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 MFnIkHandle::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]

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 MFnIkHandle::getEffector

(

MDagPath &

effectorPath

)

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 MFnIkHandle::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]

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 MFnIkHandle::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]	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 MFnIkHandle::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]

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 MFnIkHandle::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]

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 MFnIkHandle::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]

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 MFnIkHandle::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]

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 MFnIkHandle::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]

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 MFnIkHandle::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]

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 MFnIkHandle::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]

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 MFnIkHandle::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]

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 MFnIkHandle::solver

(

MStatus *

ReturnStatus = NULL

)

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 MFnIkHandle::setSolver

(

const MObject &

solver

)

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 MFnIkHandle::setSolver

(

const MString &

solverName

)

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