- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions

# MItInstancer Class Reference
OpenMaya - API module for common classes

This reference page is linked to from the following overview topics: Overview of example plug-ins, Example C++ plug-in descriptions.

Search for all occurrences

## Detailed Description

Particle iterator.

Maya's Particle Replacement aka Particle Instancing feature allows geometry to be instanced and those instances transformed using particles. More precisely, particles are replaced by arbitrary DAG nodes which maya be transforms with many shapes under them, and multiple DAG paths to those shapes.

The Instancer Iterator Class (MItInstancer) provides methods for iterating over all the dag paths to the shapes created in the scene by the replacement of particles by dag nodes.

When particles are being replaced by a shape node there will be one dag path corresponding with each particle. If, say, particles are instead being replaced by a transform with five shape nodes somewhere underneath it, then this iterator will visit five paths for every particle. Dag-instancing is also respected: if the given dag node has two child transforms each of which is a path to one shape underneath them, then this iterator will visit two paths. In other words, this iterator does not distinguish between paths resulting from a multiplicity of actual shapes and paths resulting from DAG-instances of individual shapes: all appear as different paths for the current particle.

A simple usage might look like:

MItInstancer it; while( ! it.isDone() ) { MDagPath path = it.path(); MString label = path.fullPathName(); MGlobal::displayInfo( label ); it.next(); }

Examples:

  instancerListCmd.cpp.

`#include <MItInstancer.h>`

List of all members.

## Public Member Functions
| MItInstancer ()
| Constructs a dag-path-to-replaced-particle Iterator and resets it See reset() for more information.
virtual | ~MItInstancer ()
| Class destructor.
MStatus | reset ()
| Moves the iterator to the first dag-path to the first replaced-particle in the scene.
MStatus | next ()
| Advances the iterator to the next replaced-particle dag-path in the scene.
MStatus | nextParticle ()
| Advances the iterator to the next replaced-particle in the scene, skipping over any remaining dag-paths associated with the current replaced-particle.
MStatus | nextInstancer ()
| Advances the iterator to the next instancer in the scene, skipping over any remaining particles associated with the current instancer.
bool | isDone () const
| Returns true if the iteration is finished, i.e.
MObject | instancer () const
| Returns the current instancer node as an MObject.
MDagPath | instancerPath () const
| Returns the full DAG path to the instancer that generated the current particle instance.
MDagPath | path ()
| Returns the replaced-particle dag-path which the iterator is currently pointing to.
MMatrix | matrix ()
| Returns the transformation matrix represented by the current path.
MUintPtrSz | instancerId () const
| Returns a unique identifier for the current instancer.
unsigned int | particleId () const
| Returns a unique identifier for the current particle.
unsigned int | pathId () const
| Returns a unique identifier for the current path.
## Static Public Member Functions
static const char * | className ()
| Returns the name of this class.

## Member Function Documentation

MStatus reset | ( |  | ) |

Search for all occurrences

Moves the iterator to the first dag-path to the first replaced-particle in the scene.

If none exist, then isDone() will be immediately true.

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

MStatus next | ( |  | ) |

Search for all occurrences

Advances the iterator to the next replaced-particle dag-path in the scene.

Calling reset(), then repeatedly calling this method until isDone() becomes true is equivalent to the following loop structure:

For every instancer For every particle For every dagPath connected to this instancer

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

Examples:
  instancerListCmd.cpp.

MStatus nextParticle | ( |  | ) |

Search for all occurrences

Advances the iterator to the next replaced-particle in the scene, skipping over any remaining dag-paths associated with the current replaced-particle.

If there are no more particles associated with the current instancer then the iterator will advance to the next instancer in order to point at the next particle.

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

MStatus nextInstancer | ( |  | ) |

Search for all occurrences

Advances the iterator to the next instancer in the scene, skipping over any remaining particles associated with the current instancer.

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

bool isDone | ( |  | ) | const

Search for all occurrences

Returns true if the iteration is finished, i.e.

there are no more dag-paths to replaced-particles in the scene.

Returns:
  - true There are no more items to iterate over.
  - false There are more items in the iteration.

Examples:
  instancerListCmd.cpp.

MObject instancer | ( |  | ) | const

Search for all occurrences

Returns the current instancer node as an MObject.

Returns:
  See description.

Examples:
  instancerListCmd.cpp.

MDagPath instancerPath | ( |  | ) | const

Search for all occurrences

Returns the full DAG path to the instancer that generated the current particle instance.

A NULL path will be returned if there is no current instancer being iterated

Returns:
  See description.

Examples:
  instancerListCmd.cpp.

MDagPath path | ( |  | ) |

Search for all occurrences

Returns the replaced-particle dag-path which the iterator is currently pointing to.

Each path is to a shape. If the particle is replaced by a shape directly then there will be only one path per particle. If a particle is replaced by a transform with many child shapes then each one of those shapes will have a path. Amongst the paths corresponding to a given particle there may be multiple paths to multiple shapes. If there is no such path, a null path will be returned.

Returns:
  See description.

Examples:
  instancerListCmd.cpp.

MMatrix matrix | ( |  | ) |

Search for all occurrences

Returns the transformation matrix represented by the current path.

If there is no such path, identity matrix will be returned.

Returns:
  See description.

Examples:
  instancerListCmd.cpp.

MUintPtrSz instancerId | ( |  | ) | const

Search for all occurrences

Returns a unique identifier for the current instancer.

Collectively, this id together with the particle id and the path id uniquely identify a "replaced particle".

Returns:
  See description.

unsigned int particleId | ( |  | ) | const

Search for all occurrences

Returns a unique identifier for the current particle.

Collectively, this id together with the instancer id and the path id uniquely identify a "replaced particle".

Returns:
  See description.

unsigned int pathId | ( |  | ) | const

Search for all occurrences

Returns a unique identifier for the current path.

Collectively, this id together with the instancer id and the particle id uniquely identify a "replaced particle".

Returns:
  See description.

const char * className | ( |  | ) | `[static]`

Search for all occurrences

Returns the name of this class.

Returns:
  The name of this class.

MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer
MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer MItInstancer