class MDagPath

Jump to documentation

public members:

	MDagPath ()
	MDagPath ( const MDagPath & src )
virtual	~MDagPath ()
static MStatus	getAllPathsTo ( const MObject & entity, MDagPathArray & pathArray )
static MStatus	getAPathTo ( const MObject & entity, MDagPath & path )
bool	hasFn ( MFn::Type type, MStatus * ReturnStatus = NULL ) const
MFn::Type	apiType ( MStatus * ReturnStatus = NULL) const
bool	isValid ( MStatus * ReturnStatus = NULL) const
MObject	node ( MStatus * ReturnStatus = NULL) const
MObject	transform ( MStatus * ReturnStatus = NULL ) const
unsigned int	length ( MStatus * ReturnStatus = NULL) const
MStatus	extendToShape ()
MStatus	extendToShapeDirectlyBelow ( unsigned int )
MStatus	numberOfShapesDirectlyBelow ( unsigned int& )
MStatus	push ( const MObject & child )
MStatus	pop ( unsigned int num = 1 )
unsigned int	childCount ( MStatus * ReturnStatus = NULL ) const
MObject	child ( unsigned int i, MStatus * ReturnStatus = NULL ) const
MMatrix	inclusiveMatrix ( MStatus * ReturnStatus = NULL) const
MMatrix	exclusiveMatrix ( MStatus * ReturnStatus = NULL) const
MMatrix	inclusiveMatrixInverse ( MStatus * ReturnStatus = NULL)const
MMatrix	exclusiveMatrixInverse ( MStatus * ReturnStatus = NULL)const
MDagPath &	operator = ( const MDagPath & src)
bool	operator == ( const MDagPath & src) const
MStatus	set ( const MDagPath & src)
unsigned int	pathCount ( MStatus * ReturnStatus = NULL) const
MStatus	getPath ( MDagPath & path, unsigned int i = 0 ) const
MString	fullPathName ( MStatus *ReturnStatus = NULL) const
MString	partialPathName ( MStatus *ReturnStatus = NULL) const
bool	isInstanced ( MStatus *ReturnStatus = NULL ) const
unsigned int	instanceNumber ( MStatus *ReturnStatus = NULL ) const
static MDagPath	getAPathTo ( const MObject & entity, MStatus * ReturnStatus = NULL ) OBSOLETE

Documentation

Provides methods for obtaining one or all Paths to a specified DAG Node, determining if a Path is valid and if two Paths are equivalent, obtaining the length, transform, and inclusive and exclusive matrices of a Path, as well as performing Path to Path assignment.

DAG Paths may be used as parameters to some methods in the DAG Node Function Set (MFnDagNode).

It is often useful to combine DAG Paths into DAG Path arrays (MDagPathArray).

Description

Use this DAG Path Class to obtain and query Paths to DAG Nodes. A DAG path is a path from the world node to a particular object in the DAG.

If a DAG object is instanced, then an MDagPath is required to identify a particular instance. DAG paths are also required when doing world space transformations.

Use this class in conjunction with the DAG Iterator (MItDag), DAG Node Function Set (MFnDagNode) and DAG Path Array class (MDagPathArray) to query and edit the DAG.

Functions

MDagPath:: MDagPath ()

Description

Class Constructor.

Creates a DAG Path

MDagPath:: MDagPath ( const MDagPath & src )

Description

Copy constructor. Duplicate the given path.

Arguments

• src the path to be copied

MDagPath:: ~MDagPath ()

Description

Class Destructor

No additional action.

MStatus MDagPath:: getAllPathsTo ( const MObject & object, MDagPathArray & pathArray )

Description

Determines all Paths to the specified DAG Node.

Arguments

• object DAG Node for which Paths are determined
• pathArray Array containing all DAG Paths to the specified Node (implicit return)

Return Value

• Status Code (see below)

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Invalid parameter passed for object - Node is not accessible, does not exist or is not a DAG Node
• MS::kFailure Unknown failure to determine Paths

MStatus MDagPath:: getAPathTo ( const MObject & object, MDagPath &path )

Description

Determines the Path to the specified DAG Node. The Path returned is rooted at the World. If the object is instanced and has multiple paths, then the first one that is found is returned.

Arguments

• object DAG Node for which Paths are determined
• path reference to the path of the specified DAG Node

Return Value

• Status Code (see below)

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter Invalid parameter passed for object - Node is not accessible, does not exist or is not a DAG Node
• MS::kFailure Unknown failure to determine Path

bool MDagPath:: hasFn ( MFn::Type type, MStatus *ReturnStatus ) const

Description

Returns true if the object at the end of this DAG path supports the given function set.

If the object at the end of this DAG path is a transform node and has a child that is a shape, then that node will be checked as well. All function sets that take an MDagPath

Arguments

• type function set type to check
• ReturnStatus status code

Return Value

• boolean value indicating whether the function set is supported

Status Codes

• MS::kSuccess Success
• MS::kFailure Invalid object

MFn::Type MDagPath:: apiType ( MStatus *ReturnStatus) const

Description

Returns the type of the object at the end of the path.

Arguments

• ReturnStatus status code

Return Value

• type of the object

Status Codes

• MS::kSuccess Success
• MS::kFailure Invalid object

bool MDagPath:: isValid ( MStatus *ReturnStatus) const

Description

Determines if Path is valid.

Arguments

• ReturnStatus status code

Return Value

• true = valid
• false = not valid

Status Codes

• MS::kSuccess Success
• MS::kFailure Invalid object

MObject MDagPath:: node ( MStatus * ReturnStatus) const

Description

Retrieves the DAG Node for this DAG Path.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• DAG Node for this DAG Path

Status Codes

• MS::kSuccess Success
• MS::kFailure Invalid object or no node

MObject MDagPath:: transform ( MStatus *ReturnStatus) const

Description

Retrieves the lowest Transform in the DAG Path.

Arguments

• ReturnStatus Status Code (see below)

Return Value

• Lowest Transform for this DAG Path

Status Codes

• MS::kSuccess Success
• MS::kInvalidParameter This object has no transform (i.e. this is the world node)
• MS::kFailure Invalid object

unsigned int MDagPath:: length ( MStatus *ReturnStatus) const

Description

Determines the number of DAG Nodes in the Path not including the root.

Arguments

• ReturnStatus status code

Return Value

• Number of DAG Nodes not including the root

Status Codes

• MS::kSuccess Success
• MS::kFailure Invalid object

MStatus MDagPath:: extendToShape ()

Description

If the object at the end of this path is a transform and there is a shape node directly beneath it in the hierarchy, then the path is extended to that geometry node.

NOTE: This method will fail if there multiple shapes below the transform.

Return Value

• status code

Status Codes

• MS::kSuccess operation successful
• MS::kInvalidParameter DAG path does not lead to a transform or there is no geometry below it
• MS::kFailure the object is invalid

MStatus MDagPath:: extendToShapeDirectlyBelow ( unsigned int index )

Description

This method is used if the end of the path is a transform and there are shapes directly below the transform. The shape to extend to is set by passing in an appropriate index parameter.

Use the numberOfShapesDirectlyBelow() method to determine how many shapes are below

Arguments

• index contains the index of the shape to extend the path to

Return Value

• status code

Status Codes

• MS::kSuccess operation successful
• MS::kInvalidParameter DAG path does not lead to a transform or there is no geometry below it
• MS::kFailure the object is invalid

MStatus MDagPath:: numberOfShapesDirectlyBelow ( unsigned int& num )

Description

If the object at the end of this path is a transform, this method will return the number of shapes directly below the transform.

Arguments

• num on success, this parameter will be set to the number of shapes directly underneath the transform

Return Value

• status code

Status Codes

• MS::kSuccess operation successful
• MS::kInvalidParameter DAG path does not lead to a transform or there is no geometry below it
• MS::kFailure the object is invalid

MStatus MDagPath:: push ( const MObject & child )

Description

Push an object onto the end of the path. The object must be a child of the object that is currently at the end of the path.

Arguments

• child child object to push onto the path

Return Value

• status code

Status Codes

• MS::kSuccess operation successful
• MS::kFailure unexpected error or invalid object
• MS::kInvalidParameter child is invalid or is not a child of the object at the end of this path

MStatus MDagPath:: pop ( unsigned int num )

Description

Pop the given number of objects off of the end of the path.

Arguments

• num number of objects to pop off of the path

Return Value

• status code

Status Codes

• MS::kSuccess operation successful
• MS::kInvalidParameter the number of objects to pop is greater than the length of the path
• MS::kFailure the object is invalid

