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 Class Reference

OpenMayaAnim - API module for animation | FunctionSet classes

Detailed Description

Public Types

Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation