Public Types | Public Member Functions | Static Public Member Functions

MItDag Class Reference

This reference page is linked to from the following overview topics: Querying the Scene Graph, DAG walking example.


Search for all occurrences

Detailed Description

DAG Iterator.

Use the DAG iterator to traverse the DAG either depth first or breadth first, visiting each node and, if desired, retrieving the node (as an MObject). The DAG iterator provides a basic filtering capability, so that DAG node retrieval can be limited to a specific type (MFn::Type) of node. With filtering enabled the iterator checks to see if the node is compatible with the type of Function Set specified by the filter. See MFn::Type for a list of all valid Function set types.

Since each object, if retrieved, is returned as an MObject, the MObject::hasFn() method can be used to further check for compatible function set types since an MObjects may be compatible with more than one function set).

Any compatible Function Set can be attached to the retrieved object to query or or edit it. Often you will want to use the DAG node Function Set (MFnDagNode), which is compatible with all DAG objects, to perform basic queries on each node as the iterator traverses the DAG.

The iterator also provides the capability to reset the root of the iteration, the type of traversal, and the filter.

Additionally, the iterator can be queried for the root, mode and type of traversal, and to determine if the the traversal has been completed.

Examples:

animExportUtil.cpp, animInfoCmd.cpp, D3DResourceManager.cpp, D3DViewportRenderer.cpp, lepTranslator.cpp, maTranslator.cpp, narrowPolyViewerCmd.cpp, objExport.cpp, OpenGLViewportRenderer.cpp, polyExporter.cpp, scanDagCmd.cpp, and scanDagSyntax.cpp.

#include <MItDag.h>

List of all members.

Public Types

enum  TraversalType { kInvalidType = 0, kDepthFirst, kBreadthFirst }
 

Order in which nodes should be traversed.

More...

Public Member Functions

 MItDag (TraversalType=kDepthFirst, MFn::Type=MFn::kInvalid, MStatus *ReturnStatus=NULL)
 Class Constructor.
 MItDag (MIteratorType &dagInfoObject, TraversalType=kDepthFirst, MStatus *ReturnStatus=NULL)
 Class Constructor.
MStatus reset ()
 Resets the iterator.
MStatus reset (const MObject &object, TraversalType=kDepthFirst, MFn::Type=MFn::kInvalid)
 Resets root, type and filter of the iterator.
MStatus reset (const MDagPath &path, TraversalType=kDepthFirst, MFn::Type=MFn::kInvalid)
 Resets root, type and filter of the iterator.
MStatus reset (MIteratorType &dagInfoObject, const MObject *object, const MDagPath *path, TraversalType=kDepthFirst)
 Resets root, type and filter list of the iterator.
MObject item (MStatus *ReturnStatus=NULL)
 This method is obsolete.
MObject currentItem (MStatus *ReturnStatus=NULL)
 Retrieves DAG node to which the iterator points.
MStatus next ()
 Moves to the next node matching the filter in the graph.
MStatus prune ()
 Prunes iteration tree at current node.
bool isDone (MStatus *ReturnStatus=NULL) const
 Indicates end of iteration path.
MObject root (MStatus *ReturnStatus=NULL)
 Returns the root (start node) of the current traversal.
unsigned int depth (MStatus *ReturnStatus=NULL) const
 Returns the height or depth of the current node in the DAG relative to the root node.
TraversalType getType (MStatus *ReturnStatus=NULL) const
 Returns the direction of the traversal.
MStatus getPath (MDagPath &path) const
 Determines a DAG Path to the current item in the iteration.
MStatus getAllPaths (MDagPathArray &paths) const
 Determines all DAG Paths to current item in the iteration.
MString fullPathName (MStatus *ReturnStatus=NULL) const
 Return a string representing the full path from the root of the dag to this object.
MString partialPathName (MStatus *ReturnStatus=NULL) const
 Return a string representing the partial path from the root of the dag to this object.
bool isInstanced (bool indirect=true, MStatus *ReturnStatus=NULL) const
 Determines whether the current item (DAG node) in the iteration is directly or indirectly instanced.
unsigned int instanceCount (bool total, MStatus *ReturnStatus=NULL) const
 Determines the number of times the current item (DAG node) in the iteration is instanced.
MStatus traverseUnderWorld (bool flag)
 Specifies whether underworld traversal is turned on.
bool willTraverseUnderWorld (MStatus *ReturnStatus=NULL) const
 Returns true if this iterator will traverse into underworld items.
virtual ~MItDag ()
 Class Destructor.

Static Public Member Functions

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

Member Enumeration Documentation

Order in which nodes should be traversed.

Enumerator:
kInvalidType 

 

kDepthFirst 

Visit a node's children before moving on to its siblings.

kBreadthFirst 

Visit a node's siblings before moving on to its children.


Constructor & Destructor Documentation

MItDag ( MItDag::TraversalType  type = kDepthFirst,
MFn::Type  filter = MFn::kInvalid,
MStatus ReturnStatus = NULL 
)

Class Constructor.

Initializes the root of iteration at the world node, sets the type of the traversal, and the filter. Sets a return status parameter to indicate success or failure.

Parameters:
[in]typeEnumerated type that determines the direction of the traversal
  • kDepthFirst - Traverse vertically first
  • kBreadthFirst - Traverse horizontally first
Parameters:
[in]filterFunction set type (MFn::Type)
  • kInvalid - Filtering disabled
  • See MFn::Type for other values
Parameters:
[out]ReturnStatusStatus Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvlaidParameter Invalid parameter passed for mode or type
  • MS::kFailure Failure creating iterator
MItDag ( MIteratorType dagInfoObject,
MItDag::TraversalType  type = kDepthFirst,
MStatus ReturnStatus = NULL 
)

Class Constructor.

Initializes the root of iteration at the world node, sets the type of the traversal, and the filter list. Sets a return status parameter to indicate success or failure.

Parameters:
[in]typeEnumerated type that determines the direction of the traversal
  • kDepthFirst - Traverse vertically first
  • kBreadthFirst - Traverse horizontally first
Parameters:
[in]dagInfoObjectObject which has details of type_filter or filter list.
[out]ReturnStatusStatus Code (see below)
Status Codes:
  • MS::kSuccess Success
  • MS::kInvlaidParameter Invalid parameter passed for mode or type
  • MS::kFailure Failure creating iterator
~MItDag ( ) [virtual]

Class Destructor.

Deletes iterator.


Member Function Documentation

MStatus reset ( )

Resets the iterator.

The iterator is reset to the previous traversal setting.

Returns:
Status code
Status Codes:
MStatus reset ( const MObject object,
MItDag::TraversalType  type = kDepthFirst,
MFn::Type  filter = MFn::kInvalid 
)

Resets root, type and filter of the iterator.

Parameters:
[in]objectRoot node to begin traversal
[in]typeEnumerated type that determines the direction of the traversal
  • kDepthFirst - Traverse vertically first
  • kBreadthFirst - Traverse horizontally first
Parameters:
[in]filterFunction set type (MFn::Type)
  • kInvalid - Filtering disabled
  • See MFn::Type for other values
Returns:
Status code
Status Codes:
MStatus reset ( const MDagPath path,
MItDag::TraversalType  type = kDepthFirst,
MFn::Type  filter = MFn::kInvalid 
)

Resets root, type and filter of the iterator.

This method is usefull when a node is instanced and a DAG path is necessary to specify which instance should be the root of the traversal.

Parameters:
[in]pathPath to begin traversal
[in]typeEnumerated type that determines the direction of the traversal
  • kInvalid - Invalid parameter. Not used.
  • kDepthFirst - Traverse vertically first
Parameters:
[in]filterFunction set type (MFn::Type)
  • kInvalid - Filtering disabled
  • See MFn::Type for other values
Returns:
Status code
Status Codes:
  • MS::kSuccess Success
  • MS::kInvlaidParameter Invalid parameter passed for object, mode or type
  • MS::kFailure Failure resetting iterator
MStatus reset ( MIteratorType dagInfoObject,
const MObject object,
const MDagPath path,
MItDag::TraversalType  type = kDepthFirst 
)

Resets root, type and filter list of the iterator.

This method is usefull when a node is instanced and a DAG path is necessary to specify which instance should be the root of the traversal.

Parameters:
[in]dagInfoObjectIterator object having info on filter or filterlist.
[in]objectMObject, to which the iterator will be reset to. This may be NULL if we are setting the iterator root to dagpath object.
[in]pathMDagPath object, to which the iterator will be reset to. This may be NULL if we are setting the iterator root to MObject.
[in]typeEnumerated type that determines the direction of the traversal
  • kInvalid - Invalid parameter. Not used.
  • kDepthFirst - Traverse vertically first
Returns:
Status code
Status Codes:
  • MS::kSuccess Success
  • MS::kInvlaidParameter Invalid parameter passed for object, mode or type
  • MS::kFailure Failure resetting iterator
MObject item ( MStatus ReturnStatus = NULL)

This method is obsolete.

Deprecated:
Use the MItDag::currentItem method instead.

Retrieves DAG node to which the iterator points.

Parameters:
[out]ReturnStatusStatus Code (see below).
Returns:
Pointer to the DAG node. Null pointer indicates failure.
Status Codes:
Examples:
maTranslator.cpp.
MObject currentItem ( MStatus ReturnStatus = NULL)

Retrieves DAG node to which the iterator points.

Parameters:
[out]ReturnStatusStatus Code (see below).
Returns:
Pointer to the DAG node. Null pointer indicates failure.
Status Codes:
MStatus next ( )

Moves to the next node matching the filter in the graph.

Returns:
Status code
Status Codes:
Examples:
maTranslator.cpp.
MStatus prune ( )

Prunes iteration tree at current node.

Returns:
Status code
Status Codes:
Examples:
maTranslator.cpp.
bool isDone ( MStatus ReturnStatus = NULL) const

Indicates end of iteration path.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
Boolean value: true when done, false otherwise.
Status Codes:
Examples:
maTranslator.cpp.
MObject root ( MStatus ReturnStatus = NULL)

Returns the root (start node) of the current traversal.

The constructor sets the root of traversal to the world node. The root can be changed by the reset() method.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
Root of the traversal
Status Codes:
unsigned int depth ( MStatus ReturnStatus = NULL) const

Returns the height or depth of the current node in the DAG relative to the root node.

The root node has a depth of zero.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
Depth of the current node
Status Codes:
MItDag::TraversalType getType ( MStatus ReturnStatus = NULL) const

Returns the direction of the traversal.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
  • kDepthFirst Recursively visits grandchildren of each child node
  • kBreadthFirst Recursively visits each child/parent node before any grandchild/grandparent nodes
Status Codes:
MStatus getPath ( MDagPath path) const

Determines a DAG Path to the current item in the iteration.

Parameters:
[out]pathThe DAG Path that is found (implicit return)
Returns:
Status Code
Status Codes:
Examples:
maTranslator.cpp.
MStatus getAllPaths ( MDagPathArray paths) const

Determines all DAG Paths to current item in the iteration.

Parameters:
[out]pathsArray of all DAG Paths that are found (implicit return)
Returns:
Status Code
Status Codes:
MString fullPathName ( MStatus ReturnStatus = NULL) const

Return a string representing the full path from the root of the dag to this object.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
The full path name
Status Codes:
MString partialPathName ( MStatus ReturnStatus = NULL) const

Return a string representing the partial path from the root of the dag to this object.

The partial path is the minimum path that is still unique. This string may contain wildcards.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
The partial path name
Status Codes:
bool isInstanced ( bool  indirect = true,
MStatus ReturnStatus = NULL 
) const

Determines whether the current item (DAG node) in the iteration is directly or indirectly instanced.

If indirect instance flag is false, the result is true if and only if the Node itself is multiply instanced (node->parentCount > 1).

If the indirect flag is true, the result is true if and only if the Node itself is multiply instanced (node->parentCount > 1) or if the Node is not multipuly instanced, but it has a directly instanced parent (node->parentCount()=1 and parent->parentCount >1).

Parameters:
[in]indirectIndirect instance flag
[out]ReturnStatusStatus Code (see below)
Returns:
  • true = Node is instanced (directly or indirectly according to indirect instance flag)
  • false = Node is not instanced (directly or indirectly according to indirect instance flag)
Status Codes:
unsigned int instanceCount ( bool  total,
MStatus ReturnStatus = NULL 
) const

Determines the number of times the current item (DAG node) in the iteration is instanced.

If total is false the number of direct instances is returned, which is the same as the node's parent count.

If total is true the total number of instances is returned, including indirect instances resulting from instancing higher up the DAG hierarchy (i.e. one or more of the node's ancestors also has multiple instances).

Parameters:
[in]totalControls whether to include indirect instances in the count.
[out]ReturnStatusStatus Code (see below)
Returns:
Number of instances.
Status Codes:
MStatus traverseUnderWorld ( bool  flag)

Specifies whether underworld traversal is turned on.

The default is off.

The underworld for a shape is a sub dag that hangs off of the shape. For example, if you have a curve on surface for a shape then there will be an underworld or sub-dag for the curve on surface.

Parameters:
[in]flagturns on/off underworld traversal
Returns:
Status Code
Status Codes:
Examples:
maTranslator.cpp.
bool willTraverseUnderWorld ( MStatus ReturnStatus = NULL) const

Returns true if this iterator will traverse into underworld items.

The underworld for a shape is a sub dag that hangs off of the shape. For example, if you have a curve on surface for a shape then there will be an underworld or sub-dag for the curve on surface.

Parameters:
[out]ReturnStatusStatus Code (see below)
Returns:
Boolean: true if underworld traversal is on, false otherwise.
Status Codes:
const char * className ( ) [static]

Returns the name of this class.

Returns:
The name of this class.

MItDag MItDag MItDag MItDag MItDag MItDag MItDag MItDag MItDag MItDag
MItDag MItDag MItDag MItDag MItDag MItDag MItDag MItDag MItDag MItDag