#include <MAnimUtil.h>

Class 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

Static Public Member Functions
static bool	isAnimated (const MObject &node, bool checkParent=false, MStatus *ReturnStatus=NULL)
	Determine whether or not an MObject is animated. More...

static bool	isAnimated (const MDagPath &path, bool checkParent=false, MStatus *ReturnStatus=NULL)
	Determine whether or not an MDagPath is animated. More...

static bool	isAnimated (const MPlug &plug, bool checkParent=false, MStatus *ReturnStatus=NULL)
	Determine whether or not an MPlug is animated. More...

static bool	isAnimated (const MSelectionList &selectionList, bool checkParent=false, MStatus *ReturnStatus=NULL)
	Determine whether or not any member of an MSelectionList is animated. More...

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. More...

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. More...

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. More...

static bool	findAnimation (const MPlug &plug, MObjectArray &animation, MStatus *ReturnStatus=NULL)
	Find the animCurve(s) that are animating a given attribute (MPlug). More...

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). More...

static bool	findConstraint (const MPlug &plug, MObject &constraint, MObjectArray &targets, MStatus *ReturnStatus=NULL)
	Find any constraint that is directly driving the specified attribute. More...

static bool	findAnimatablePlugs (const MSelectionList &selectionList, MPlugArray &animatablePlugs)
	Find the list of attributes (MPlugs) on any member of an MSelectionList that is animatable. More...

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

Member Function Documentation

bool 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::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:: AbcBullet/MayaUtility.cpp, AbcExport/MayaUtility.cpp, and animExportUtil/animExportUtil.cpp.

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

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

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

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/animExportUtil.cpp.

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

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

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/animExportUtil.cpp.

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

static

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.

Examples:: atomImportExport/atomCachedPlugs.cpp.

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

static

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

Examples:: atomImportExport/atomCachedPlugs.cpp.

bool findAnimatablePlugs	(	const MSelectionList &	selectionList,
		MPlugArray &	animatablePlugs
	)

static

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.

Examples:: atomImportExport/atomImportExport.cpp.

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:

MAnimUtil.h
MAnimUtil.cpp

MAnimUtil Class Reference

Class Description

Static Public Member Functions

Member Function Documentation