Static class providing common animation helper methods. More...

#include <MAnimUtil.h>

Public Types
enum	AnimLayerFilter { kAllLayers, kAllUnlockedLayers, kAffectingLayers, kAffectingUnlockedLayers, kActiveLayer }
	Introduced in 2027.0 More...

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 bool	findAnimationLayers (const MPlug &plug, MObjectArray &layers, MPlugArray &plugs, MStatus *ReturnStatus=NULL)
	Find the animation layers that a given attribute belongs to. More...

static bool	findAnimationLayers (const MPlug &plug, MObjectArray &layers, AnimLayerFilter filter=MAnimUtil::AnimLayerFilter::kAllLayers, MStatus *ReturnStatus=NULL)
	Introduced in 2027.0 More...

static MObject	findActiveAnimationLayer (const MPlug &plug, MStatus *ReturnStatus=NULL)
	Introduced in 2027.0 More...

static MPlug	findBlendNodeInputPlug (const MPlug &plug, const MObject &animLayer=MObject::kNullObj, MStatus *ReturnStatus=NULL)
	Introduced in 2027.0 More...

static MObject	findAnimCurve (const MPlug &plug, const MObject &animLayer=MObject::kNullObj, MStatus *ReturnStatus=NULL)
	Introduced in 2027.0 More...

static MObject	createAnimCurve (const MPlug &plug, MDGModifier &modifier, const MObject &animLayer=MObject::kNullObj, MStatus *ReturnStatus=NULL)
	Introduced in 2027.0 More...

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

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

Member Enumeration Documentation

enum AnimLayerFilter

Introduced in 2027.0

2027.0:: Introduced in this version.

Enumerator
kAllLayers	All animation layers of the plug.
kAllUnlockedLayers	All unlocked animation layers of the plug.
kAffectingLayers	Animation layers affecting the value of the plug.
kAffectingUnlockedLayers	Unlocked animation layers affecting the value of the plug.
kActiveLayer	The active animation layer used for keying of the plug.

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.

bool findAnimationLayers	(	const MPlug &	plug,
		MObjectArray &	animLayers,
		MPlugArray &	plugs,
		MStatus *	ReturnStatus = `NULL`
	)

static

Find the animation layers that a given attribute belongs to.

If animation layers are found, it will also return the plug connected to each corresponding animation layer blend node.

Parameters

[in]	plug	the plug to examine for animation layers
[out]	animLayers	the list of animation layer node objects that this plug belongs to. Will be empty if the plug doesn't belong to any. The array is not cleared.
[out]	plugs	the list of plugs connected to each animation layer blend node. So the length of the plug array will be the same as the animLayer array with i'th plug in the plug array being controlled by the i'th animation layer in the animLayers array. 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 belongs to at least one animation layer.
false The MPlug doesn't belong to any animation layer.

Examples:: atomImportExport/atomCachedPlugs.cpp, and atomImportExport/atomImportExport.cpp.

bool findAnimationLayers	(	const MPlug &	plug,
		MObjectArray &	layers,
		AnimLayerFilter	filter = `MAnimUtil::AnimLayerFilter::kAllLayers`,
		MStatus *	ReturnStatus = `NULL`
	)

static

Introduced in 2027.0

Finds all animation layers that affect the specified plug, according to the given filter.

2027.0:: Introduced in this version.

This method retrieves the animation layers associated with the given plug, filtered according to the specified AnimLayerFilter. The filter can be used to select only the active layer, all layers, all unlocked layers, or only those layers that are currently affecting the plug.

Parameters

[in]	plug	The plug for which to find animation layers.
[out]	layers	The array to receive the animation layer MObjects. The array is not cleared.
[in]	filter	The filter specifying which layers to include (e.g., active, all, unlocked, affecting).
[out]	ReturnStatus	Optional pointer to receive the status of the operation. MS::kSuccess if the operation succeeded. MS::kInvalidParameter if the plug is null or invalid.

Returns

true At least one animation layer was found for the plug.
false No animation layers were found for the plug.

MObject findActiveAnimationLayer	(	const MPlug &	plug,
		MStatus *	ReturnStatus = `NULL`
	)

static

Introduced in 2027.0

Finds the currently active animation layer associated with a given plug.

2027.0:: Introduced in this version.

This function retrieves the animation layer that is currently active for keying operations on that plug. If a valid animation layer is found, its corresponding MObject is returned. Otherwise, MObject::kNullObj is returned.

Parameters

plug	The plug for which to find the active animation layer.
ReturnStatus	Optional pointer to an MStatus object to receive the status of the operation.

Returns: MObject The MObject representing the active animation layer, or MObject::kNullObj if none is found.

MPlug findBlendNodeInputPlug	(	const MPlug &	plug,
		const MObject &	animLayer = `MObject::kNullObj`,
		MStatus *	ReturnStatus = `NULL`
	)

static

Introduced in 2027.0

Finds the input plug of the blend node of the specified animation layer for a given plug.

2027.0:: Introduced in this version.

This method retrieves the input plug of the blend node of the specified animation layer for the given plug.

Parameters

[in]	plug	The plug for which to find the animation layer plug.
[in]	animLayer	The MObject representing the animation layer. If null, the active layer is used.
[out]	ReturnStatus	Optional pointer to receive the status of the operation. MS::kSuccess if the operation succeeded. MS::kInvalidParameter if the plug is null or invalid.

Returns: The MPlug representing the input to the blend node for the specified animation layer, or an empty MPlug if not found.

MObject findAnimCurve	(	const MPlug &	plug,
		const MObject &	animLayer = `MObject::kNullObj`,
		MStatus *	ReturnStatus = `NULL`
	)

static

Introduced in 2027.0

Finds an animCurve node used by the specified plug.

2027.0:: Introduced in this version.

If an animCurve node already exists for the given plug, it is returned. When animation layers are used by the plug, this will be the animCurve for an animation layer.

Parameters

[in]	plug	The plug for which to find or create the animCurve.
[in]	animLayer	The MObject representing the animation layer. If null, the active layer is used.
[out]	ReturnStatus	Optional pointer to receive the status of the operation. MS::kSuccess if the operation succeeded. MS::kInvalidParameter if the plug is null or invalid.

Returns: The MObject representing the animCurve node if found, or MObject::kNullObj if not found.

MObject createAnimCurve	(	const MPlug &	plug,
		MDGModifier &	modifier,
		const MObject &	animLayer = `MObject::kNullObj`,
		MStatus *	ReturnStatus = `NULL`
	)

static

Introduced in 2027.0

Finds or creates an animCurve node connected to the specified plug.

2027.0:: Introduced in this version.

If an animCurve node already exists for the given plug, it is returned. If not a new animCurve node is created and connected to the plug. When animation layers are used, this will create the animCurve for an animation layer.

Parameters

[in]	plug	The plug for which to find or create the animCurve.
[in]	modifier	Optional pointer to an MDGModifier. If provided, allows creation of a new animCurve.
[in]	animLayer	The MObject representing the animation layer. If null, the active layer is used.
[out]	ReturnStatus	Optional pointer to receive the status of the operation. MS::kSuccess if the operation succeeded. MS::kInvalidParameter if the plug is null or invalid.

Returns: The MObject representing the animCurve node if found or created, or MObject::kNullObj if not found/created.

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

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation