MItGeometry Class Reference
[OpenMaya - API module for common classes]

#include <MItGeometry.h>

List of all members.

---

Detailed Description

Iterator class for geometry data.

This class is the iterator class for geometry data, and can be used to loop over the CVs of NURBS, the points of subds & lattices, and the vertices of polygonal meshes.

Examples:

Simple traversal.

    MItGeometry iter( dagPath );
    for ( ; !iter.isDone(); iter.next() )
    {
        MPoint pt = iter.position();

        // do something with it
    }

Traversal of a geometry group within a compute() method.

    MStatus
    exampleIterator::compute(const MPlug& plug, MDataBlock& dataBlock)
    {
        MStatus status;

        if (plug.attribute() == oOutputGeometry) {
            // get the input geometry and input groupId
            MDataHandle hInputGeom = dataBlock.inputValue(inputGeomAttr);
            MDataHandle hGroupId = dataBlock.inputValue(inputGroupIdAttr);

            unsigned int groupId = hGroup.asLong();
            MDataHandle hOutput = dataBlock.outputValue(plug);
            hOutput.copy(hInputGeom);

            // do an iteration where we get each point and set it to a new value
            MItGeometry iter(hOutput,groupId,false);
            for ( ; !iter.isDone(); iter.next()) {
                MPoint pt = iter.position();

                // do something here to modify the point ...

                iter.setPosition(pt);
            }
        } else {
            status = MStatus::kUnknownParameter;
        }        

        return status;
    }

Examples:

clusterWeightFunction.cpp, exportJointClusterDataCmd.cpp, exportSkinClusterDataCmd.cpp, offsetNode.cpp, and yTwistNode.cpp.

Public Member Functions
	MItGeometry (const MDagPath &dagPath, MStatus *ReturnStatus=NULL)
	MItGeometry (const MDagPath &dagPath, MObject &component, MStatus *ReturnStatus=NULL)
	MItGeometry (MObject &dagObject, MStatus *ReturnStatus=NULL)
	MItGeometry (MDataHandle &dataHandle, unsigned int groupId, bool readOnly=true, MStatus *ReturnStatus=NULL)
	MItGeometry (MDataHandle &dataHandle, bool readOnly=true, MStatus *ReturnStatus=NULL)
virtual	~MItGeometry ()
bool	isDone (MStatus *ReturnStatus=NULL) const
MStatus	next ()
MPoint	position (MSpace::Space space=MSpace::kObject, MStatus *ReturnStatus=NULL) const
MStatus	setPosition (const MPoint &point, MSpace::Space space=MSpace::kObject)
MWeight	weight (MStatus *ReturnStatus=NULL) const
int	index (MStatus *ReturnStatus=NULL) const
MObject	component (MStatus *ReturnStatus=NULL) const
	This method is obsolete.
MObject	currentItem (MStatus *ReturnStatus=NULL) const
int	count (MStatus *ReturnStatus=NULL) const
int	exactCount (MStatus *ReturnStatus=NULL)
MStatus	reset ()
MStatus	allPositions (MPointArray &points, MSpace::Space space=MSpace::kObject) const
MStatus	setAllPositions (const MPointArray &points, MSpace::Space space=MSpace::kObject)

---

Constructor & Destructor Documentation

MItGeometry::MItGeometry	(	const MDagPath &	dagPath,
		MStatus *	ReturnStatus = NULL
	)

Constructor. This constructor is used to iterate over all of the points/CV/vertices of a dag object given a particular dag path.

Parameters:

[in]	dagPath	The dag path to the object.
[out]	ReturnStatus	Status code

Status Codes:

• MS::kSuccess The iterator was constructed successfully.
• MS::kInsufficientMemory No memory available.
• MS::kInvalidParameter An invalid object was given.

MItGeometry::MItGeometry	(	const MDagPath &	dagPath,
		MObject &	component,
		MStatus *	ReturnStatus = NULL
	)

Constructor. This constructor is used to iterate over the points/CVs/vertices of a dag object given a particular dag path. The iteration will be over the points/CVs/Vertices specified by the component argument. If the component is null then the iteration will be over the entire object.

Parameters:

[in]	dagPath	The dag path to the object.
[in]	component	The components of the object to iterate over. If this is null then the iteration will be over all components of the object.
[out]	ReturnStatus	Status code

Status Codes:

• MS::kSuccess The iterator was constructed successfully.
• MS::kInsufficientMemory No memory available.
• MS::kInvalidParameter An invalid object was given.

MItGeometry::MItGeometry	(	MObject &	dagObject,
		MStatus *	ReturnStatus = NULL
	)

Constructor. This constructor is used to iterate over all of the points/CV/vertices of the given dag object. Since there is no path information passed into this constructor world space operations will not be possible.

Parameters:

[in]	dagObject	The DAG object to iterate.
[out]	ReturnStatus	Status code

Status Codes:

• MS::kSuccess The iterator was constructed successfully.
• MS::kInsufficientMemory No memory available.
• MS::kInvalidParameter An invalid object was given.

MItGeometry::MItGeometry	(	MDataHandle &	dataHandle,
		unsigned int	groupId,
		bool	readOnly = true,
		MStatus *	ReturnStatus = NULL
	)

Constructor. This constructor is used when iterating from within the compute() method of a node. The point/CV/vertex components of the specified group within the geometry data that is pointed to by the dataHandle will be iterated. If readOnly mode is set to false, the setPosition method can be utilized.

Parameters:

[in]	dataHandle	The dataHandle pointing to the geometry data.
[in]	groupId	The id of the group whose components will be iterated.
[in]	readOnly	If false you will be allowed to modify the geometry position data during the iteration.
[out]	ReturnStatus	Status code

Status Codes:

• MS::kSuccess The iterator was constructed successfully.
• MS::kInsufficientMemory No memory available.
• MS::kInvalidParameter An invalid object was given.

MItGeometry::MItGeometry	(	MDataHandle &	dataHandle,
		bool	readOnly = true,
		MStatus *	ReturnStatus = NULL
	)

Constructor. This constructor is used when iterating from within the compute() method of a node. The point/CV/vertex components of the geometry data pointed to by the dataHandle will be iterated. If readOnly mode is set to false, the setPosition method can be utilized.

Parameters:

[in]	dataHandle	The dataHandle pointing to the geometry data.
[in]	readOnly	If false you will be allowed to modify the geometry position data during the iteration.
[out]	ReturnStatus	Status code

Status Codes:

• MS::kSuccess The iterator was constructed successfully.
• MS::kInsufficientMemory No memory available.
• MS::kInvalidParameter An invalid object was given.

MItGeometry::~MItGeometry

(

)

[virtual]

Class destructor. Deallocates memory used by this iterator.

---

Member Function Documentation

bool MItGeometry::isDone

(

MStatus *

ReturnStatus = NULL

)

const

Returns true if the iteration is finished, i.e. there are no more components to iterate on.

Parameters:

[out]

ReturnStatus

Status code

Returns:

Bool true if There are no more components to iterate on, false otherwise.

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure An object error has occurred.

Examples:

offsetNode.cpp, and yTwistNode.cpp.

MStatus MItGeometry::next

(

)

Advance to the next component in the iteration. If the iterator is already at the last component then this method has no effect. Use isDone to determine if the iterator is at the last component.

Returns:

Status code

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure An object error has occurred.

Examples:

offsetNode.cpp, and yTwistNode.cpp.

MPoint MItGeometry::position	(	MSpace::Space	space = MSpace::kObject,
		MStatus *	ReturnStatus = NULL
	)			const

Return the position of the current point/CV/vertex component.

Parameters:

[in]	space	The transformation space in which the operation is done
[out]	ReturnStatus	Status code

Returns:

Status code

Status Codes:

• MS::kSuccess The position of the current component was returned.
• MS::kInvalidParameter Cannot do world space transform.
• MS::kFailure An Object error has occurred.

Examples:

offsetNode.cpp, and yTwistNode.cpp.

MStatus MItGeometry::setPosition	(	const MPoint &	pt,
		MSpace::Space	space = MSpace::kObject
	)

Set the position of the current point/CV/vertex.

Parameters:

[in]

space

The transformation space in which the operation is done

Returns:

Status code

Status Codes:

• MS::kSuccess The transformation was successful.
• MS::kInvalidParameter Cannot do world space transform.
• MS::kFailure The transformation was not successful because the data was read only.

Examples:

offsetNode.cpp, and yTwistNode.cpp.

MWeight MItGeometry::weight

(

MStatus *

ReturnStatus = NULL

)

const

Return the weight of the current point/CV/vertex component.

Parameters:

[out]

ReturnStatus

Status code

Returns:

The current component's weight

int MItGeometry::index

(

MStatus *

ReturnStatus = NULL

)

const

This method returns the index of the current point/CV/vertex component in the iteration.

Parameters:

[out]

ReturnStatus

Status code

Returns:

The index of the current point/CV/vertex.

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure An object error has occurred.

Examples:

offsetNode.cpp.

MObject MItGeometry::component

(

MStatus *

ReturnStatus = NULL

)

const

This method is obsolete.

Deprecated:

Use the method MItGeometry::currentItem instead.

This method returns the current component in the iteration.

Parameters:

[out]

ReturnStatus

Status code

Returns:

The current component in the iteration.

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure An object error has occurred.

MObject MItGeometry::currentItem

(

MStatus *

ReturnStatus = NULL

)

const

This method returns the current component in the iteration.

Parameters:

[out]

ReturnStatus

Status code

Returns:

The current component in the iteration.

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure An object error has occurred.

int MItGeometry::count

(

MStatus *

ReturnStatus = NULL

)

const

Return the number of items in this iteration. This number will always be at least as large as the number of items, however in some cases it may be larger. It is useful if allocating space in an array to hold the results, since it will always be of sufficient size. If the exact number of items is required, use the exactCount method instead. The exactCount method is however significantly slower than this method.

Parameters:

[out]

ReturnStatus

Status code

Returns:

The number of items that will be iterated

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure An object error has occurred.

int MItGeometry::exactCount

(

MStatus *

ReturnStatus = NULL

)

Return the exact number of items in this iteration. This method is significantly slower than the count() method, so use if only if the precise number is required.

Parameters:

[out]

ReturnStatus

Status code

Returns:

The number of items that will be iterated

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure An object error has occurred.

MStatus MItGeometry::reset

(

)

Reset the iterator to the first component.

Returns:

Status code

Status Codes:

• MS::kSuccess The iterator was successfully reset
• MS::kFailure Error resetting iterator

MStatus MItGeometry::allPositions	(	MPointArray &	points,
		MSpace::Space	space = MSpace::kObject
	)			const

Return the position of all the points/CVs/vertices. This operation is faster than using the iterator to get values one by one, but uses more memory as it requires an array to hold all the values to be returned.

Parameters:

[out]	points	Storage for positions
[in]	space	The transformation space in which the operation is done

Returns:

Status code

Status Codes:

• MS::kSuccess The position of the current component was returned.
• MS::kInvalidParameter Cannot do world space transform.
• MS::kFailure An Object error has occurred.

MStatus MItGeometry::setAllPositions	(	const MPointArray &	pt,
		MSpace::Space	space = MSpace::kObject
	)

Set the position of all the points/CVs/vertices at once. This operation is faster than using the iterator to set values one by one, but uses more memory as it requires an array to hold all the values to be set.

Parameters:

[in]	pt	An array containing all the positions to be set
[in]	space	The transformation space in which the operation is done

Returns:

Status code

Status Codes:

• MS::kSuccess The transformation was successful.
• MS::kInvalidParameter Cannot do world space transform.
• MS::kFailure The transformation was not successful because the data was read only.