MFnIkHandle Class Reference
[OpenMayaAnim - API module for animationFunctionSet classes]

#include <MFnIkHandle.h>

Inheritance diagram for MFnIkHandle:

Inheritance graph
[legend]
Collaboration diagram for MFnIkHandle:

Collaboration graph
[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

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:

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:

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:


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:

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:

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


Autodesk® Maya® 2009 © 1997-2008 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6