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

- Class List
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | Protected Member Functions

# MFnParticleSystem Class Reference
OpenMayaFX - API module for effects | FunctionSet 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

Class for obtaining information about a particle system.

Particle object access class.

- isValid(): data is valid (predicate)
- renderType(): object render type
- count(): particle count at current frame

Use this chart to determine which methods to call based on the render type of the particle object:

- Valid Methods for render type kCloud:

  - position(): particle position
  - radius(): particle radius
  - surfaceShading(): object surface shading value
  - betterIllum(): invoke thick cloud sampling
  - threshold(): object threshold
  - disableCloudAxis(): for internal use; do not call
  - flatShaded(): cloud is flat shaded in modeling view

- Valid Methods for render type kTube:

  - position0(): particle start position
  - position1(): particle end position
  - radius0(): particle start radius
  - radius1(): particle end radius
  - tailSize(): length scale factor

- Valid Methods for render type kBlobby:

  - position(): particle position
  - radius(): particle radius
  - threshold(): object threshold

- Valid Methods for render type kHardware:
  - position(): particle position
  - radius(): particle radius

Examples:

  particlePathsCmd.cpp, and particleSystemInfoCmd.cpp.

`#include <MFnParticleSystem.h>`

Inheritance diagram for MFnParticleSystem:
[legend]

List of all members.

## Public Types
enum | RenderType { kCloud, kTube, kBlobby, kMultiPoint, kMultiStreak, kNumeric, kPoints, kSpheres, kSprites, kStreak }
| Ways in which particles can be rendered. More...
## Public Member Functions
virtual MFn::Type | type () const
| Function set type.
virtual | ~MFnParticleSystem ()
| Destructor.
| MFnParticleSystem ()
| Default constructor.
| MFnParticleSystem (MObject &object, MStatus *ReturnStatus=NULL)
| Constructor.
| MFnParticleSystem (const MDagPath &object, MStatus *ret=NULL)
| Constructor.
MObject | create (MStatus *status=NULL)
| To create a new particleShape with a transform.
MObject | create (MObject parent, MStatus *status=NULL)
| To create a new particleShape.
MStatus | emit (const MPoint &position)
| To add a new particle at the given position.
MStatus | emit (const MPointArray &positionArray)
| To add an array of new particles at the given positions.
MStatus | emit (const MPoint &position, const MVector &velocity)
| To add a new particle at the position with its velocity.
MStatus | emit (const MPointArray &positionArray, const MVectorArray &velocityArray)
| To add an array of new particles at the given positions with their velocity values.
MStatus | saveInitialState () const
| To reset the particle's current state as the initial state.
void | evaluateDynamics (MTime &to, bool runupFromStart)
| Run up the particle system to a certain frame, from either the current frame, or from the start of the simulation.
bool | isValid () const
| Returns false if the particle array is NULL.
MString | particleName () const
| Returns the name of this particle system. Search for all occurrences
unsigned int | count () const
| Returns the particle count at the current frame.
void | setCount (unsigned int) const
| Set the particle count at the current frame. Search for all occurrences
RenderType | renderType () const
| Return the render type used by the particle object.
void | position (MVectorArray &) const
| Compute each particle's position at the start of the time step.
void | velocity (MVectorArray &) const
| To return velocity array for all particles.
void | acceleration (MVectorArray &) const
| To return acceleration array for all particles.
void | position0 (MVectorArray &) const
| Only for use with an MFnParticleSystem of renderType kTube.
void | position1 (MVectorArray &) const
| Only for use with an MFnParticleSystem of renderType kTube.
void | radius (MDoubleArray &) const
| Calculates particle radii.
void | radius0 (MDoubleArray &) const
| Only for use with an MFnParticleSystem of renderType kTube.
void | radius1 (MDoubleArray &) const
| Only for use with an MFnParticleSystem of renderType kTube.
double | surfaceShading () const
| Only for use with an MFnParticleSystem of renderType kCloud.
double | threshold () const
| Only for use with an MFnParticleSystem of renderType kCloud or kBlobby.
bool | betterIllum () const
| Only for use with an MFnParticleSystem of renderType kCloud.
bool | flatShaded () const
| To check if a particle shape of cloud type is flat shaded.
bool | disableCloudAxis () const
| Only for use with an MFnParticleSystem of renderType kCloud.
double | tailSize () const
| Only for use with an MFnParticleSystem of renderType kTube.
void | particleIds (MIntArray &) const
| Return an array of particle identifiers at the start of the time step. Search for all occurrences
void | age (MDoubleArray &) const
| Populates the given array with the age values of the particles in this system.
void | lifespan (MDoubleArray &) const
| Populates the given array with the lifespan values of the particles in this system, if the particles have this attribute.
void | rgb (MVectorArray &) const
| Populates the given array with the color values of the particles in this system, if the particles have this attribute.
void | opacity (MDoubleArray &) const
| Populates the given array with the opacity values of the particles in this system, if the particles have this attribute.
void | mass (MDoubleArray &) const
| To return mass array for all particles.
void | emission (MVectorArray &) const
| Populates the given array with the incandescence values of the particles in this system, if the particles have this attribute.
bool | hasLifespan () const
| Returns whether or not the particles in this system have a lifespan attribute.
bool | hasRgb () const
| Returns whether or not the particles in this system have an rgb attribute.
bool | hasOpacity () const
| Returns whether or not the particles in this system have an opacity attribute.
bool | hasEmission () const
| Returns whether or not the particles in this system have an emission attribute. Search for all occurrences
bool | primaryVisibility () const
| Returns whether or not the rendering attribute for primary visibility in reflections has been enabled. Search for all occurrences
bool | visibleInReflections () const
| Returns whether or not the rendering attribute for particle visibility in reflections has been enabled. Search for all occurrences
bool | visibleInRefractions () const
| Returns whether or not the rendering attribute for particle visibility in refractions has been enabled. Search for all occurrences
bool | castsShadows () const
| Returns whether or not the rendering attribute for particles casting shadows has been enabled. Search for all occurrences
bool | receiveShadows () const
| Returns whether or not the rendering attribute for particles receiving shadows has been enabled.
unsigned int | getPerParticleAttribute (const MString &attrName, MIntArray &, MStatus *status=NULL) const
| To get per particle integer attribute with its attribute name.
unsigned int | getPerParticleAttribute (const MString &attrName, MVectorArray &, MStatus *status=NULL) const
| To get the per particle vector attribute of the given name.
unsigned int | getPerParticleAttribute (const MString &attrName, MDoubleArray &, MStatus *status=NULL) const
| To get the per particle double attribute of the given name.
void | setPerParticleAttribute (const MString &attrName, MVectorArray &, MStatus *status=NULL) const
| To set the per particle vector attribute of the given name with the given values.
void | setPerParticleAttribute (const MString &attrName, MDoubleArray &, MStatus *status=NULL) const
| To set the per particle double attribute of the given name with the given values.
bool | isPerParticleIntAttribute (const MString &attrName, MStatus *status=NULL) const
| To check if the input attribute is a per particle integer attribute.
bool | isPerParticleDoubleAttribute (const MString &attrName, MStatus *status=NULL) const
| To check if the input attribute is a per particle double attribute.
bool | isPerParticleVectorAttribute (const MString &attrName, MStatus *status=NULL) const
| To check if the input attribute is a per particle vector attribute.
bool | isDeformedParticleShape (MStatus *status=NULL) const
| To return if this particle shape is deformed.
MObject | deformedParticleShape (MStatus *status=NULL) const
| To get the deformed particleShape.
MObject | originalParticleShape (MStatus *status=NULL) const
| To get the original particleShape.
| MFnParticleSystem (const MObject &object, MStatus *ret=NULL)
| Constructor.
## Protected Member Functions Search for all occurrences
virtual const char * | className () const
| Class name. Search for all occurrences

