C++ API Reference
MItKeyframe Class Reference

Keyframe Iterator. More...

#include <MItKeyframe.h>

Public Types

enum  TangentType {
  kTangentGlobal = 0, kTangentFixed, kTangentLinear, kTangentFlat,
  kTangentSmooth, kTangentStep, kTangentSlow, kTangentFast,
  kTangentClamped, kTangentPlateau, kTangentStepNext, kTangentAuto,
  kTangentAutoMix, kTangentAutoEase, kTangentAutoCustom
}
 Tangent types. More...
 
typedef double TangentValue
 Defines the value type of the tangent.
 

Public Member Functions

 MItKeyframe (MObject &animCurveNode, MStatus *ReturnStatus=NULL)
 Class Constructor. More...
 
 ~MItKeyframe ()
 Class Destructor. More...
 
MStatus reset (MObject &animCurveNode)
 Detaches the iterator from the current Anim Curve Node and attaches it to the given Node. More...
 
MStatus reset ()
 Resets the keyframe index to 0 (first keyframe) on the Anim Curve Node to which the iterator is attached. More...
 
MStatus next ()
 Moves to the next keyframe on the Anim Curve Node to which the iterator is attached. More...
 
bool isDone (MStatus *ReturnStatus=NULL)
 Indicates that the iterator has moved beyond the last keyframe on the Anim Curve Node to which the iterator is attached. More...
 
MTime time (MStatus *ReturnStatus=NULL)
 Determines the time of the current keyframe. More...
 
MStatus setTime (MTime time)
 Sets the time of the current keyframe. More...
 
double value (MStatus *ReturnStatus=NULL)
 Determines the value of the current keyframe. More...
 
MStatus setValue (double value)
 Sets the value of the current keyframe. More...
 
TangentType inTangentType (MStatus *ReturnStatus=NULL)
 Determines the type of the tangent to the curve entering the current keyframe. More...
 
TangentType outTangentType (MStatus *ReturnStatus=NULL)
 Determines the type of the tangent to the curve leaving the current keyframe. More...
 
MStatus setInTangentType (TangentType tangentType)
 Sets the type of the tangent to the curve entering the current keyframe. More...
 
MStatus setOutTangentType (TangentType tangentType)
 Sets the type of the tangent to the curve entering the current keyframe. More...
 
MStatus getTangentOut (TangentValue &x, TangentValue &y)
 Determines the x,y value of the tangent to the curve leaving the current keyframe. More...
 
MStatus getTangentIn (TangentValue &x, TangentValue &y)
 Determines the x,y value of the tangent to the curve entering the current keyframe. More...
 
bool tangentsLocked (MStatus *ReturnStatus=NULL) const
 Determines whether the tangents are locked at this keyframe. More...
 
MStatus setTangentsLocked (bool locked)
 Lock or unlock the tangents at this keyframe. More...
 

Static Public Member Functions

static const char * className ()
 Returns the name of this class. More...
 

Detailed Description

Keyframe Iterator.

Iterate over the keyframes of a particular Anim Curve Node, and query and edit the keyframe to which the iterator points.

Determine the time and value of the keyframe, as well as the x,y values and type of the tangent to the curve entering (in tangent) and leaving (out tangent) the keyframe.

Set the time and value of the keyframe, and the type of the tangents.

Anim Curves are implemented as Dependency Graph (DG) Nodes. Each Node has multiple ordered and indexed keyframes.

Use the Keyframe Iterator to systematically visit, and query and/or edit the keyframes of a Anim Curve Node.

Use the Keyframe Iterator in conjunction with the Anim Curve Function Set (MFnAnimCurve) to edit Anim Curve Nodes.

On creation the iterator is attached to a Anim Curve Node. The iterator may be detached from its current Node and attached to another Anim Curve Node using the reset() method.

Though keyframes within a Node are ordered and indexed, the iterator maintains the index of the current Node internally and does not export it. Use the Anim Curve Function Set to access the index for a keyframe. The index is zero-based. When an iterator is first attached to a Node, either on creation or reset, the index is set to zero. There is an overloaded version of the reset() method which does not cause the iterator to change Nodes, but merely resets the index.

