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® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6