MItDag Class Reference

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

enum TraversalType

Search for all occurrences

Order in which nodes should be traversed.

Enumerator:

kInvalidType	Search for all occurrences
kDepthFirst	Visit a node's children before moving on to its siblings. Search for all occurrences
kBreadthFirst	Visit a node's siblings before moving on to its children. Search for all occurrences

---

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]

type

Enumerated type that determines the direction of the traversal

• kDepthFirst - Traverse vertically first
• kBreadthFirst - Traverse horizontally first

Parameters:

[in]

filter

Function set type (MFn::Type)

• kInvalid - Filtering disabled
• See MFn::Type for other values

Parameters:

[out]

ReturnStatus

Status 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]

type

Enumerated type that determines the direction of the traversal

• kDepthFirst - Traverse vertically first
• kBreadthFirst - Traverse horizontally first

Parameters:

[in]	dagInfoObject	Object which has details of type_filter or filter list.
[out]	ReturnStatus	Status 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

(

)

Search for all occurrences

Resets the iterator.

The iterator is reset to the previous traversal setting.

Returns:

Status code

Status Codes:

• MS::kSuccess operation successful
• MS::kFailure operation failed

MStatus reset	(	const MObject &	object,
		MItDag::TraversalType	type = kDepthFirst,
		MFn::Type	filter = MFn::kInvalid
	)

Search for all occurrences

Resets root, type and filter of the iterator.

Parameters:

[in]	object	Root node to begin traversal
[in]	type	Enumerated type that determines the direction of the traversal

• kDepthFirst - Traverse vertically first
• kBreadthFirst - Traverse horizontally first

Parameters:

[in]

filter

Function set type (MFn::Type)

• kInvalid - Filtering disabled
• See MFn::Type for other values

Returns:

Status code

Status Codes:

• MS::kSuccess Success
• MS::kInvalidParameter Invalid parameter passed for object, mode or type
• MS::kFailure Failure resetting iterator

MStatus reset	(	const MDagPath &	path,
		MItDag::TraversalType	type = kDepthFirst,
		MFn::Type	filter = MFn::kInvalid
	)

Search for all occurrences

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]	path	Path to begin traversal
[in]	type	Enumerated type that determines the direction of the traversal

• kInvalid - Invalid parameter. Not used.
• kDepthFirst - Traverse vertically first

Parameters:

[in]

filter

Function 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
	)

Search for all occurrences

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]	dagInfoObject	Iterator object having info on filter or filterlist.
[in]	object	MObject, to which the iterator will be reset to. This may be NULL if we are setting the iterator root to dagpath object.
[in]	path	MDagPath object, to which the iterator will be reset to. This may be NULL if we are setting the iterator root to MObject.
[in]	type	Enumerated 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

)

Search for all occurrences

This method is obsolete.

Deprecated:

Use the MItDag::currentItem method instead.

Retrieves DAG node to which the iterator points.

Parameters:

[out]

ReturnStatus

Status Code (see below).

Returns:

Pointer to the DAG node. Null pointer indicates failure.

Status Codes:

• MS::kSuccess Success
• MS::kInvalidParameter Null DAG object - end of iteration
• MS::kFailure Object error

Examples:

maTranslator.cpp.

MObject currentItem

(

MStatus *

ReturnStatus = NULL

)

Search for all occurrences

Retrieves DAG node to which the iterator points.

Parameters:

[out]

ReturnStatus

Status Code (see below).

Returns:

Pointer to the DAG node. Null pointer indicates failure.

Status Codes:

• MS::kSuccess Success
• MS::kInvalidParameter Null DAG object - end of iteration
• MS::kFailure Object error

MStatus next

(

)

Search for all occurrences

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

Returns:

Status code

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error

Examples:

maTranslator.cpp.

MStatus prune

(

)

Search for all occurrences

Prunes iteration tree at current node.

Returns:

Status code

Status Codes:

• MS::kSuccess Success
• MS::kFailure Could not access node

Examples:

maTranslator.cpp.

bool isDone

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Indicates end of iteration path.

Parameters:

[out]

ReturnStatus

Status Code (see below)

Returns:

Boolean value: true when done, false otherwise.

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error

Examples:

maTranslator.cpp.

MObject root

(

MStatus *

ReturnStatus = NULL

)

Search for all occurrences

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]

ReturnStatus

Status Code (see below)

Returns:

Root of the traversal

Status Codes:

• MS::kSuccess Success
• MS::kFailure Could not access node

unsigned int depth

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

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]

ReturnStatus

Status Code (see below)

Returns:

Depth of the current node

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error

MItDag::TraversalType getType

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

Returns the direction of the traversal.

Parameters:

[out]

ReturnStatus

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

• MS::kSuccess Success
• MS::kFailure Object error or internal error

MStatus getPath

(

MDagPath &

path

)

const

Search for all occurrences

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

Parameters:

[out]

path

The DAG Path that is found (implicit return)

Returns:

Status Code

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error or NULL DAG node

Examples:

maTranslator.cpp.

MStatus getAllPaths

(

MDagPathArray &

paths

)

const

Search for all occurrences

Determines all DAG Paths to current item in the iteration.

Parameters:

[out]

paths

Array of all DAG Paths that are found (implicit return)

Returns:

Status Code

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

MString fullPathName

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

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

Parameters:

[out]

ReturnStatus

Status Code (see below)

Returns:

The full path name

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

MString partialPathName

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

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]

ReturnStatus

Status Code (see below)

Returns:

The partial path name

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

bool isInstanced	(	bool	indirect = true,
		MStatus *	ReturnStatus = NULL
	)		const

Search for all occurrences

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]	indirect	Indirect instance flag
[out]	ReturnStatus	Status 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:

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

unsigned int instanceCount	(	bool	total,
		MStatus *	ReturnStatus = NULL
	)		const

Search for all occurrences

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]	total	Controls whether to include indirect instances in the count.
[out]	ReturnStatus	Status Code (see below)

Returns:

Number of instances.

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error or invalid DAG node

MStatus traverseUnderWorld

(

bool

flag

)

Search for all occurrences

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]

flag

turns on/off underworld traversal

Returns:

Status Code

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error

Examples:

maTranslator.cpp.

bool willTraverseUnderWorld

(

MStatus *

ReturnStatus = NULL

)

const

Search for all occurrences

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]

ReturnStatus

Status Code (see below)

Returns:

Boolean: true if underworld traversal is on, false otherwise.

Status Codes:

• MS::kSuccess Success
• MS::kFailure Object error

const char * className

(

)

[static]

Search for all occurrences

Returns the name of this class.

Returns:

The name of this class.