## Member Enumeration Documentation

enum RenderType

Search for all occurrences

Ways in which particles can be rendered.

Enumerator:

  kCloud | Search for all occurrences
  kTube | Search for all occurrences
  kBlobby | Search for all occurrences
  kMultiPoint | Search for all occurrences
  kMultiStreak | Search for all occurrences
  kNumeric | Search for all occurrences
  kPoints | Search for all occurrences
  kSpheres | Search for all occurrences
  kSprites | Search for all occurrences
  kStreak | Search for all occurrences

## Constructor & Destructor Documentation

~MFnParticleSystem | ( |  | ) | `[virtual]`

Destructor.

Class destructor.

MFnParticleSystem | ( | MObject & | object,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters:

  [in] | object | The MObject to attach the function set to
  [out] | ReturnStatus | the return status

Status Codes:
  - MS::kSuccess if the function set is successfully attached
  - MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

MFnParticleSystem | ( | const MDagPath & | object,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Constructor.

Class constructor that initializes the function set to the given constant MDagPath object.

Parameters:

  [in] | object | The const MDagPath to attach the function set to
  [out] | ReturnStatus | The return status

Status Codes:
  - MS::kSuccess if the function set is successfully attached
  - MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

MFnParticleSystem | ( | const MObject & | object,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Constructor.

Class constructor that initializes the function set to the given MObject.

Parameters:

  [in] | object | The MObject to attach the function set to
  [out] | ReturnStatus | the return status

Status Codes:
  - MS::kSuccess if the function set is successfully attached
  - MS::kInvalidParameter if the MObject does not represent a valid Maya object or if the function set is not allowed to attach to this MObject

## Member Function Documentation

MFn::Type type | ( |  | ) | const`[virtual]`

Search for all occurrences

Function set type.

Return the class type : MFn::kParticle.

Reimplemented from MFnDagNode.

MObject create | ( | MStatus * | ReturnStatus = `NULL` | ) |

Search for all occurrences

To create a new particleShape with a transform.

Parameters:

  [out] | ReturnStatus | Status code

Returns:
  The newly created particleShape

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

Examples:
  particleSystemInfoCmd.cpp.

MObject create | ( | MObject | parentMObj,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  |

Search for all occurrences

To create a new particleShape.

If the parent is not specified, a new transform will be created as the parent.

Parameters:

  [in] | parentMObj | The parent as an MObject
  [out] | ReturnStatus | Status code

Returns:
  The newly created particleShape

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

MStatus emit | ( | const MPoint & | v | ) |

Search for all occurrences

To add a new particle at the given position.

Parameters:

  [in] | v | The particle's position

Returns:
  Return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

MStatus emit | ( | const MPointArray & | pArray | ) |

Search for all occurrences

To add an array of new particles at the given positions.

Parameters:

  [in] | pArray | The particle's position array

Returns:
  Return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

MStatus emit | ( | const MPoint & | p,
|  | const MVector & | v
| ) |  |

Search for all occurrences

To add a new particle at the position with its velocity.

Parameters:

  [in] | p | The particle's position
  [in] | v | The particle's velocity

Returns:
  Return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

MStatus emit | ( | const MPointArray & | pArray,
|  | const MVectorArray & | vArray
| ) |  |

Search for all occurrences

To add an array of new particles at the given positions with their velocity values.

Parameters:

  [in] | pArray | The particle's position array
  [in] | vArray | The particle's velocity array

Returns:
  Return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

MStatus saveInitialState | ( |  | ) | const

Search for all occurrences

To reset the particle's current state as the initial state.

Returns:
  Return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

void evaluateDynamics | ( | MTime & | to,
|  | bool | runupFromStart
| ) |  |

Search for all occurrences

Run up the particle system to a certain frame, from either the current frame, or from the start of the simulation.

Parameters:

  [in] | to | Time to run the particle system up to.
  [in] | runupFromStart | If true runup will begin at the start of the simulation, otherwise it will begin from the current frame.

bool isValid | ( |  | ) | const

Search for all occurrences

Returns false if the particle array is NULL.

Returns true otherwise.

void setCount | ( | unsigned int | count | ) | const

Search for all occurrences

Set the particle count at the current frame.

Parameters:

  [in] | count | Particle count.

void position | ( | MVectorArray & | positions | ) | const

Search for all occurrences

Compute each particle's position at the start of the time step.

This is done by taking the particle's current position and velocity, and extrapolation backwards in time.

NOTE: For an MFnParticleSystem of renderType kTube, use position0() and position1() instead.

void velocity | ( | MVectorArray & | array | ) | const

Search for all occurrences

To return velocity array for all particles.

Parameters:

  [out] | array | The resulting velocity array

void acceleration | ( | MVectorArray & | array | ) | const

Search for all occurrences

To return acceleration array for all particles.

Parameters:

  [out] | array | The resulting acceleration array

void position0 | ( | MVectorArray & | positions | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kTube.

Calculates particle start positions.

void position1 | ( | MVectorArray & | positions | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kTube.

Calculates particle end positions.

void radius | ( | MDoubleArray & | radii | ) | const

Search for all occurrences

Calculates particle radii.

NOTE: For an MFnParticleSystem of renderType kTube, use position0() and position1() instead.

void radius0 | ( | MDoubleArray & | radii | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kTube.

Calculates the particles' start radii.

void radius1 | ( | MDoubleArray & | radii | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kTube.

Calculates the particles' end radii.

double surfaceShading | ( |  | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kCloud.

Returns the object surface shading value.

double threshold | ( |  | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kCloud or kBlobby.

Returns the object threshold.

bool betterIllum | ( |  | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kCloud.

Returns a boolean indicating whether or not thick cloud sampling is already enabled.

bool flatShaded | ( |  | ) | const

Search for all occurrences

To check if a particle shape of cloud type is flat shaded.

This is only for use with an MFnParticleSystem of renderType kCloud.

Returns:
  - true The particles are displayed as flat shaded discs
  - false The particles are displayed as volumetric dics

bool disableCloudAxis | ( |  | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kCloud.

Internal use for better illum.

NOTE: Internal use only. Do not call.

double tailSize | ( |  | ) | const

Search for all occurrences

Only for use with an MFnParticleSystem of renderType kTube.

Returns the length scale factor.

void particleIds | ( | MIntArray & | ids | ) | const

Search for all occurrences

Return an array of particle identifiers at the start of the time step.

The array of particle id's is correlated with the other per-particle arrays returned by this class, so ids[i] will be the id for the particle with position position[i], velocity[i], etc., as long as all these arrays were retrieved for the same time step.

The particle id is a constant identifier for an individual particle that does not change between time steps. The particle id can be used to follow the path of a single particle between frames. Only living particle identifiers are returned by this method.

Parameters:

  [out] | ids | Array of particle identifiers. The contents of the array are overwritten with the current list of particle identifiers.

void lifespan | ( | MDoubleArray & | lifespans | ) | const

Search for all occurrences

Populates the given array with the lifespan values of the particles in this system, if the particles have this attribute.

See hasLifespan().

void rgb | ( | MVectorArray & | colors | ) | const

Search for all occurrences

Populates the given array with the color values of the particles in this system, if the particles have this attribute.

See hasRgb().

For each particle, processes the internal representation into RGB color values, which are mapped to a vector.

void opacity | ( | MDoubleArray & | opacities | ) | const

Search for all occurrences

Populates the given array with the opacity values of the particles in this system, if the particles have this attribute.

See hasOpacity().

void mass | ( | MDoubleArray & | array | ) | const

Search for all occurrences

To return mass array for all particles.

Parameters:

  [out] | array | The resulting mass array

void emission | ( | MVectorArray & | emissions | ) | const

Search for all occurrences

Populates the given array with the incandescence values of the particles in this system, if the particles have this attribute.

See hasEmission().

bool hasLifespan | ( |  | ) | const

Search for all occurrences

Returns whether or not the particles in this system have a lifespan attribute.

See lifespan().

bool hasRgb | ( |  | ) | const

Search for all occurrences

Returns whether or not the particles in this system have an rgb attribute.

See rgb().

bool hasOpacity | ( |  | ) | const

Search for all occurrences

Returns whether or not the particles in this system have an opacity attribute.

See opacity().

bool hasEmission | ( |  | ) | const

Search for all occurrences

Returns whether or not the particles in this system have an emission attribute.

See emission().

unsigned int getPerParticleAttribute | ( | const MString & | attrName,
|  | MIntArray & | array,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

To get per particle integer attribute with its attribute name.

Parameters:

  [in] | attrName | The input attribute name
  [out] | array | The returned integer array
  [out] | ReturnStatus | The returned status

Returns:
  The size of the returned integer array

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

unsigned int getPerParticleAttribute | ( | const MString & | attrName,
|  | MVectorArray & | array,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

To get the per particle vector attribute of the given name.

Parameters:

  [in] | attrName | The input attribute name
  [out] | array | The returned vector array
  [out] | ReturnStatus | The return status

Returns:
  The size of the returned vector array

unsigned int getPerParticleAttribute | ( | const MString & | attrName,
|  | MDoubleArray & | array,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

To get the per particle double attribute of the given name.

Parameters:

  [in] | attrName | The input attribute name
  [out] | array | The returned double array
  [out] | ReturnStatus | The return status

Returns:
  The size of the returned double array

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

void setPerParticleAttribute | ( | const MString & | attrName,
|  | MVectorArray & | array,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

To set the per particle vector attribute of the given name with the given values.

Parameters:

  [in] | attrName | The input attribute name
  [in] | array | The input vector array
  [out] | ReturnStatus | The return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

void setPerParticleAttribute | ( | const MString & | attrName,
|  | MDoubleArray & | array,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

To set the per particle double attribute of the given name with the given values.

Parameters:

  [in] | attrName | The input attribute name
  [in] | array | The input double array
  [out] | ReturnStatus | The return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

bool isPerParticleIntAttribute | ( | const MString & | attrName,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

To check if the input attribute is a per particle integer attribute.

Parameters:

  [in] | attrName | The input attribute name
  [out] | ReturnStatus | The return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

bool isPerParticleDoubleAttribute | ( | const MString & | attrName,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

To check if the input attribute is a per particle double attribute.

Parameters:

  [in] | attrName | The input attribute name
  [out] | ReturnStatus | The return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

bool isPerParticleVectorAttribute | ( | const MString & | attrName,
|  | MStatus * | ReturnStatus = `NULL`
| ) |  | const

Search for all occurrences

To check if the input attribute is a per particle vector attribute.

Parameters:

  [in] | attrName | The input attribute name
  [out] | ReturnStatus | The return status

Status Codes:
  - MS::kSuccess operation successful
  - MS::kFailure operation fail

bool isDeformedParticleShape | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

To return if this particle shape is deformed.

Parameters:

  [out] | ReturnStatus | Status code

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

Returns:
  true particle shape is deformed, false otherwise.

MObject deformedParticleShape | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

To get the deformed particleShape.

Parameters:

  [out] | ReturnStatus | Status code

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

Returns:
  The particle shape connecting to the output of the deformer(s)

MObject originalParticleShape | ( | MStatus * | ReturnStatus = `NULL` | ) | const

Search for all occurrences

To get the original particleShape.

Parameters:

  [out] | ReturnStatus | Status code

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

Returns:
  The particle shape connecting to the input of the deformer(s)

MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem
MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem MFnParticleSystem