Use the next(), reset() and isDone() methods to perform iterations.

Use the specific query methods to determine the time, value and tangent information for the keyframe under the iterator.

Use specific edit methods to set the time and value , as well as the incoming and outgoing tangent type (MItKeyframe::TangentType) of the keyframe under the iterator.

There is no method for setting the x,y value of either of the tangents.

Setting the time of a keyframe will fail if the new time would require a re-ordering of the keyframes. Use the Anim Curve Functiion Set methods MFnAnimCurve::remove() and MFnAnimCurve::addKeyFrame() to re-order the keyframes.

Member Enumeration Documentation

Tangent types.

Enumerator
kTangentGlobal 

Use the global tangent settings in Maya's 'Animation Preferences'.

kTangentFixed 

Normally, if a key is moved tangent values will be adjusted to maintain their relationships to the surrounding keys (linear, smooth, etc).

If a tangent is set to be fixed then it will not change when keys are moved but will retain its current value.

kTangentLinear 

For an in tangent this sets it to point directly at the previous key.

For an out tangent it points directly to the next key. This is used to create straight lines between keys.

kTangentFlat 

The tangent is horizontal.

kTangentSmooth 

The in and out tangents are colinear and set to provide a smooth transition from the key before to the key after.

kTangentStep 

The key's value is maintained until the next key is reached whereupon it immediately jumps to the new key's value.

kTangentSlow 

Slow tangent.

kTangentFast 

Fast tangent.

kTangentClamped 

Same as smooth except when two keys are very close together in which case the tangents between them are treated as linear.

This corrects for slippage which is sometimes seen when spline tangents are used on keyframes which are close together.

kTangentPlateau 

Similar to smooth except that minima and maxima between keyframes are flattened, if necessary, to prevent them overshooting their keys.

kTangentStepNext 

Upon leaving the keyframe the value immediately jumps to that of the next keyframe and stays there.

kTangentAuto 

The first and last keyframes will have flat tangents.

Between, inner keyframes, the animation curve will not over shoot the keyframe values.

kTangentAutoMix 

The first and last keyframes will have flat tangents.

Between, inner keyframes, the animation curve will not over shoot the keyframe values, and use a linear interpolation to calculate the auto tangent.

kTangentAutoEase 

The first and last keyframes will have flat tangents.

Between, inner keyframes, the animation curve will not over shoot the keyframe values, and use a cubic interpolation to calculate the auto tangent.

kTangentAutoCustom 

The first and last keyframes will have flat tangents.

Between, inner keyframes, the animation curve will not over shoot the keyframe values, and use a custom cubic interpolation to calculate the auto tangent.

Constructor & Destructor Documentation

OPENMAYA_MAJOR_NAMESPACE_OPEN MItKeyframe ( MObject animCurveNode,
MStatus ReturnStatus = NULL 
)

Class Constructor.

Creates an iterator and attaches it to the given Anim Curve Node.

Parameters
[in]animCurveNodeTarget Node for attachment of iterator
[out]ReturnStatusStatus Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Failure creating iterator - Node does not exist, is not accessible or is not a Anim Curve

Class Destructor.

No additional action.

Member Function Documentation

MStatus reset ( MObject animCurveNode)

Detaches the iterator from the current Anim Curve Node and attaches it to the given Node.

Resets to the first keyframe (index = 0).

Parameters
[in]animCurveNodeNew target Node for attachment to iterator
Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Failure reseting iterator - Node does not exist, is not accessible or is not a Anim Curve
MStatus reset ( )

Resets the keyframe index to 0 (first keyframe) on the Anim Curve Node to which the iterator is attached.

Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Failure reseting iterator - Node does not exist or is not accessible
MStatus next ( )

Moves to the next keyframe on the Anim Curve Node to which the iterator is attached.