unsigned int MDagPath:: childCount ( MStatus * ReturnStatus ) const

Description

Return the number of children that the object at the end of the path has.

Arguments

• ReturnStatus status code

Return Value

• the number of children

Status Codes

• MS::kSuccess operation successful
• MS::kFailure invalid object

MObject MDagPath:: child ( unsigned int index, MStatus * ReturnStatus ) const

Description

Return the child object at the given index, where the parent is the object at the end of the path.

Arguments

• index child's index
• ReturnStatus status code

Return Value

• a handle to the child

Status Codes

• MS::kSuccess operation successful
• MS::kInvalidParameter the index is out of range
• MS::kFailure the object is invalid

MMatrix MDagPath:: inclusiveMatrix ( MStatus *ReturnStatus) const

Description

Determines the inclusive matrix of the Path.

Arguments

• ReturnStatus status code

Return Value

• The matrix for all Transforms in the Path including the the end Node in the Path if it is a Transform

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid or it has a null path

MMatrix MDagPath:: exclusiveMatrix ( MStatus * ReturnStatus) const

Description

Determines the exclusive matrix of the Path.

Arguments

• ReturnStatus status code

Return Value

• The matrix for all transforms in the Path excluding the end Node in the Path if it is Transform

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

MMatrix MDagPath:: inclusiveMatrixInverse ( MStatus * ReturnStatus) const

Description

Determines the inverse inclusive matrix of the Path.

Arguments

• ReturnStatus status code

Return Value

• The inverse of the matrix for all Transforms in the Path including the end Node in the Path if it is a Transform

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

MMatrix MDagPath:: exclusiveMatrixInverse ( MStatus * ReturnStatus) const

Description

Determines the inverse exclusive matrix of the Path.

Arguments

• ReturnStatus status code

Return Value

• The inverse of the matrix for all transforms in the Path excluding the end Node in the Path if it is Transform

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

MDagPath & MDagPath:: operator = ( const MDagPath & src)

Description

Assigns the DAG Path on the RHS of the operator to the DAG Path on the LHS.

Arguments

• src the path to be copied

Return Value

• A bitwise copy of the the DAG Path on the LHS

Status Codes

• Nil

bool MDagPath:: operator == ( const MDagPath & src) const

Description

Determines if the DAG Path on the LHS of the operator is equal to the DAG Path on the RHS.

Arguments

• Nil

Return Value

• true -> LHS == RHS
• false -> LHS != RHS

Status Codes

• Nil

MStatus MDagPath:: set ( const MDagPath & src)

Description

Sets this DAG Path equal to the specified DAG Path.

Arguments

• src DAG Path to be copied.

Return Value

• status code

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

unsigned int MDagPath:: pathCount ( MStatus *ReturnStatus) const

Description

Return the number of paths which make up this path.

Arguments

• ReturnStatus status code

Return Value

• The path count

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

MStatus MDagPath:: getPath ( MDagPath & path, unsigned int i ) const

Description

Return the i'th path. The zero'th path is the top-most path and must be rooted by the world. Additional paths are paths in the underworld of the object at the end of the previous path (path i-1).

Arguments

• path reference to the destination path
• i the index of the path to retrieve

Return Value

• Status code

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

MString MDagPath:: fullPathName ( MStatus * ReturnStatus) const

Description

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

Arguments

• ReturnStatus status code

Return Value

• The full path name

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

MString MDagPath:: partialPathName ( MStatus * ReturnStatus) const

Description

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.

Arguments

• ReturnStatus status code

Return Value

• The partial path name

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

bool MDagPath:: isInstanced ( MStatus *ReturnStatus ) const

Description

Returns true if the object at the end of the DAG path is instanced. It is instanced if there is more than one path to the node from the top of the DAG. Each instance of the node will be drawn separately in the view, but the geometry will be shared.

Arguments

• ReturnStatus status code

Return Value

• true if the DAG node at the end of the path is instanced

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

unsigned int MDagPath:: instanceNumber ( MStatus *ReturnStatus ) const

Description

For an instanced object, this returns the instance number that this path represents in the DAG. The instance number can be used to determine which element of the world space array attributes of a DAG node to connect to get information regarding this instance.

Arguments

• ReturnStatus status code

Return Value

• the instance number represented by this path

Status Codes

• MS::kSuccess success
• MS::kFailure the object is invalid

This class has no child classes.