MAnimUtil Class Reference
[OpenMayaAnim - API module for animation]

#include <MAnimUtil.h>

List of all members.

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:

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


Static Public Member Functions
static bool  isAnimated (const MObject &node, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool  isAnimated (const MDagPath &path, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool  isAnimated (const MPlug &plug, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool  isAnimated (const MSelectionList &selectionList, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool  findAnimatedPlugs (const MObject &node, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool  findAnimatedPlugs (const MDagPath &path, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool  findAnimatedPlugs (const MSelectionList &selectionList, MPlugArray &animatedPlugs, bool checkParent=false, MStatus *ReturnStatus=NULL)
static bool  findAnimation (const MPlug &plug, MObjectArray &animation, MStatus *ReturnStatus=NULL)

Member Function Documentation

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

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::kNullPointerArgument if the MObject does not represent a valid Maya object
  • MS::kInvalidObjectType if the MObject is not a dependency node
Returns:
Examples:
animExportUtil.cpp.

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

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::kNullPointerArgument if the MDagPath does not represent a valid Maya object
  • MS::kInvalidObjectType if the MDagPath is not a dependency node
Returns:

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

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::kNullPointerArgument if the MPlug does not represent a valid Maya object
Returns:
  • true The MPlug is animated.
  • false The MPlug is not animated.

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

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
Returns:

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

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::kNullPointerArgument if the MObject does not represent a valid Maya object
  • MS::kInvalidObjectType if the MObject is not a dependency node
Returns:
Examples:
animExportUtil.cpp.

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

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::kNullPointerArgument if the MDagPath does not represent a valid Maya object
  • MS::kInvalidObjectType if the MDagPath is not a dependency node
Returns:

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

Find the list of attributes (MPlugs) on any member of an MSelectionList that 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]  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
Returns:

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

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::kNullPointerArgument if plug is null
Returns:
  • true The MPlug is animated.
  • false The MPlug is not animated.
Examples:
animExportUtil.cpp.
Autodesk® Maya® 2011 © 1997-2010 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6