Attempting to move beyond the last keyframe has no effect (and returns success).

Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible
bool isDone ( MStatus ReturnStatus = NULL)

Indicates that the iterator has moved beyond the last keyframe on the Anim Curve Node to which the iterator is attached.

If isDone() returns true, attempting to access the curve via the iterator's time(), value() etc. methods will return an 'index out of range' error.

Parameters
[out]ReturnStatusStatus Code (see below)
Returns
  • true Done
  • false Not done
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible
MTime time ( MStatus ReturnStatus = NULL)

Determines the time of the current keyframe.

Parameters
[out]ReturnStatusStatus Code (see below).
Returns
Time (in seconds) of the current keyframe
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible
MStatus setTime ( MTime  time)

Sets the time of the current keyframe.

This will fail if setting the time would require re-ordering of the keyframes.

Tangents may be changed so that the curve remains monotonic with respect to time.

Parameters
[in]timeTime to which the current keyframe time is to be set.
Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Invalid parameter passed for time - time out of range and/or re-ordering of keyframes required
  • MS::kFailure Failure editing Node - Node does not exist or is not accessible
double value ( MStatus ReturnStatus = NULL)

Determines the value of the current keyframe.

Parameters
[out]ReturnStatusStatus Code (see below).
Returns
Value of the current keyframe
Status Codes:
  • MS::kSuccess Success
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible
MStatus setValue ( double  value)

Sets the value of the current keyframe.

Parameters
[in]valueValue to which the current keyframe time is to be set.
Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure editing Node - Node does not exist or is not accessible
MItKeyframe::TangentType inTangentType ( MStatus ReturnStatus = NULL)

Determines the type of the tangent to the curve entering the current keyframe.

Parameters
[out]ReturnStatusStatus Code (see below).
Returns
Type of the tangent
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible, or keyframe does not exist or is not aacessible, or index is invalid
MItKeyframe::TangentType outTangentType ( MStatus ReturnStatus = NULL)

Determines the type of the tangent to the curve leaving the current keyframe.

Parameters
[out]ReturnStatusStatus Code (see below).
Returns
Type of the tangent
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible, or keyframe does not exist or is not aacessible, or index is invalid
MStatus setInTangentType ( TangentType  tangentType)

Sets the type of the tangent to the curve entering the current keyframe.

Parameters
[in]tangentTypeType to which the tangent is to be set
Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible
MStatus setOutTangentType ( TangentType  tangentType)

Sets the type of the tangent to the curve entering the current keyframe.

Parameters
[in]tangentTypeType to which the tangent is to be set
Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible
MStatus getTangentOut ( TangentValue x,
TangentValue y 
)

Determines the x,y value of the tangent to the curve leaving the current keyframe.

Parameters
[out]xDelta x of the slope of the tangent
[out]yDelta y of the slope of the tangent
Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible, or keyframe does not exist or is not aacessible, or index is invalid
MStatus getTangentIn ( TangentValue x,
TangentValue y 
)

Determines the x,y value of the tangent to the curve entering the current keyframe.

Parameters
[out]xDelta x of the slope of the tangent
[out]yDelta y of the slope of the tangent
Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible, or keyframe does not exist or is not aacessible, or index is invalid
bool tangentsLocked ( MStatus ReturnStatus = NULL) const

Determines whether the tangents are locked at this keyframe.

Parameters
[out]ReturnStatusStatus Code (see below).
Returns
  • true if the tangents are locked
  • false if the tangents are not locked
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible, or keyframe does not exist or is not aacessible, or index is invalid
MStatus setTangentsLocked ( bool  locked)

Lock or unlock the tangents at this keyframe.

Parameters
[in]lockedtrue if the tangents are to be locked, false otherwise
Returns
Status Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvalidParameter Iterator holds invalid keyframe index (index >= number of keyframes) - iterator is invalid or index is invalid
  • MS::kFailure Failure querying Node - Node does not exist or is not accessible
const char * className ( )
static

Returns the name of this class.

Returns
The name of this class.

The documentation for this class was generated from the following files: