MFnDependencyNode Class Reference
[OpenMaya - API module for common classes, FunctionSet classes]

#include <MFnDependencyNode.h>

Inheritance diagram for MFnDependencyNode:

Inheritance graph
[legend]
Collaboration diagram for MFnDependencyNode:

Collaboration graph
[legend]

List of all members.

Detailed Description

Dependency node function set.

MFnDependencyNode allows the creation and manipulation of dependency graph nodes. Traversal of the dependency graph is possible using the getConnections method.

This function set does not support creation or removal of connections. MDGModifier should be used for that purpose.

Examples:

affectsNode.cpp, animExportUtil.cpp, animInfoCmd.cpp, blindComplexDataCmd.cpp, blindDoubleDataCmd.cpp, blindShortDataCmd.cpp, cgfxAttrDef.cpp, cgfxAttrDef.h, cgfxShaderCmd.cpp, cgfxShaderCmd.h, cgfxShaderNode.cpp, closestPointCmd.cpp, closestPointOnCurveCmd.cpp, clothPaintAttrCmd.cpp, componentScaleManip.cpp, customAttrManip.cpp, cvColorNode.cpp, cvColorShader.cpp, D3DTextureItem.cpp, D3DViewportRenderer.cpp, dagPoseInfoCmd.cpp, deletedMsgCmd.cpp, exportJointClusterDataCmd.cpp, filteredAsciiFile.cpp, findFileTexturesCmd.cpp, findTexturesPerPolygonCmd.cpp, footPrintManip.cpp, getAttrAffectsCmd.cpp, GLSLShaderNode.cpp, GLSLShaderNode.h, hairCollisionSolver.cpp, hwDecalBumpShader_NV20.cpp, hwPhongShaderBehavior.cpp, hwReflectBumpShader_NV20.cpp, hwRefractReflectShader_NV20.cpp, hwToonShader_NV20.cpp, hwUnlitShader.cpp, instancerListCmd.cpp, intersectCmd.cpp, latticeNoiseCmd.cpp, lepTranslator.cpp, listPolyHolesCmd.cpp, lockEvent.cpp, maTranslator.cpp, meshOpCmd.cpp, motionTraceCmd.cpp, moveManip.cpp, MTextureCache.cpp, narrowPolyViewer.h, nodeCreatedCBCmd.cpp, nodeInfoCmd.cpp, NodeMonitor.cpp, offsetNode.cpp, ownerEmitter.cpp, pluginMain.cpp, pointOnMeshCmd.cpp, polyModifierCmd.cpp, polyPrimitiveCmd.cpp, polyWriter.cpp, rockingTransformCheck.cpp, rotateManip.cpp, ShadingConnection.cpp, simpleEmitter.cpp, simpleFluidEmitter.cpp, slopeShaderBehavior.cpp, splitUVCmd.cpp, squareScaleManipContext.cpp, surfaceBumpManip.cpp, sweptEmitter.cpp, swissArmyManip.cpp, torusField.cpp, and whatisCmd.cpp.


Public Types

enum  MAttrClass { kGlobalDynamicAttr = 1, kLocalDynamicAttr, kNormalAttr, kInvalidAttr }
 Specifies the scope of the attribute. More...
enum  MdgTimerState { kTimerOff, kTimerOn, kTimerUninitialized, kTimerInvalidState }
 Possible states for the node's timer. More...
enum  MdgTimerMetric {
  kTimerMetric_callback, kTimerMetric_compute, kTimerMetric_dirty, kTimerMetric_draw,
  kTimerMetric_fetch, kTimerMetric_callbackViaAPI, kTimerMetric_callbackNotViaAPI, kTimerMetric_computeDuringCallback,
  kTimerMetric_computeNotDuringCallback
}
 The different timer metrics which can be queried. More...
enum  MdgTimerType { kTimerType_self, kTimerType_inclusive, kTimerType_count }
 The types of timers which can be queried. More...

Public Member Functions

virtual MFn::Type type () const
 Function set type.
virtual ~MFnDependencyNode ()
 Destructor.
 MFnDependencyNode ()
 Default constructor.
 MFnDependencyNode (MObject &object, MStatus *ReturnStatus=NULL)
 Constructor.
MObject create (const MTypeId &typeId, MStatus *ReturnStatus=NULL)
MObject create (const MTypeId &typeId, const MString &name, MStatus *ReturnStatus=NULL)
MObject create (const MString &type, MStatus *ReturnStatus=NULL)
MObject create (const MString &type, const MString &name, MStatus *ReturnStatus=NULL)
MTypeId typeId (MStatus *ReturnStatus=NULL) const
MString typeName (MStatus *ReturnStatus=NULL) const
MString name (MStatus *ReturnStatus=NULL) const
MString pluginName (MStatus *ReturnStatus=NULL) const
MString setName (const MString &name, MStatus *ReturnStatus=NULL)
MStatus getConnections (MPlugArray &array) const
unsigned int attributeCount (MStatus *ReturnStatus=NULL) const
MObject attribute (unsigned int index, MStatus *ReturnStatus=NULL) const
MObject reorderedAttribute (unsigned int index, MStatus *ReturnStatus=NULL) const
MObject attribute (const MString &attrName, MStatus *ReturnStatus=NULL) const
MAttrClass attributeClass (const MObject &attr, MStatus *ReturnStatus=NULL) const
MStatus getAffectedAttributes (const MObject &attr, MObjectArray &affectedAttributes) const
MStatus getAffectedByAttributes (const MObject &attr, MObjectArray &affectedByAttributes) const
MPlug findPlug (const MObject &attr, bool wantNetworkedPlug, MStatus *ReturnStatus=NULL) const
MPlug findPlug (const MString &attrName, bool wantNetworkedPlug, MStatus *ReturnStatus=NULL) const
MPlug findPlug (const MObject &attr, MStatus *ReturnStatus=NULL) const
 This method is obsolete.
MPlug findPlug (const MString &attrName, MStatus *ReturnStatus=NULL) const
 This method is obsolete.
MStatus addAttribute (const MObject &attr, MAttrClass type=kLocalDynamicAttr)
MStatus removeAttribute (const MObject &attr, MAttrClass type=kLocalDynamicAttr)
MPxNode * userNode (MStatus *ReturnStatus=NULL) const
bool isFromReferencedFile (MStatus *ReturnStatus=NULL) const
bool isShared (MStatus *ReturnStatus=NULL) const
bool hasUniqueName (MStatus *ReturnStatus=NULL) const
MString parentNamespace (MStatus *ReturnStatus=NULL) const
bool isLocked (MStatus *ReturnStatus=NULL) const
MStatus setLocked (bool locked)
bool isNewAttribute (const MObject &attr, MStatus *ReturnStatus=NULL) const
MStatus setFlag (unsigned int flag, bool state)
bool isFlagSet (unsigned int flag, MStatus *ReturnStatus=NULL) const
bool isDefaultNode (MStatus *ReturnStatus=NULL) const
MStatus setDoNotWrite (bool flag)
bool canBeWritten (MStatus *ReturnStatus=NULL) const
bool hasAttribute (const MString &name, MStatus *ReturnStatus=NULL) const
MObject getAliasAttr (bool force, MStatus *ReturnStatus=NULL)
bool setAlias (const MString &alias, const MString &name, const MPlug &plug, bool add=true, MStatus *ReturnStatus=NULL)
bool findAlias (const MString &alias, MObject &attrObj, MStatus *ReturnStatus=NULL) const
bool getAliasList (MStringArray &strArray, MStatus *ReturnStatus=NULL)
MString plugsAlias (const MPlug &plug, MStatus *ReturnStatus=NULL)
 MFnDependencyNode (const MObject &object, MStatus *ReturnStatus=NULL)
 NO SCRIPT SUPPORT.
bool getPlugsAlias (const MPlug &plug, MString &aliasName, MStatus *ReturnStatus=NULL)
 NO SCRIPT SUPPORT.
MStatus dgTimerOn ()
MStatus dgTimerOff ()
MdgTimerState dgTimerQueryState (MStatus *ReturnStatus=NULL)
MStatus dgTimerReset ()
double dgTimer (const MdgTimerMetric timerMetric, const MdgTimerType timerType, MStatus *ReturnStatus=NULL) const
MStatus dgCallbacks (const MdgTimerType type, MStringArray &callbackName, MDoubleArray &value)
MStatus dgCallbackIds (const MdgTimerType type, const MString &callbackName, MCallbackIdArray &callbackId, MDoubleArray &value)

Static Public Member Functions

static MString classification (const MString &nodeTypeName)
static unsigned int allocateFlag (const MString pluginName, MStatus *ReturnStatus=NULL)
static MStatus deallocateFlag (const MString pluginName, unsigned int flag)
static MStatus deallocateAllFlags (const MString pluginName)

Protected Member Functions

virtual const char * className () const
 Class name.

Member Enumeration Documentation

enum MFnDependencyNode::MAttrClass

Specifies the scope of the attribute.

Enumerator:
kGlobalDynamicAttr  Dynamically added, applies to all nodes of this type.
kLocalDynamicAttr  Dynamically added, only applies to this specific node.
kNormalAttr  Static attribute which is part of the original definition for this node type.
kInvalidAttr   

enum MFnDependencyNode::MdgTimerState

Possible states for the node's timer.

Enumerator:
kTimerOff   
kTimerOn   
kTimerUninitialized   
kTimerInvalidState   

enum MFnDependencyNode::MdgTimerMetric

The different timer metrics which can be queried.

Enumerator:
kTimerMetric_callback  Time spent within node callbacks for this node.
kTimerMetric_compute  Time spent within the compute method for this node.
kTimerMetric_dirty  Time spent propogating dirty messages from this node.
kTimerMetric_draw  Time spent drawing this node.
kTimerMetric_fetch  Time spent fetching data from plugs.
kTimerMetric_callbackViaAPI  Time spent in callbacks which were registered through the API.
kTimerMetric_callbackNotViaAPI  Time spent in callbacks not registered through the API (i.e internal Maya callbacks).
kTimerMetric_computeDuringCallback  Time spent in this node's compute while executing node callbacks on any node.
kTimerMetric_computeNotDuringCallback  Time spent in this nodes compute when not executing any node callbacks on any nodes.

enum MFnDependencyNode::MdgTimerType

The types of timers which can be queried.

Enumerator:
kTimerType_self  Time spent performing an operation, not including any time spent by child operations. For example, if we are drawing a node and that requires a compute, self time will only include the time spent drawing and not the compute time. Self time measures wall-clock time as opposed to CPU time and the values are in seconds.
kTimerType_inclusive  Time spent performing an operation including all time spent by child operations. For example, if we are drawing a node and that requires a compute, inclusive time is the time for the draw plus compute. Inclusive time measure wall-clock time as opposed to CPU time and the values are in seconds.
kTimerType_count  The number of operations that occurred. Ideally we should return an integer when this timer type is queried, but there are two advantages to using a double. 1) it keeps the interface consistent and 2) integer has a fixed upper bound of roughly four billion so using a double allows us to exceed this.

Constructor & Destructor Documentation

MFnDependencyNode::MFnDependencyNode ( MObject &  object,
MStatus *  ReturnStatus = NULL 
)

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters:
[in] object The MObject to attach the function set to
[out] ReturnStatus the return status
Status Codes:

MFnDependencyNode::MFnDependencyNode ( const MObject &  object,
MStatus *  ReturnStatus = NULL 
)

NO SCRIPT SUPPORT.

Constructor

Class constructor that initializes the function set to the given MObject.

Parameters:
[in] object The MObject to attach the function set to
[out] ReturnStatus the return status
Status Codes:

Member Function Documentation

MFn::Type MFnDependencyNode::type (  )  const [virtual]

Function set type.

Return the class type : MFn::kDependencyNode

Reimplemented from MFnBase.

Reimplemented in MFnAirField, MFnAmbientLight, MFnAnimCurve, MFnAnisotropyShader, MFnAreaLight, MFnBlendShapeDeformer, MFnBlinnShader, MFnCamera, MFnCharacter, MFnCircleSweepManip, MFnClip, MFnContainerNode, MFnCurveSegmentManip, MFnDagNode, MFnDirectionalLight, MFnDirectionManip, MFnDiscManip, MFnDistanceManip, MFnDragField, MFnExpression, MFnField, MFnFluid, MFnFreePointTriadManip, MFnGeometryFilter, MFnGravityField, MFnHikEffector, MFnIkEffector, MFnIkHandle, MFnIkJoint, MFnIkSolver, MFnInstancer, MFnLambertShader, MFnLattice, MFnLatticeDeformer, MFnLayeredShader, MFnLight, MFnManip3D, MFnMesh, MFnMotionPath, MFnNewtonField, MFnNonAmbientLight, MFnNonExtendedLight, MFnNurbsCurve, MFnNurbsSurface, MFnParticleSystem, MFnPartition, MFnPfxGeometry, MFnPhongEShader, MFnPhongShader, MFnPointLight, MFnPointOnCurveManip, MFnPointOnSurfaceManip, MFnRadialField, MFnReflectShader, MFnRenderLayer, MFnRenderPass, MFnRotateManip, MFnScaleManip, MFnSet, MFnSkinCluster, MFnSpotLight, MFnStateManip, MFnSubd, MFnToggleManip, MFnTransform, MFnTurbulenceField, MFnUniformField, MFnVolumeAxisField, MFnVolumeLight, MFnVortexField, MFnWeightGeometryFilter, and MFnWireDeformer.

const char * MFnDependencyNode::className (  )  const [protected, virtual]

Class name.

Return the class name : "MFnDependencyNode"

Reimplemented from MFnBase.

Reimplemented in MFnAirField, MFnAmbientLight, MFnAnimCurve, MFnAnisotropyShader, MFnAreaLight, MFnBlendShapeDeformer, MFnBlinnShader, MFnCamera, MFnCharacter, MFnCircleSweepManip, MFnClip, MFnContainerNode, MFnCurveSegmentManip, MFnDagNode, MFnDirectionalLight, MFnDirectionManip, MFnDiscManip, MFnDistanceManip, MFnDragField, MFnExpression, MFnField, MFnFluid, MFnFreePointTriadManip, MFnGeometryFilter, MFnGravityField, MFnHikEffector, MFnIkEffector, MFnIkHandle, MFnIkJoint, MFnIkSolver, MFnInstancer, MFnLambertShader, MFnLattice, MFnLatticeDeformer, MFnLayeredShader, MFnLight, MFnManip3D, MFnMesh, MFnMotionPath, MFnNewtonField, MFnNonAmbientLight, MFnNonExtendedLight, MFnNurbsCurve, MFnNurbsSurface, MFnParticleSystem, MFnPartition, MFnPfxGeometry, MFnPhongEShader, MFnPhongShader, MFnPointLight, MFnPointOnCurveManip, MFnPointOnSurfaceManip, MFnRadialField, MFnReflectShader, MFnRenderLayer, MFnRenderPass, MFnRotateManip, MFnScaleManip, MFnSet, MFnSkinCluster, MFnSpotLight, MFnStateManip, MFnSubd, MFnToggleManip, MFnTransform, MFnTurbulenceField, MFnUniformField, MFnVolumeAxisField, MFnVolumeLight, MFnVortexField, MFnWeightGeometryFilter, and MFnWireDeformer.

MObject MFnDependencyNode::create ( const MTypeId &  typeId,
MStatus *  ReturnStatus = NULL 
)

Creates a new dependency node with the given type tag. The new node is placed into the dependency graph.

If the node is a DAG node, it will be parented to a transform.

The initial name for the node will be the node's "typeName" followed by a number to make the instance unique. For example, the first transform node created will be named "transform1".

Parameters:
[in] typeId type id of node to be created
[out] ReturnStatus return status
Returns:
A pointer to the new dependency node object
Status Codes:
Examples:
closestPointOnCurveCmd.cpp, latticeNoiseCmd.cpp, and pointOnMeshCmd.cpp.

MObject MFnDependencyNode::create ( const MTypeId &  typeId,
const MString &  name,
MStatus *  ReturnStatus = NULL 
)

Creates a new dependency node with the given type tag. The new node is placed into the dependency graph.

If the node is a DAG node, it will be parented to a transform.

Parameters:
[in] typeId type id of node to be created
[in] name the name to be assigned to the new node If the node's name is not unique, it will be given a unique name by changing its numerical suffix. For example, if this node is called "myNode" and a node by the same name exists, this node will be renamed to "myNode1".
[out] ReturnStatus return status
Returns:
A pointer to the new dependency node object
Status Codes:

MObject MFnDependencyNode::create ( const MString &  type,
MStatus *  ReturnStatus = NULL 
)

Creates a new dependency node with the given type. The new node is placed into the dependency graph.

If the node is a DAG node, it will be parented to a transform.

The initial name for the node will be the node's "typeName" followed by a number to make the instance unique. For example, the first transform node created will be named "transform1".

Parameters:
[in] type int name for the type of dependency node
[out] ReturnStatus return status
Returns:
A pointer to the new dependency node object
Status Codes:

MObject MFnDependencyNode::create ( const MString &  type,
const MString &  name,
MStatus *  ReturnStatus = NULL 
)

Creates a new dependency node with the given type. The new node is placed into the dependency graph.

If the node is a DAG node, it will be parented to a transform.

Parameters:
[in] type int name for the type of dependency node
[in] name the name to be assigned to the new node If the node's name is not unique, it will be given a unique name by changing its numerical suffix. For example, if this node is called "myNode" and a node by the same name exists, this node will be renamed to "myNode1".
[out] ReturnStatus return status
Returns:
A pointer to the new dependency node object
Status Codes:

Reimplemented in MFnCircleSweepManip, MFnDirectionManip, MFnDiscManip, MFnDistanceManip, MFnFreePointTriadManip, MFnPointOnCurveManip, MFnPointOnSurfaceManip, MFnRotateManip, MFnScaleManip, MFnStateManip, and MFnToggleManip.

MTypeId MFnDependencyNode::typeId ( MStatus *  ReturnStatus = NULL  )  const

Returns the type id of this node. The type is is the 4 byte code that is used in the binary file format to identify the type of this node.

Parameters:
[out] ReturnStatus return status
Returns:
The type id of this node
Status Codes:
Examples:
cgfxShaderCmd.cpp.

MString MFnDependencyNode::typeName ( MStatus *  ReturnStatus = NULL  )  const

Returns the type name of this node. The string returned is the name of the node type as it is used in the ascii file format.

Parameters:
[out] ReturnStatus return status
Returns:
The type name of this node
Status Codes:
Examples:
findFileTexturesCmd.cpp.

MString MFnDependencyNode::name ( MStatus *  ReturnStatus = NULL  )  const

Returns the name of this node. Note that if the object the instance of this class is attached to is data instead of being in the graph (ie. the object was created by one of the MFn*Data function sets, or was passed to an MPxNode::compute function in a data block) then the name method will not work.

Parameters:
[out] ReturnStatus return status
Returns:
The name of this node
Status Codes:
Examples:
animInfoCmd.cpp, cgfxAttrDef.cpp, cgfxShaderCmd.cpp, cleanPerFaceAssignmentCmd.cpp, closestPointOnCurveCmd.cpp, dagMessageCmd.cpp, findFileTexturesCmd.cpp, pointOnMeshCmd.cpp, polyModifierCmd.cpp, polyPrimitiveCmd.cpp, and whatisCmd.cpp.

MString MFnDependencyNode::pluginName ( MStatus *  ReturnStatus = NULL  )  const

Returns the name of the plug-in this MFnDependendencyNode was defined in. The name returned is the name of the plug-in on disk, and may contain pathname separators (such as `/') and drive letters (e.g. C:). If this object is not an MFnDependency node, then MS::kFailure is returned instead.

Parameters:
[out] ReturnStatus return status
Returns:
The name of the plug-in
Status Codes:

MString MFnDependencyNode::setName ( const MString &  name,
MStatus *  ReturnStatus = NULL 
)

Sets the name of this node.

If the new name conflicts with the name of an existing node then the object will be given a unique name based on the supplied name. If the new name ends in a single '#' it will be replaced with a number that ensures the new name is unique.

When a transform is renamed, any shape nodes beneath the transform that have the same prefix as the old transform name are also renamed. For example, "rename nurbsSphere1 ball" would rename "nurbsSphere1|nurbsSphereShape1" to "ball|ballShape".

The unique name set for the node is returned.

Note that if the object the instance of this class is attached to is data instead of being in the graph (ie. the object was created by one of the MFn*Data function sets, or was passed to an MPxNode::compute function in a data block) then the setName method will not work.

Parameters:
[in] name the new name for the node
[out] ReturnStatus return status
Returns:
The new name of the node.
Status Codes:

MStatus MFnDependencyNode::getConnections ( MPlugArray &  array  )  const

Get all of the current connections to this node as an array of plugs.

Parameters:
[out] array storage for the array of plugs
Returns:
Status code
Status Codes:

unsigned int MFnDependencyNode::attributeCount ( MStatus *  ReturnStatus = NULL  )  const

Returns the number of attributes that this node has.

Parameters:
[out] ReturnStatus return status
Returns:
The attribute count
Status Codes:

MObject MFnDependencyNode::attribute ( unsigned int  index,
MStatus *  ReturnStatus = NULL 
) const

Finds the attribute of this node at the given index. Index order is based on the order in which the attributes were added to the node.

Parameters:
[in] index the index of the attribute
[out] ReturnStatus return status
Returns:
A pointer to the attribute
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure function set does not have a valid object, or the index is out of range
Examples:
cgfxAttrDef.cpp, findFileTexturesCmd.cpp, GLSLShaderNode.cpp, latticeNoiseCmd.cpp, and polyModifierCmd.cpp.

MObject MFnDependencyNode::reorderedAttribute ( unsigned int  index,
MStatus *  ReturnStatus = NULL 
) const

Some nodes, such as the various animCurve nodes, require that their attributes be set in a specific order for proper operation. Usually this ordering is only important when the node is being created during file I/O.

The attribute(index) method above returns the attributes according to the order in which they were originally added to the node.

This method returns the attributes according to the reordering, if any, which is required by the node.

Parameters:
[in] index the reordered index of the attribute
[out] ReturnStatus return status
Returns:
A pointer to the attribute
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure function set does not have a valid object, or the index is out of range

MObject MFnDependencyNode::attribute ( const MString &  attrName,
MStatus *  ReturnStatus = NULL 
) const

Finds the attribute of this node that has the given name.

Parameters:
[in] attrName name of the attribute to find
[out] ReturnStatus return status
Returns:
A pointer to the attribute
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure function set does not have a valid object, or the given attribute was not found

MFnDependencyNode::MAttrClass MFnDependencyNode::attributeClass ( const MObject &  attribute,
MStatus *  ReturnStatus = NULL 
) const

Returns the class (normal, local dynamic, global dynamic) of the specified attribute.

Parameters:
[in] attribute the attribute to check
[out] ReturnStatus return status
Returns:
The class of the attribute. If the node does not have the specified attribute, then kInvalidAttr is returned as the class.
Status Codes:

MStatus MFnDependencyNode::getAffectedAttributes ( const MObject &  attr,
MObjectArray &  affectedAttributes 
) const

Returns an array of attributes that are affected by the attribute passed in. That is, when the given attribute, attr is marked dirty (changed) all the affectedAttributes attributes will also be marked dirty. For nodes defined in plug-ins this call returns all those attributes that were marked as being affected by the given one via the MPxNode::attributeAffects call.

It should be noted that dynamic attributes cannot be handled by this method. This is because the attribute affects dependencies are statically defined when the node is created. An alternate approach which works for dynamic as well as non-dynamic attributes is available through MPxNode::setDependentsDirty override.

Parameters:
[in] attr the attribute to check
[out] affectedAttributes an array of attributes affected by attr
Returns:
Status code
Status Codes:

MStatus MFnDependencyNode::getAffectedByAttributes ( const MObject &  attr,
MObjectArray &  affectedByAttributes 
) const

Returns an array of attributes that affect the attribute passed in, attr. That is, when one of the attributes in affectedByAttributes is marked dirty (changed) then attr will also be marked dirty. For nodes defined in plug-ins this call returns all those attributes that were marked as affecting the given one via the MPxNode::attributeAffects call.

It should be noted that dynamic attributes cannot be handled by this method. This is because the attribute affects dependencies are statically defined when the node is created. An alternate approach which works for dynamic as well as non-dynamic attributes is available through MPxNode::setDependentsDirty override.

Parameters:
[in] attr the attribute to check
[out] affectedByAttributes an array of attributes affected by attr
Returns:
Status code
Status Codes:

MPlug MFnDependencyNode::findPlug ( const MObject &  attr,
bool  wantNetworkedPlug,
MStatus *  ReturnStatus = NULL 
) const

Attempt to find a plug for the given attribute. This method will first try to find the networked version of the plug if requested. The networked version of a plug is one that currently exists in the dependency graph at a particular connection point. If a networked version is not found, then a standard non-networked plug is returned.

A non-networked plug is not actually used by the dependency graph, but is used to represent the same connections. Every time an operation is performed on a non-networked plug, a search is made for the networked version of the plug.

Networked and non-networked plugs behave the same, but networked plugs are much more efficient if used for multiple operations.

Networked plugs should be avoided if you will be deleting connections to the plug.

Parameters:
[in] attr attribute whose plug we wish to find
[in] wantNetworkedPlug if true, request a networked plug if it is available
[out] ReturnStatus return status
Returns:
The plug
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure function set does not have a valid object, or the plug could not be found
Examples:
cgfxShaderCmd.cpp, closestPointCmd.cpp, closestPointOnCurveCmd.cpp, findTexturesPerPolygonCmd.cpp, intersectCmd.cpp, pointOnMeshCmd.cpp, polyExporter.cpp, polyModifierCmd.cpp, surfaceBumpManip.cpp, and swissArmyManip.cpp.

MPlug MFnDependencyNode::findPlug ( const MString &  attrName,
bool  wantNetworkedPlug,
MStatus *  ReturnStatus = NULL 
) const

Attempt to find a plug for the given attribute. This method will first try to find the networked version of the plug if requested. The networked version of a plug is one that currently exists in the dependency graph at a particular connection point. If a networked version is not found, then a standard non-networked plug is returned.

A non-networked plug is not actually used by the dependency graph, but is used to represent the same connections. Every time an operation is performed on a non-networked plug, a search is made for the networked version of the plug.

Networked and non-networked plugs behave the same, but networked plugs are much more efficient if used for multiple operations.

Networked plugs should be avoided if you will be deleting connections to the plug.

Parameters:
[in] attrName name of attribute whose plug we wish to find
[in] wantNetworkedPlug if true, request a networked plug if it is available
[out] ReturnStatus return status
Returns:
The plug
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure function set does not have a valid object, or the plug could not be found

MPlug MFnDependencyNode::findPlug ( const MObject &  attr,
MStatus *  ReturnStatus = NULL 
) const

This method is obsolete.

Deprecated:
Use the MFnDependencyNode::findPlug( MObject&, bool, MStatus* ) method instead.

MPlug MFnDependencyNode::findPlug ( const MString &  attrName,
MStatus *  ReturnStatus = NULL 
) const

This method is obsolete.

Deprecated:
Use the MFnDependencyNode::findPlug( MString&, bool, MStatus* ) method instead.

MStatus MFnDependencyNode::addAttribute ( const MObject &  attr,
MFnDependencyNode::MAttrClass  type = kLocalDynamicAttr 
)

Add a new attibute to this node. Note that this operation will fail if the given type parameter is not MFnDependencyNode::kLocalDynamicAttr.

Parameters:
[in] attr new attribute
[in] type class of attribute to add
Returns:
Status code
Status Codes:
  • MS::kSuccess operation successful
  • MS::kInvalidParameter attr is not a valid attribute object, or type did not specify a local dynamic attribute type.
  • MS::kFailure function set does not have a valid object, or the addition of the new attribute failed

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

Remove an attribute from a node.

Note: After a successful call to this method, the MObject passed to it 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] attribute attribute to remove
[in] type class of attribute to remove (must be either MFnDependencyNode::kLocalDynamicAttr or MFnDependencyNode::kGlobalDynamicAttr)
Returns:
Status code
Status Codes:
  • MS::kSuccess operation successful
  • MS::kInvalidParameter attr is not a valid attribute object, or type did not specify a dynamic attribute type.
  • MS::kFailure function set does not have a valid object, or the removal of the attribute failed

MPxNode * MFnDependencyNode::userNode ( MStatus *  ReturnStatus = NULL  )  const

If the function set's node is a plug-in node, then this method will extract the MPxNode pointer from it. This method should only be used on node types that are provided by the plug-in calling this method.

Parameters:
[out] ReturnStatus return status
Returns:
A pointer to the user data (NULL if not a plug-in node)
Status Codes:
  • MS::kSuccess operation successful
  • MS::kFailure function set does not have a valid object, or the removal of the attribute failed
Examples:
cgfxShaderCmd.cpp.

bool MFnDependencyNode::isFromReferencedFile ( MStatus *  ReturnStatus = NULL  )  const

Indicates whether or not this node came from a referenced file. If it did, the node will be marked as read-only in the scene and changes to the node's attributes will be saved in the main scene file, not the referenced from from which the node came.

Parameters:
[out] ReturnStatus return status
Returns:
Boolean value: true if the node came from a referenced file, false otherwise.
Status Codes:

bool MFnDependencyNode::isShared ( MStatus *  ReturnStatus = NULL  )  const

Indicates whether or not this node is shared. This comes into play when you attempt to create a new node with the same name as an existing node. If the existing node is shared, then no new node will be created. If the existing node is not shared, then the new node will be created and given a different name.

For example, if you import several scene files into a single scene, they may all attempt to create their own 'defaultResolution' node. However, since this node is shared, only one such node will be created and the other requests will be ignored.

The concept of "sharing" can also be found in the "createNode -shared" flag found in MEL which, if specified causes an implicit node to be created (or not created, if it is already present).

Parameters:
[out] ReturnStatus return status
Returns:
Boolean value: true if the node is shared, false otherwise.
Status Codes:

bool MFnDependencyNode::hasUniqueName ( MStatus *  ReturnStatus = NULL  )  const

Indicates whether or not this node's name is unique within the scene.

Parameters:
[out] ReturnStatus return status
Returns:
Boolean value:
  • true if the node's name is unique within scene, false otherwise.
Status Codes:

MString MFnDependencyNode::parentNamespace ( MStatus *  ReturnStatus = NULL  )  const

Returns the name of the namespace in which this node resides. Namespaces are often used when importing files to prevent name collisions.

Parameters:
[out] ReturnStatus return status
Returns:
The name of the namespace in which this node exists. This will be a colon separated path. If the object is in the root namespace, then an empty string will be returned.
Status Codes:

bool MFnDependencyNode::isLocked ( MStatus *  ReturnStatus = NULL  )  const

Indicates whether or not this node is locked. See the setLocked method for more information on what it means for a node to be locked.

Parameters:
[out] ReturnStatus return status
Returns:
Boolean value:
  • true if the node is locked, false otherwise.
Status Codes:

MStatus MFnDependencyNode::setLocked ( bool  lock  ) 

Locks or unlocks this node.

If a node is locked, it may not be deleted, renamed, or reparented; it may not have attributes added or removed; attributes which are unlocked may not be locked and those which are already locked may not be unlocked.

Parameters:
[in] lock If true then node will be locked.
Returns:
Status code
Status Codes:

MString MFnDependencyNode::classification ( const MString &  nodeTypeName  )  [static]

Retrieves the classification string for a node type. This is a string that is used in dependency nodes that are also shaders to provide more detailed type information to the rendering system. See the documentation for the MEL commands getClassification and listNodeTypes for information on the strings that can be provided.

User-defined nodes set this value through a parameter to MFnPlugin::registerNode.

Parameters:
[in] nodeTypeName The name of the node for which a classification should be retrieved. Since this is a static method, the typeName method of this class can be used for this parameter if it is desired to get the classification for the attached node.
Returns:
The classification string. If the node does not have an associated classification, an empty string will be returned.

bool MFnDependencyNode::isNewAttribute ( const MObject &  attr,
MStatus *  ReturnStatus = NULL 
) const

Indicates whether or not the specified attribute was added to this node within the current scene.

For nodes from referenced files, this method will only return true if the attribute was added to the node after the reference file was loaded into the scene.

For all other nodes, this method will return true if the attribute is dynamic (i.e. not one of the node's original, permanent attributes).

Parameters:
[out] ReturnStatus return status
Returns:
  • true the attribute was added within the current scene
  • false the attribute is permanent or was added within a referenced file.
Status Codes:

unsigned int MFnDependencyNode::allocateFlag ( const MString  pluginName,
MStatus *  ReturnStatus = NULL 
) [static]

Allocates a node flag for sole use by the caller. Note that the flag is not specific to any one node but is made available to the caller on all nodes. Furthermore, node flags only persist for the duration of the current Maya session: they are not saved with the scene.

deallocateFlag must be called when a flag is no longer needed.

There are a total of just 8 flags available, so plugins should strive not to hold onto flags for extended periods of time as that might interfere with the needs of other plugins.

When a plugin is unloaded, deallocateAllFlags is automatically invoked to free up any node flags still held by the plugin.

Parameters:
[in] pluginName The name of the plugin which is allocating the flag. A plugin's name can be retrieved by calling MFnPlugin::name() within its initializePlugin() or uninitializePlugin() functions.
[out] ReturnStatus Return status.
Returns:
The newly-allocated flag.
Status Codes:
Examples:
maTranslator.cpp.

MStatus MFnDependencyNode::deallocateFlag ( const MString  pluginName,
unsigned int  flag 
) [static]

Deallocates a node flag which was previously allocated by a call to allocateFlag. The flag subsequently becomes available for reallocation and use by someone else.

Parameters:
[in] pluginName The name of the plugin which allocated the flag. A plugin's name can be retrieved by calling MFnPlugin::name() within its initializePlugin() or uninitializePlugin() functions.
[in] flag Flag to deallocate.
Returns:
Status code.
Status Codes:
Examples:
maTranslator.cpp.

MStatus MFnDependencyNode::deallocateAllFlags ( const MString  pluginName  )  [static]

Deallocates all of the node flags which are currently allocated to the specified plugin. The deallocated flags immediately become available for use by any plugin.

Parameters:
[in] pluginName The name of the plugin whose flags are to be deallocated. A plugin's name can be retrieved by calling MFnPlugin::name() within its initializePlugin() or uninitializePlugin() functions.
Returns:
Status code.
Status Codes:
  • MS::kSuccess Operation successful.
  • MS::kInvalidParemeter The pluginName was invalid.

MStatus MFnDependencyNode::setFlag ( unsigned int  flag,
bool  state 
)

Sets the state of the specified flag for the node.

The flag number must have been previously obtained through a call to allocateFlag.

Parameters:
[in] flag flag to set
[in] state new state to which the flag will be set
Returns:
Status code.
Status Codes:

bool MFnDependencyNode::isFlagSet ( unsigned int  flag,
MStatus *  ReturnStatus = NULL 
) const

Retrieves the current state of the specified flag for a node.

The flag must have been previously obtained through a call to allocateFlag.

Parameters:
[in] flag number of the flag to retrieve.
[out] ReturnStatus return status
Returns:
Current state of the flag
Status Codes:

bool MFnDependencyNode::isDefaultNode ( MStatus *  ReturnStatus = NULL  )  const

Returns true if the node is a default node.

A default node is one that Maya creates automatically and does not get saved out with the scene, although some of its attribute values may.

Parameters:
[out] ReturnStatus return status
Returns:
Boolean value: true if the node is default, false otherwise.
Status Codes:

MStatus MFnDependencyNode::setDoNotWrite ( bool  flag  ) 

Use this method to mark the "do not write" state of this node. If set, this node will not be saved when the Maya model is written out.

NOTES: 1. If this node is a DAG and has a parent or children, the "do not write" flag of the parent or children will not be set. It is the developer's responsibility to ensure that the resulting scene file is capable of being read in without errors due to unwritten nodes.

Parameters:
[in] flag True if the node should not be saved.

bool MFnDependencyNode::canBeWritten ( MStatus *  ReturnStatus = NULL  )  const

Returns true if the node can be written/exported to scene files.

Note that if a node is marked as being shared (see MFnDependencyNode::isShared) that overrides being marked as not writable. So shared nodes can be written, even if not marked as writable.

Parameters:
[out] ReturnStatus return status
Returns:
Boolean value: true if the node can be written, false otherwise.
Status Codes:

bool MFnDependencyNode::hasAttribute ( const MString &  attrName,
MStatus *  ReturnStatus = NULL 
) const

Returns true if the node already has an attribute with the given name.

Parameters:
[out] ReturnStatus return status
Returns:
Boolean value: true if the node has attribute, false otherwise.
Status Codes:
Examples:
GLSLShaderNode.cpp.

MObject MFnDependencyNode::getAliasAttr ( bool  force,
MStatus *  ReturnStatus = NULL 
)

The function returns the alias attribute list; returns NULL if it doesn't exist. If the value of argument 'force' is true, an alias attribute is created if one doesn't exist.

Parameters:
[in] force To indicate whether the alias attr should be created.
[out] ReturnStatus return status
Returns:
The MObject corresponding to the alias attribute.
Status Codes:

bool MFnDependencyNode::setAlias ( const MString &  alias,
const MString &  name,
const MPlug &  plug,
bool  add = true,
MStatus *  ReturnStatus = NULL 
)

The function sets the alias attribute.

Parameters:
[in] alias name of the alias.
[in] name name of the attribute for which we need an alias.
[in] plug plug to the attribute for which we need an alias.
[in] add boolean; a value of false indicates that the alias name has to be removed from the alias attribute list. Default value is true.
[out] ReturnStatus return status
Returns:
Boolean indicating if the alias has been set properly.
Status Codes:

bool MFnDependencyNode::findAlias ( const MString &  alias,
MObject &  attrObj,
MStatus *  ReturnStatus = NULL 
) const

The function looks for an aliased attribute on this node with the given name

Parameters:
[in] alias name of the alias attribute.
[in] attrObj MObject of the alias attribute.
[out] ReturnStatus return status
Returns:
Boolean indicating if the alias was found.
Status Codes:

bool MFnDependencyNode::getAliasList ( MStringArray &  strArray,
MStatus *  ReturnStatus = NULL 
)

The function sets a pointer to the list of all attribute aliases for this node.

Parameters:
[in] strArray Pointer to MStringArray, which will be filled.
[out] ReturnStatus return status
Returns:
Boolean value: true if any alias was found.
Status Codes:

MString MFnDependencyNode::plugsAlias ( const MPlug &  plug,
MStatus *  ReturnStatus = NULL 
)

The function returns the name of the alias on whose attribute the given plug is created.

Parameters:
[in] plug the plug on the attribute.
[out] ReturnStatus return status. See below.
Returns:
Name of the alias attribute.
Status Codes:

bool MFnDependencyNode::getPlugsAlias ( const MPlug &  plug,
MString &  aliasName,
MStatus *  ReturnStatus = NULL 
)

NO SCRIPT SUPPORT.

The function returns the name of the alias on whose attribute the given plug is created.

Python Notes

This method is not supported in Python. Please see plugsAlias()

Parameters:
[in] plug the plug on the attribute.
[in] aliasName Name of the alias attribute.
[out] ReturnStatus return status
Returns:
Boolean indicating if the alias was found.
Status Codes:

MStatus MFnDependencyNode::dgTimerOn (  ) 

The function starts the timing for this node. Note that this does not reset the timers and counters on the node, it merely activates the timing mechanism within Maya and subsequent timing values are added to the current timer and counter values. If you also want the counters to be reset, use the method dgTimerReset().

For the inquisitive: yes, it is OK to turn on timing when its already on, and turn it off when its already off, so you don't have to call dgTimerQueryState() on each node in order to change its state.

Returns:
Status code
Status Codes:

MStatus MFnDependencyNode::dgTimerOff (  ) 

The function stops the timing of dependency graph evaluation for this node

Returns:
Status code
Status Codes:

MFnDependencyNode::MdgTimerState MFnDependencyNode::dgTimerQueryState ( MStatus *  ReturnStatus = NULL  ) 

The function returns the current on/off state of the node's timer.

Parameters:
[out] ReturnStatus return status.
Returns:
The node's timer's current on/off state.
Status Codes:

MStatus MFnDependencyNode::dgTimerReset (  ) 

The function resets the dependency graph timers and counters for this node to zero. Note that this method does not start or stop timing, it only resets the values to zero. If you want to turn on timing, use the method dgTimerOn(). If you want to turn off timing, use dgTimerOff().

Returns:
Status code
Status Codes:

double MFnDependencyNode::dgTimer ( const MdgTimerMetric  timerMetric,
const MdgTimerType  timerType,
MStatus *  ReturnStatus = NULL 
) const

The function returns the specified timer value for the current node. This is the total amount of time spent performing the requested operation since the timer was last reset (see dgTimerReset() for details). There are numerous timers per node and these are referenced by the metric and the timer type.

Parameters:
[in] timerMetric The timing metric we wish to query.
[in] timerType The timer type we wish to query.
[out] ReturnStatus return status
Returns:
Value of the timer in seconds for types of kTimerType_self and kTimerType_inclusive, and as a simple count for kTimerType_count.
Status Codes:

MStatus MFnDependencyNode::dgCallbacks ( const MdgTimerType  timerType,
MStringArray &  callbackName,
MDoubleArray &  value 
)

Node callbacks that occur when timing is enabled get logged with the node and can be queried via this method. See the dgCallbackIds method for getting a further breakdown of the time for an individual callback on this node.

There are several important items of note:

  • 1 Due to the large number of node types which exist within Maya, the "internal name" is used instead of the API name. For example, a message the user declares to be of type MDagMessage::kParentRemoved will report as "parentRemovedMsg". In general it should be obvious as to the meaning of the callback name.
  • 2 Timing is reported by callback type and is not further broken down by the individual callback methods that are registered against that callback type. Therefore if you note a high-cost callback type, the majority of cost may not be expended in your callback method but rather in other registered callbacks on that type.
  • 3 Not all callback types inside Maya that deal with nodes are currently tracked using the node callback timing mechanism. Only the most frequently encountered message types are currently recorded.
The result of calling this method is an array of names and an array of values. There is a one-to-one correspondence between the two arrays.

Parameters:
[in] timerType The timer we want to query, e.g. kTimerType_self for self time.
[in] callbackName Returns an array of callback names that were invoked for this node since the last timer reset.
[in] value Returns an array of timing values. There is a one-to-one correspondence with the `callbackName' array.
Returns:
Status code
Status Codes:

MStatus MFnDependencyNode::dgCallbackIds ( const MdgTimerType  timerType,
const MString &  callbackName,
MCallbackIdArray &  callbackId,
MDoubleArray &  value 
)

This method provides a further breakdown of the per-callback time returned via dgCallbacks() by returning the data on a per-callbackId basis. We define a "callback" to be an event withing Maya that "callback methods" can be registered with to be invoked when the given event occurs. The registered client information is called a "callbackId". There can be multiple callbackIds registered with a given callback, and a callbackId can be shared amongst multiple nodes or multiple callbacks.

An example of a callback is "attributeChangedMsg", which the user can register callback methods against via MNodeMessage::addAttributeChangedCallback(). The process of registering a callback method returns a callbackId, thus there can be multiple callbacksIds per callback.

The general approach when querying callbackIds is as follows:

  • 1 Query the callbacks associated with a given node using MFnDependencyNode::dgCallbacks(). This returns the list of callbacks by name.
  • 2 Use this method to query the callbackIds for a given callback on the given node.
The result of calling this method is an array of names and an array of values. There is a one-to-one correspondence between the two arrays.

Parameters:
[in] timerType The timer we want to query, e.g. kTimerType_self for self time.
[in] callbackName Name of the callback to query the callbackIds for. This should be one of the callback names that was returned from MFnDependencyNode::dgCallbacks().
[in] callbackId Returns an array of callbackIds which were invoked for this node and `callbackName' since the last timer reset. There is a one-to-one correspondence with the `value' array. The entries in the list can include callbackIds that are no longer active (e.g. if you unregistered the callbackId), so be careful not to treat these as active callbackIds -- they are for informational purposes only.
[in] value Returns an array of timing values. There is a one-to-one correspondence with the `name' array.
Returns:
Status code
Status Codes:

Autodesk® Maya® 2009 © 1997-2008 Autodesk, Inc. All rights reserved. Generated with doxygen 1.5.6