Dependency graph modifier. More...

#include <MDGModifier.h>

Inheritance diagram for MDGModifier:

Public Member Functions
	MDGModifier ()
	The class constructor.

virtual	~MDGModifier ()
	The class destructor.

MObject	createNode (const MTypeId &typeId, MStatus *ReturnStatus=NULL)
	This method adds an operation to this dependency graph modifier that will add a new dependency graph node of the given type to the dependency graph. More...

MObject	createNode (const MString &type, MStatus *ReturnStatus=NULL)
	This method adds an operation to this dependency graph modifier that will add a new dependency graph node of the given type to the dependency graph. More...

MStatus	deleteNode (const MObject &node)
	This method adds an operation to this dependency graph modifier that will delete a dependency graph node from the dependency graph. More...

MStatus	deleteNode (const MObject &node, bool includeParents)
	Introduced in 2022.0 More...

MStatus	renameNode (const MObject &node, const MString &newName)
	This method adds an operation to this dependency graph modifier that will rename a dependency graph node. More...

MStatus	setNodeLockState (const MObject &node, bool newState)
	This method adds an operation to this dependency graph modifier that will set the lock state of the node. More...

MStatus	connect (const MObject &sourceNode, const MObject &sourceAttr, const MObject &destNode, const MObject &destAttr)
	Adds an operation to this dependency graph modifier that connects two attributes of two nodes in the dependency graph. More...

MStatus	disconnect (const MObject &sourceNode, const MObject &sourceAttr, const MObject &destNode, const MObject &destAttr)
	Adds an operation to this dependency graph modifier that disconnects two attributes of two nodes in the dependency graph. More...

MStatus	connect (const MPlug &source, const MPlug &dest)
	Adds an operation to this dependency graph modifier that connects two plugs in the dependency graph. More...

MStatus	disconnect (const MPlug &source, const MPlug &dest)
	Adds an operation to this dependency graph modifier that disconnects two plugs in the dependency graph. More...

MStatus	addAttribute (const MObject &node, const MObject &attribute)
	Add a new dynamic attribute to the given dependency node. More...

MStatus	removeAttribute (const MObject &node, const MObject &attribute)
	Removes a dynamic attribute from the given dependency node. More...

MStatus	renameAttribute (const MObject &node, const MObject &attribute, const MString &shortName, const MString &longName)
	Renames a dynamic attribute on the given dependency node. More...

MStatus	addExtensionAttribute (const MNodeClass &nodeClass, const MObject &attribute)
	Add a new extension attribute to the given dependency node class. More...

MStatus	removeExtensionAttribute (const MNodeClass &nodeClass, const MObject &attribute)
	Removes an extension attribute from the given dependency node type. More...

MStatus	removeExtensionAttributeIfUnset (const MNodeClass &nodeClass, const MObject &attribute)
	Removes an extension attribute from the given dependency node type but only if there are no nodes in the graph with non-default values for this attribute. More...

MStatus	linkExtensionAttributeToPlugin (const MObject &plugin, const MObject &attribute)
	The plugin calls this to indicate that the extension attribute defines part of the plugin, regardless of the node type to which it attaches itself. More...

MStatus	unlinkExtensionAttributeFromPlugin (const MObject &mPlugin, const MObject &mAttribute)
	Tells a plugin that it no longer requires an extension attribute for operation. More...

MStatus	commandToExecute (const MString &command)
	Adds an operation to this dependency graph modifier that executes a MEL command. More...

MStatus	pythonCommandToExecute (const MString &command)
	Adds an operation to this dependency graph modifier that executes a Python command/script. More...

MStatus	newPlugValue (const MPlug &plug, MObject &plugValue)
	Adds an operation to this dependency graph modifier that sets a plug value. More...

MStatus	newPlugValueBool (const MPlug &plug, bool plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to a boolean value. More...

MStatus	newPlugValueChar (const MPlug &plug, char plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to a char value. More...

MStatus	newPlugValueDouble (const MPlug &plug, double plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to a double value. More...

MStatus	newPlugValueFloat (const MPlug &plug, float plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to a float value. More...

MStatus	newPlugValueInt (const MPlug &plug, int plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to an int value. More...

MStatus	newPlugValueInt64 (const MPlug &plug, MInt64 plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to a 64-bit int value. More...

MStatus	newPlugValueMAngle (const MPlug &plug, const MAngle &plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to an MAngle value. More...

MStatus	newPlugValueMDistance (const MPlug &plug, const MDistance &plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to an MDistance value. More...

MStatus	newPlugValueMTime (const MPlug &plug, const MTime &plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to an MTime value. More...

MStatus	newPlugValueShort (const MPlug &plug, short plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to a short value. More...

MStatus	newPlugValueString (const MPlug &plug, const MString &plugValue)
	Adds an operation to this dependency graph modifier that sets a plug to a string value. More...

MStatus	removeMultiInstance (const MPlug &plug, bool breakConnections)
	Adds an operation to this dependency graph modifier that removes an element of a multi (array) plug. More...

MStatus	setMetadata (const MObject &node, const adsk::Data::Associations &metadata)
	Adds an operation to this dependency graph modifier that replaces metadata on a specific node. More...

MStatus	deleteMetadata (const MObject &node)
	Adds an operation to this dependency graph modifier that deletes all metadata from a node. More...

MStatus	doIt ()
	Executes all of the operations that have been given to this modifier. More...

MStatus	undoIt ()
	Undoes all of the operations that have been given to this modifier. More...

MStatus	addAttribute (const MObject &node, const MObject &attribute, MFnDependencyNode::MAttrClass type)
	Deprecated in 2019.0 More...

MStatus	removeAttribute (const MObject &node, const MObject &attribute, MFnDependencyNode::MAttrClass type)
	Deprecated in 2019.0 More...

Static Public Member Functions
static const char *	className ()
	Returns the name of this class. More...

Detailed Description

Dependency graph modifier.

An MDGModifier is used to change the structure of the dependency graph. This includes adding nodes, making new connections, and removing existing connections. To perform operations using an MDGModifier, register all of the changes that are to be made and then call the doIt method to make the changes. Undo is provided through the undoIt method.

Under some situations, a doIt() call may be required to separate some of the operations. The specific case of interest involves performing a disconnect() and a deleteNode() on the same node within the stack of operations.

Assuming that the Maya model has a connected node that was going to be deleted, do the following:

MStatus cmd::redoIt()
{
    MStatus result = dgModifier.disconnect(plugA, plugB);
    if (!result)
        ...
    result = dgModifier.doIt();
    if (!result)
        ...
    result = dgModifier.deleteNode(plugBNode);
    if (!result)
        ...
    result = dgModifier.doIt();
    if (!result)
        ...
    return result;
}

Then undoIt() can be implemented as:

MStatus cmd::undoIt()
{
    MStatus result = dgModifier.undoIt();
    if (!result)
        ...
    return result;
}

MDGModifier does not understanding the hierarchical relationship between DAG nodes. When performing DG operations on DAG nodes MDagModifier should be used instead. In some cases MDagModifier may even be required when operating on non-DAG nodes. For example, a container node is a non-DAG node but it may contain DAG nodes. When the container is deleted its members will be deleted as well. Since some of those members may be DAG nodes an MDagModifier should be used to delete the container node.

Examples:: AbcImport/CreateSceneHelper.cpp, AbcImport/NodeIteratorVisitorHelper.cpp, AbcImport/util.cpp, atomImportExport/atomFileUtils.cpp, cgFx/cgfxAttrDef.cpp, cgFx/cgfxAttrDef.h, cgFx/cgfxShaderCmd.cpp, cgFx/cgfxShaderCmd.h, cgFx/cgfxShaderNode.cpp, closestPointOnCurve/closestPointOnCurveCmd.cpp, createClipCmd/createClipCmd.cpp, deletedMsgCmd/deletedMsgCmd.cpp, dx11Shader/dx11Shader.cpp, geometrySurfaceConstraint/geometrySurfaceConstraint.cpp, geometrySurfaceConstraint/geometrySurfaceConstraint.h, glslShader/GLSLShader.cpp, gpuCache/gpuCacheCmd.cpp, latticeNoise/latticeNoiseCmd.cpp, meshOpCmd/polyModifierCmd.cpp, meshOpCmd/polyModifierCmd.h, MetadataSample/createMetadataCmd.h, MetadataSample/importMetadataCmd.h, pointOnMeshInfo/pointOnMeshCmd.cpp, simplePhysicsEngine/simplePhysicsEngine.cpp, splitUVCmd/polyModifierCmd.cpp, and splitUVCmd/polyModifierCmd.h.

Member Function Documentation

MObject createNode	(	const MTypeId &	typeId,
		MStatus *	ReturnStatus = `NULL`
	)

This method adds an operation to this dependency graph modifier that will add a new dependency graph node of the given type to the dependency graph.

This method may not be used to construct new DAG nodes. Use MDagModifier for that purpose.

When createNode is called, the new node is created and the MObject handle for it is returned. It should be noted that the node will not be added to the dependency graph until the doIt method is called.

If a node is created with this method, but the operation is undone, then the MDGModifier will take responsibility for freeing the node. This will be done when the MDGModifier is destructed.

Parameters

[in]	typeId	type of the node to create
[out]	ReturnStatus	return status

Returns: A handle for the new node

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter the type passed in is not valid or the type is a DAG node (see MDagModifier)

Examples:: AbcImport/NodeIteratorVisitorHelper.cpp, and gpuCache/gpuCacheCmd.cpp.

MObject createNode	(	const MString &	type,
		MStatus *	ReturnStatus = `NULL`
	)

This method adds an operation to this dependency graph modifier that will add a new dependency graph node of the given type to the dependency graph.

This method may not be used to construct new DAG nodes. Use MDagModifier for that purpose.

When createNode is called, the new node is created and the MObject handle for it is returned. It should be noted that the node will not be added to the dependency graph until the doIt method is called.

If a node is created with this method, but the operation is undone, then the MDGModifier will take responsibility for freeing the node. This will be done when the MDGModifier is destructed.

Parameters

[in]	type	type name of the node to create
[out]	ReturnStatus	return status

Returns: A handle for the new node

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter the type passed in is not valid or the type is a DAG node (see MDagModifier)

MStatus deleteNode ( const MObject & node )

This method adds an operation to this dependency graph modifier that will delete a dependency graph node from the dependency graph.

The deleteNode method will perform some operations immediately like removing connections and removing DAG nodes from the model. However, it is still necessary to call doIt to complete the delete operation.

Special care must be taken when combining other operations with delete in the same MDGModifier and you should call doIt before and after deleteNode. Sample code showing how to disconnect and delete a node using a single MDGModifier can be found in the class description.

Note: The default behaviour when deleting a DAG node is to also include empty parents of the DAG node in the delete operation. If you do not want this behaviour use the other deleteNode method and pass false for the second (includeParents) argument.

Parameters

[in] node node to delete

Returns: Return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter the node is invalid or is NULL

Examples:: AbcImport/CameraHelper.cpp, AbcImport/CreateSceneHelper.cpp, and cgFx/cgfxAttrDef.cpp.

MStatus deleteNode	(	const MObject &	node,
		bool	includeParents
	)

Introduced in 2022.0

This method adds an operation to this dependency graph modifier that will delete a dependency graph node from the dependency graph.

2022.0:: Introduced in this version.

The deleteNode method will perform some operations immediately like removing connections and removing DAG nodes from the model. However, it is still necessary to call doIt to complete the delete operation.

Special care must be taken when combining other operations with delete in the same MDGModifier and you should call doIt before and after deleteNode. Sample code showing how to disconnect and delete a node using a single MDGModifier can be found in the class description.

Note: If includeParents is true then empty parents of the DAG node will be included in the delete operation. Pass false to only delete this node.

Parameters

[in]	node	node to delete
[in]	includeParents	delete empty DAG node parents

Returns: Return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter the node is invalid or is NULL

MStatus renameNode	(	const MObject &	node,
		const MString &	newName
	)

This method adds an operation to this dependency graph modifier that will rename a dependency graph node.

Parameters

[in]	node	node to rename
[in]	newName	new name for the node

Returns: Return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter the node is invalid or is NULL

Examples:: AbcImport/CreateSceneHelper.cpp, and sceneAssembly/adskRepresentations.cpp.

MStatus setNodeLockState	(	const MObject &	node,
		bool	newState
	)

This method adds an operation to this dependency graph modifier that will set the lock state of the node.

Parameters

[in]	node	node to toggle lock state
[in]	newState	new lock state

Returns: Return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter the node is invalid or is NULL

MStatus connect	(	const MObject &	sourceNode,
		const MObject &	sourceAttr,
		const MObject &	destNode,
		const MObject &	destAttr
	)

Adds an operation to this dependency graph modifier that connects two attributes of two nodes in the dependency graph.

The value of the destination attribute is supplied by the value of the source attribute once they are connected.

It is the users responsibility to ensure that the source and destination attributes are of compatible types. For instance, if the source attribute is a nurbs surface then the destination must also be a nurbs surface.

To connect array attributes use the other version of connect which takes MPlugs as parameters.

Parameters

[in]	sourceNode	the source node in the connection
[in]	sourceAttr	the attribute of the source node that is to be connected
[in]	destNode	the destination node in the connection
[in]	destAttr	the attribute of the destination node that is to be connected

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter one of the input objects is invalid

Examples:: AbcImport/CreateSceneHelper.cpp, AbcImport/NodeIteratorVisitorHelper.cpp, atomImportExport/atomImportExport.cpp, cgFx/cgfxAttrDef.cpp, closestPointOnCurve/closestPointOnCurveCmd.cpp, dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, gpuCache/gpuCacheCmd.cpp, latticeNoise/latticeNoiseCmd.cpp, meshOpCmd/polyModifierCmd.cpp, offsetNode/offsetNode.cpp, pointOnMeshInfo/pointOnMeshCmd.cpp, polyPrimitiveCmd/polyPrimitiveCmd.cpp, simplePhysicsEngine/simplePhysicsEngine.cpp, and splitUVCmd/polyModifierCmd.cpp.

MStatus disconnect	(	const MObject &	sourceNode,
		const MObject &	sourceAttr,
		const MObject &	destNode,
		const MObject &	destAttr
	)

Adds an operation to this dependency graph modifier that disconnects two attributes of two nodes in the dependency graph.

Parameters

[in]	sourceNode	the source node in the connection
[in]	sourceAttr	the attribute of the source node that is connected
[in]	destNode	the destination node in the connection
[in]	destAttr	the attribute of the destination node that is connected

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter one of the input objects is invalid

Examples:: AbcImport/util.cpp, cgFx/cgfxAttrDef.cpp, dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and latticeNoise/latticeNoiseCmd.cpp.

MStatus connect	(	const MPlug &	source,
		const MPlug &	dest
	)

Adds an operation to this dependency graph modifier that connects two plugs in the dependency graph.

The value of the destination plug is supplied by the value of the source plug once they are connected.

It is the users responsibility to ensure that the source and destination attributes are of compatible types. For instance, if the source attribute is a nurbs surface then the destination must also be a nurbs surface.

Parameters

[in]	source	the source plug in the connection
[in]	dest	the destination plug in the connection

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter one of the input plugs is invalid

MStatus disconnect	(	const MPlug &	source,
		const MPlug &	dest
	)

Adds an operation to this dependency graph modifier that disconnects two plugs in the dependency graph.

Parameters

[in]	source	the source plug in the connection
[in]	dest	the destination plug in the connection

Returns: The return status

Status Codes:

MS::kSuccess operation successful

MStatus addAttribute	(	const MObject &	node,
		const MObject &	attribute
	)

Add a new dynamic attribute to the given dependency node.

This method also adds all children of the attribute if it is a compound. So, if a compound attribute is being added to a node, then only the parent attribute needs to be added using this method.

Parameters

[in]	node	node to which to add the attribute
[in]	attribute	attribute to add

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter either the node or attribute is invalid or the attribute already exists.

Examples:: AbcImport/CreateSceneHelper.cpp, atomImportExport/atomFileUtils.cpp, cgFx/cgfxAttrDef.cpp, dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, and polyPrimitiveCmd/polyPrimitiveCmd.cpp.

MStatus removeAttribute	(	const MObject &	node,
		const MObject &	attribute
	)

Removes a dynamic attribute from the given dependency node.

This method also removes all children of the attribute if it is a compound.

Note: After a successful call to this method, the MObject passed to it that contains the attribute will have been reset to MObject::kNullObj because the attribute it referenced no longer exists. Thus no function sets, such as MFnAttribute, should be attached to the MObject at the time this call is made.

Parameters

[in]	node	node to add an attribute to
[in]	attribute	attribute to add

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter either the node or attribute is invalid

Examples:: cgFx/cgfxAttrDef.cpp, dx11Shader/dx11Shader.cpp, and glslShader/GLSLShader.cpp.

MStatus renameAttribute	(	const MObject &	node,
		const MObject &	attribute,
		const MString &	shortName,
		const MString &	longName
	)

Renames a dynamic attribute on the given dependency node.

Parameters

[in]	node	The node to which the attribute belongs
[in]	attribute	The attribute to rename
[in]	shortName	The new short name
[in]	longName	The new long name

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter either the node or attribute is invalid, the attribute does not exist, one of the names is empty or one of the names is already being used as an attribute on the node

MStatus addExtensionAttribute	(	const MNodeClass &	nodeClass,
		const MObject &	attribute
	)

Add a new extension attribute to the given dependency node class.

This method also adds all children of the attribute if it is a compound. So, if a compound attribute is being added to a node type, then only the parent attribute needs to be added using this method.

Parameters

[in]	nodeClass	class of node to which to add the attribute
[in]	attribute	attribute to add

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter either the node type or attribute is invalid or the attribute already exists.

MStatus removeExtensionAttribute	(	const MNodeClass &	nodeClass,
		const MObject &	attribute
	)

Removes an extension attribute from the given dependency node type.

This method also removes all children of the attribute if it is a compound.

Note: After a successful call to this method, the MObject passed to it that contains the attribute will have been reset to MObject::kNullObj because the attribute it referenced may no longer exist. Thus no function sets, such as MFnAttribute, should be attached to the MObject at the time this call is made.

Parameters

[in]	nodeClass	class of node from which to remove the attribute
[in]	attribute	attribute to remove

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter either the node type or attribute is invalid

MStatus removeExtensionAttributeIfUnset	(	const MNodeClass &	nodeClass,
		const MObject &	attribute
	)

Removes an extension attribute from the given dependency node type but only if there are no nodes in the graph with non-default values for this attribute.

This method also removes all children of the attribute if it is a compound.

Note: After a successful call to this method, the MObject passed to it that contains the attribute may have been reset to MObject::kNullObj because the attribute it referenced may no longer exist. Thus no function sets, such as MFnAttribute, should be attached to the MObject at the time this call is made.

Parameters

[in]	nodeClass	class of node from which to remove the attribute
[in]	attribute	attribute to remove

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter either the node type or attribute is invalid

MStatus linkExtensionAttributeToPlugin	(	const MObject &	mPlugin,
		const MObject &	mAttribute
	)

The plugin calls this to indicate that the extension attribute defines part of the plugin, regardless of the node type to which it attaches itself.

This requirement is used when the plugin is checked to see if it is in use or if is able to be unloaded or if it is required as part of a stored file.

This should only be called once for root attributes (i.e. those with no parent). It is an error to call it with a child attribute. All children and ancestors are recursively tested. Forcing it to be called only on the root keeps the calling code simple and avoids duplicate calls.

Parameters

[in]	mPlugin	plugin to which the attribute is to be tied
[in]	mAttribute	attribute to associate with the plugin, must not have a parent

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kFailure the attribute could not be referenced by the plugin
MS::kInvalidParameter the plugin or attribute were not valid for the operation

MStatus unlinkExtensionAttributeFromPlugin	(	const MObject &	mPlugin,
		const MObject &	mAttribute
	)

Tells a plugin that it no longer requires an extension attribute for operation.

This requirement is used when the plugin is checked to see if it is in use or if is able to be unloaded.

This should only be called once for root attributes (i.e. those with no parent). It is an error to call it with a child attribute. All children and ancestors are recursively removed. Forcing it to be called only on the root keeps the calling code simple and avoids duplicate calls.

Parameters

[in]	mPlugin	plugin from which the attribute is to be released
[in]	mAttribute	attribute to disassociate with the plugin, must not have a parent

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kFailure the attribute reference didn't exist on the plugin or could not be removed
MS::kInvalidParameter the plugin or attribute were not valid for the operation

MStatus commandToExecute ( const MString & command )

Adds an operation to this dependency graph modifier that executes a MEL command.

The command should be fully undoable, otherwise unpredictable behaviour may result. For example, assume that the command is a MEL procedure which contains some undoable commands and some non-undoable commands. When doIt() is first called, the procedure will be executed and all of its commands will take effect. If undoIt() is subsequently called, only the undoable portions of the script will be undone, which may leave Maya in an unstable or inconsistent state. Any subsequent calls to doIt() will only redo the commands which were undone, the non-undoable portions will not be re-executed.

If the command contains no undoable portions whatsoever, the call to doIt() may fail (it depends upon the state of the MDGModifier at the time), but only after executing the command.

NOTE: It is best to use multiple commandToExecute() calls rather than batching multiple commands into one call to commandToExecute(). Using one command per call to commandToExecute() will simplify the undo stack which is important in case of command failure.

Parameters

[in] command the command that will be executed (should be undoable)

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInsufficientMemory No memory available.
MS::kFailure operation failed

Examples:: AbcImport/util.cpp, and cgFx/cgfxAttrDef.cpp.

MStatus pythonCommandToExecute ( const MString & command )

Adds an operation to this dependency graph modifier that executes a Python command/script.

As noted for commandToExecute(), the specified command should be fully undoable, otherwise unpredictable behaviour may result. However, this is even more true for a Python command/script because it has access to the Maya API. Most Maya commands which modify the scene are undoable, but modifications made through the API are not.

For example, assume that the script uses the 'polySphere' command to create a mesh sphere, but then modifies its shape using API calls. When the MDGModifier's doIt() is first called, everything will work as planned and a modified sphere will result. When undoIt() is called, only the undoable 'polySphere' command will be done, not modifications made through the API. That's no loss since the sphere is being deleted. However, if doIt() is now called a second time, only those the undoable actions will be redone, so the 'polySphere' command will be redone, but the API calls to modify it will not, leaving an unmodified sphere. Variants on the same thing can end up corrupting your model and even crashing Maya.

If the command contains no undoable portions whatsoever, the call to doIt() may fail (it depends upon the state of the MDGModifier at the time), but only after executing the command.

Python Notes

In Python this method can also be passed a Python callable which will be passed no arguments when it is executed.

Parameters

[in] command the command that will be executed (should be undoable)

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInsufficientMemory No memory available.
MS::kFailure operation failed

MStatus newPlugValue	(	const MPlug &	plug,
		MObject &	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug value.

Plug values can be created with the MFnNumericData class.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug or plugValue are null
MS::kInsufficientMemory No memory available.
MS::kFailure operation failed

Examples:: geometrySurfaceConstraint/geometrySurfaceConstraint.cpp.

MStatus newPlugValueBool	(	const MPlug &	plug,
		bool	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to a boolean value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

Examples:: AbcImport/CreateSceneHelper.cpp.

MStatus newPlugValueChar	(	const MPlug &	plug,
		char	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to a char value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus newPlugValueDouble	(	const MPlug &	plug,
		double	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to a double value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus newPlugValueFloat	(	const MPlug &	plug,
		float	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to a float value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus newPlugValueInt	(	const MPlug &	plug,
		int	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to an int value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

Examples:: gpuCache/gpuCacheCmd.cpp.

MStatus newPlugValueInt64	(	const MPlug &	plug,
		MInt64	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to a 64-bit int value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus newPlugValueMAngle	(	const MPlug &	plug,
		const MAngle &	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to an MAngle value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus newPlugValueMDistance	(	const MPlug &	plug,
		const MDistance &	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to an MDistance value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus newPlugValueMTime	(	const MPlug &	plug,
		const MTime &	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to an MTime value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus newPlugValueShort	(	const MPlug &	plug,
		short	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to a short value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus newPlugValueString	(	const MPlug &	plug,
		const MString &	plugValue
	)

Adds an operation to this dependency graph modifier that sets a plug to a string value.

Parameters

[in]	plug	the plug to set
[in]	plugValue	the value to set

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus removeMultiInstance	(	const MPlug &	plug,
		bool	breakConnections
	)

Adds an operation to this dependency graph modifier that removes an element of a multi (array) plug.

If breakConnections is true, all connections to the attribute will be broken before the element is removed. If false, then the operation will fail if the element is connected.

Parameters

[in]	plug	the plug to remove
[in]	breakConnections	whether to break connections before removing the element

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter plug is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus setMetadata	(	const MObject &	node,
		const adsk::Data::Associations &	metadata
	)

Adds an operation to this dependency graph modifier that replaces metadata on a specific node.

Parameters

[in]	node	The node to receive the metadata
[in]	metadata	The metadata values it will receive

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter node is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus deleteMetadata ( const MObject & node )

Adds an operation to this dependency graph modifier that deletes all metadata from a node.

Parameters

[in] node the node from which the metadata is to be removed

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter node is null
MS::kInsufficientMemory No memory available
MS::kFailure operation failed

MStatus doIt ( )

Executes all of the operations that have been given to this modifier.

It is only valid to call this method after all of the operations have been specified. This method may also be called after undoIt to redo the operations.

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kFailure operation failed because at least one of the operations was invalid

Examples:: AbcImport/CameraHelper.cpp, AbcImport/CreateSceneHelper.cpp, AbcImport/NodeIteratorVisitorHelper.cpp, AbcImport/util.cpp, atomImportExport/atomFileUtils.cpp, cgFx/cgfxAttrDef.cpp, cgFx/cgfxShaderNode.cpp, closestPointOnCurve/closestPointOnCurveCmd.cpp, dx11Shader/dx11Shader.cpp, glslShader/GLSLShader.cpp, gpuCache/gpuCacheCmd.cpp, latticeNoise/latticeNoiseCmd.cpp, meshOpCmd/polyModifierCmd.cpp, pointOnMeshInfo/pointOnMeshCmd.cpp, polyPrimitiveCmd/polyPrimitiveCmd.cpp, sceneAssembly/adskRepresentations.cpp, simplePhysicsEngine/simplePhysicsEngine.cpp, and splitUVCmd/polyModifierCmd.cpp.

MStatus undoIt ( )

Undoes all of the operations that have been given to this modifier.

It is only valid to call this method after the doIt method has been called.

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kFailure operation failed because at least one of the operations was invalid

Examples:: gpuCache/gpuCacheCmd.cpp, meshOpCmd/polyModifierCmd.cpp, polyPrimitiveCmd/polyPrimitiveCmd.cpp, and splitUVCmd/polyModifierCmd.cpp.

const char * className ( )

static

Returns the name of this class.

Returns: The name of this class.

MStatus addAttribute	(	const MObject &	node,
		const MObject &	attribute,
		MFnDependencyNode::MAttrClass	type
	)

Deprecated in 2019.0

This method also adds all children of the attribute if it is a compound.

Deprecated:: Use the method MDGModifier::addAttribute( const MObject&, const MObject& ) instead

2019.0:: Deprecated in this version.

So, if a compound attribute is being added to a node, then only the parent attribute needs to be added using this method.

Parameters

[in]	node	node to add an attribute to
[in]	attribute	attribute to add
[in]	type	determines if this is a local or global attribute

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter either the node or attribute is invalid or the attribute already exists.

MStatus removeAttribute	(	const MObject &	node,
		const MObject &	attribute,
		MFnDependencyNode::MAttrClass	type
	)

Deprecated in 2019.0

Removes a dynamic attribute from the given dependency node.

Deprecated:: Use MDGModifier::removeAttribute( const MObject&, const MObject& ) instead

2019.0:: Deprecated in this version.

This method also removes all children of the attribute if it is a compound.

Note: After a successful call to this method, the MObject passed to it that contains the attribute will have been reset to MObject::kNullObj because the attribute it referenced no longer exists. Thus no function sets, such as MFnAttribute, should be attached to the MObject at the time this call is made.

Parameters

[in]	node	node to add an attribute to
[in]	attribute	attribute to add
[in]	type	determines if this is a local or global attribute

Returns: The return status

Status Codes:

MS::kSuccess operation successful
MS::kInvalidParameter either the node or attribute is invalid

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

MDGModifier.h
MDGModifier.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation