- Main Page
- Related Pages
- Modules
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Static Public Member Functions

# MAnimUtil Class Reference

# OpenMayaAnim - API module for animation

Search for all occurrences

## Detailed Description

Static class providing common animation helper methods.

MAnimUtil is a static class which provides methods which determine if an object is being animated, which attributes are animated for a given object and which animation curves are used to animate a given attribute.

Note: for purposes of this helper class, "animation" refers to attributes animated by animCurves (i.e. by setting keys). It does not include any animation through expressions or dynamics or timer node connections.

Some helper methods may examine different types of objects. Depending upon how the object is represented, the same object may be examined differently.

If the object is specified as an MObject, then all of its attributes are examined. If the MObject is a hierarchical object (such as a dag node) and you specify that the objects parents should be examined, then all the parents of an instanced object will be examined.

If the object is specified as an MDagPath, then all of its attributes are examined. If you specify that the objects parents should be examined, then only the specified path of the instanced object will be examined.

If the object is specifed as an MPlug and no attribute has been set, then the method will behave as if it was called with an MObject. Otherwise only the specified attribute will be examined. For example, a compound attribute will not have its child attributes examined (i.e. if you specify node.translate, node.translateX will not be examined).

If the object is specified through an MSelectionList, it can also have multiple representations. If the object was added to the MSelectionList as an MObject, then it will be examined as an MObject. If the object was added to the MSelectionList as an MDagPath, then it will be examined as an MDagPath. If the object was added to the MSelectionList as either a component or an MPlug, it will be examined as an MPlug with additional expansion of compound attributes into their child attributes (for example, if specify node.translate is specified, node.translateX will be examined. More importantly, if you specify poly.f[4] then xValue, yValue and zValue will be examined for each vertex).

Below is a summary of how the same object will be examined by MAnimUtil::isAnimated depending upon how it has been represented. If we have the following hierarchical layout:

- group1 (translateX is animated)

  - pTorus1 (instanced and not animated)
    - pTorusShape1 (face[4] is animated)

- group2 (not animated)
  - pTorus1 (another instance of pTorus1 as above)

The MAnimUtil::isAnimated will respond as follows:

isAnimated ( MObject(pTorus1), false ) => false

isAnimated ( MObject(pTorus1), true ) => true

isAnimated ( MDagPath(group2|pTorus1), false ) => false

isAnimated ( MDagPath(group2|pTorus1), true ) => false

isAnimated ( MPlug(pTorus1), false ) => false

isAnimated ( MPlug(pTorus1), true ) => true

isAnimated ( MPlug(group1.translate) ) => false

isAnimated ( MPlug(group1.translateX) ) => true

isAnimated ( MPlug(pTorusShape1.pnts[4]) ) => false

isAnimated ( MPlug(pTorusShape1.pnts[4].xValue) ) => true

The following list assumes that MAnimUtil is called with an MSelectionList named list, and shows the response depending upon how the object has been added to list:

isAnimated ( list.add(MObject(pTorus1)), false ) => false

isAnimated ( list.add(MObject(pTorus1)), true ) => true

isAnimated ( list.add(MDagPath(group2|pTorus1)), false ) => false

isAnimated ( list.add(MDagPath(group2|pTorus1)), true ) => false

isAnimated ( list.add(MPlug(pTorus1)), false ) => false

isAnimated ( list.add(MPlug(pTorus1)), true ) => true

isAnimated ( list.add(MPlug(group1.translate)) ) => true

isAnimated ( list.add(MPlug(group1.translateX) ) => true

isAnimated ( list.add(MPlug(pTorusShape1.pnts[4])) ) => true

isAnimated ( list.add(MPlug(pTorusShape1.pnts[4].xValue)) ) => true

`#include <MAnimUtil.h>`

List of all members.

## Static Public Member Functions
static bool | isAnimated (const MObject &node, bool checkParent=false, MStatus *ReturnStatus=NULL)
| Determine whether or not an MObject is animated.
static bool | isAnimated (const MDagPath &path, bool checkParent=false, MStatus *ReturnStatus=NULL)
| Determine whether or not an MDagPath is animated.
static bool | isAnimated (const MPlug &plug, bool checkParent=false, MStatus *ReturnStatus=NULL)
| Determine whether or not an MPlug is animated.
static bool | isAnimated (const MSelectionList &selectionList, bool checkParent=false, MStatus *ReturnStatus=NULL)
| Determine whether or not any member of an MSelectionList is animated.
static bool | findAnimatedPlugs (const MObject &node, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
| Find the list of attributes (MPlugs) on an MObject that is animated.
static bool | findAnimatedPlugs (const MDagPath &path, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
| Find the list of attributes (MPlugs) on an MDagPath object that is animated.
static bool | findAnimatedPlugs (const MSelectionList &selectionList, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
| Find the list of attributes (MPlugs) on any member of an MSelectionList that is animated.
static bool | findAnimation (const MPlug &plug, MObjectArray &animation, MStatus *ReturnStatus=NULL)
| Find the animCurve(s) that are animating a given attribute (MPlug).
static bool | findSetDrivenKeyAnimation (const MPlug &plug, MObjectArray &animation, MPlugArray &drivers, MStatus *ReturnStatus=NULL)
| Find any driven keyframe animCurves, the blendWeighted node and the driver attribute(s) that are animating a given attribute (MPlug).
static bool | findConstraint (const MPlug &plug, MObject &constraint, MObjectArray &targets, MStatus *ReturnStatus=NULL)
| Find any constraint that is directly driving the specified attribute.
static bool | findAnimatablePlugs (const MSelectionList &selectionList, MPlugArray &animatablePlugs)
| Find the list of attributes (MPlugs) on any member of an MSelectionList that is animatable.
static const char * | className ()
| Returns the name of this class.

## Member Function Documentation

bool isAnimated | ( | const MObject & | node,
|  | bool | checkParent = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Determine whether or not an MObject is animated.

If the MObject is a hierarchical object (such as a dag node) then you may also specify whether or not the MObject's parents are examined. In the case of instanced MObjects, all of the MObject's parents are examined.

Parameters:

  [in] | node | the MObject to examine
  [in] | checkParent | whether or not to examine if the node's parent is animated
  [out] | ReturnStatus | the return status

- MS::kSuccess if the method succeeded
- MS::kInvalidParameter if the MObject does not represent a valid Maya object
- MS::kInvalidObjectType if the MObject is not a dependency node

Returns:
  - true The MObject is animated.
  - false The MObject is not animated.

Examples:
  animExportUtil.cpp.

bool isAnimated | ( | const MDagPath & | path,
|  | bool | checkParent = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Determine whether or not an MDagPath is animated.

You may also specify whether or not the MDagPath's parent is examined. In the case of instanced MDagPath only the specified path is examined.

Parameters:

  [in] | path | the MDagPath to examine
  [in] | checkParent | whether or not to examine if the path's parent is animated
  [out] | ReturnStatus | the return status

- MS::kSuccess if the method succeeded
- MS::kInvalidParameter if the MDagPath does not represent a valid Maya object
- MS::kInvalidObjectType if the MDagPath is not a dependency node

Returns:
  - true The MDagPath is animated.
  - false The MDagPath is not animated.

bool isAnimated | ( | const MPlug & | plug,
|  | bool | checkParent = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Determine whether or not an MPlug is animated.

If the MPlug does not have an attribute specified, then the entire node is examined. You may also specify whether or not the node's parents are examined. In the case of instanced nodes, all of the node's parents are examined. If an attribute has been specified, the node's parents are not examined.

Parameters:

  [in] | plug | the MPlug to examine
  [in] | checkParent | whether or not to examine if the node's parent is animated
  [out] | ReturnStatus | the return status

- MS::kSuccess if the method succeeded
- MS::kInvalidParameter if the MPlug does not represent a valid Maya object

Returns:
  - true The MPlug is animated.
  - false The MPlug is not animated.

bool isAnimated | ( | const MSelectionList & | selectionList,
|  | bool | checkParent = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Determine whether or not any member of an MSelectionList is animated.

This is intended to work with an MSelectionList with a single entry since that provides the most useful information.

In addition to normal objects, components such as mesh vertices or faces can be easily described on an MSelectionList, making this a good way to determine if parts of a shape are animated or not.

If a member represents an MDagPath you may also specify whether or not the MDagPath's parent is examined. In the case of instanced MDagPath only the specified path is examined.

If a member represents a hierarchical MObject (such as a dag node) then you may also specify whether or not the MObject's parents are examined. In the case of instanced MObjects, all of the MObject's parents are examined.

Parameters:

  [in] | selectionList | the MSelectionList to examine
  [in] | checkParent | whether or not to examine if the node's parent is animated
  [out] | ReturnStatus | the return status

- MS::kSuccess if the method succeeded

Returns:
  - true The MSelectionList has at least one animated member.
  - false No member of the MSelectionList is animated.

bool findAnimatedPlugs | ( | const MObject & | node,
|  | MPlugArray & | animatedPlugs,
|  | bool | checkParent = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Find the list of attributes (MPlugs) on an MObject that is animated.

If the MObject is a hierarchical object (such as a dag node) then you may also specify whether or not the MObject's parents are examined. In the case of instanced MObjects, all of the MObject's parents are examined.

Parameters:

  [in] | node | the MObject to examine
  [in] | animatedPlugs | the list of attributes which are animated the array is not cleared
  [in] | checkParent | whether or not to examine if the node's parent is animated
  [out] | ReturnStatus | the return status

- MS::kSuccess if the method succeeded
- MS::kInvalidParameter if the MObject does not represent a valid Maya object
- MS::kInvalidObjectType if the MObject is not a dependency node

Returns:
  - true The MObject is animated.
  - false The MObject is not animated.

Examples:
  animExportUtil.cpp.

bool findAnimatedPlugs | ( | const MDagPath & | path,
|  | MPlugArray & | animatedPlugs,
|  | bool | checkParent = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Find the list of attributes (MPlugs) on an MDagPath object that is animated.

You may also specify whether or not the MDagPath's parent is examined. In the case of instanced MDagPath only the specified path is examined.

Parameters:

  [in] | path | the MDagPath to examine
  [in] | animatedPlugs | the list of attributes which are animated the array is not cleared
  [in] | checkParent | whether or not to examine if the path's parent is animated
  [out] | ReturnStatus | the return status

- MS::kSuccess if the method succeeded
- MS::kInvalidParameter if the MDagPath does not represent a valid Maya object
- MS::kInvalidObjectType if the MDagPath is not a dependency node

Returns:
  - true The MDagPath is animated.
  - false The MDagPath is not animated.

bool findAnimatedPlugs | ( | const MSelectionList & | selectionList,
|  | MPlugArray & | animatedPlugs,
|  | bool | checkParent = `false`,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Find the list of attributes (MPlugs) on any member of an MSelectionList that is animated.

In addition to normal objects, components such as mesh vertices or faces can be easily described on an MSelectionList, making this a good way to determine if parts of a shape are animated or not.

If a member represents an MDagPath you may also specify whether or not the MDagPath's parent is examined. In the case of instanced MDagPath only the specified path is examined.

If a member represents a hierarchical MObject (such as a dag node) then you may also specify whether or not the MObject's parents are examined. In the case of instanced MObjects, all of the MObject's parents are examined.

Parameters:

  [in] | selectionList | the MSelectionList to examine
  [in] | animatedPlugs | the list of attributes which are animated the array is not cleared
  [in] | checkParent | whether or not to examine if the node's parent is animated
  [out] | ReturnStatus | the return status

- MS::kSuccess if the method succeeded

Returns:
  - true The MSelectionList has at least one animated member.
  - false No member of the MSelectionList is animated.

bool findAnimation | ( | const MPlug & | plug,
|  | MObjectArray & | animation,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Find the animCurve(s) that are animating a given attribute (MPlug).

In most cases an attribute is animated by a single animCurve and so just that animCurve will be returned. It is possible to setup a series of connections where an attribute is animated by more than one animCurve, although Maya does not currently offer a UI to do so. Compound attributes are not expanded to include any child attributes.

Parameters:

  [in] | plug | the plug to examine for animCurve(s)
  [in] | animation | the list of animCurves which animate `plug'. The array is not cleared
  [out] | ReturnStatus | the return status

- MS::kSuccess if the method succeeded
- MS::kInvalidParameter if plug is null

Returns:
  - true The MPlug is animated.
  - false The MPlug is not animated.

Examples:
  animExportUtil.cpp.

bool findSetDrivenKeyAnimation | ( | const MPlug & | plug,
|  | MObjectArray & | animationNodes,
|  | MPlugArray & | drivers,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Find any driven keyframe animCurves, the blendWeighted node and the driver attribute(s) that are animating a given attribute (MPlug).

Or return false if no driven keyframe exists on the attribute.

A driven keyframe is similar to a regular keyframe. However, while a standard keyframe always has an x-axis of time in the graph editor, for a drivenkeyframe the user may choose any attribute as the x-axis of the graph editor. This attribute is called the driver.

In the case where there is only one driver, the animation curve will be connected directly to the driven attribute. When there are multiple drivers, the driven keyframe animCurves feed into a blendWeighted node which drives the attribute.

Compound attributes are not expanded to include any child attributes.

Parameters:

  [in] | plug | the plug to examine for animCurve(s)
  [out] | animationNodes | the list of sdk animation curves and a blendWeighted node that drive the `plug'. The array is not cleared
  [out] | drivers | the list of driver attribute(s). The array is not cleared.
  [out] | ReturnStatus | the return status

Status Codes:
  - MS::kSuccess if the method succeeded
  - MS::kInvalidParameter if plug is null

Returns:
  - true The MPlug is animated by a setDrivenKey.
  - false The MPlug is not animated by a setDrivenKey.

bool findConstraint | ( | const MPlug & | plug,
|  | MObject & | constraint,
|  | MObjectArray & | targets,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | `[static]`

Search for all occurrences

Find any constraint that is directly driving the specified attribute.

If a constraint is found, this method will also find the constraint targets. Return false if no constraint exists on the attribute.

Compound attributes are not expanded to include any child attributes.

Parameters:

  [in] | plug | the plug to examine for a constraint
  [out] | constraint | the constraint
  [out] | targets | the list of constraint targets The array is not cleared.
  [out] | ReturnStatus | the return status

Status Codes:
  - MS::kSuccess if the method succeeded
  - MS::kInvalidParameter if plug is null

Returns:
  - true The MPlug is controlled by a constraint
  - false The MPlug is not animated by a constraint

bool findAnimatablePlugs | ( | const MSelectionList & | selectionList,
|  | MPlugArray & | animatablePlugs
| ) |  | `[static]`

Search for all occurrences

Find the list of attributes (MPlugs) on any member of an MSelectionList that is animatable.

In addition to normal objects, components such as mesh vertices or faces can be easily described on an MSelectionList, making this a good way to determine if parts of a shape are animatable or not.

Parameters:

  [in] | selectionList | the MSelectionList to examine
  [in] | animatablePlugs | the list of attributes which are animatable the array is not cleared

Returns:
  - true The MSelectionList has at least one animatable member.
  - false No member of the MSelectionList is animatable.

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  The name of this class.

MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil
MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil MAnimUtil