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 Class Reference

OpenMayaFX - API module for effects | FunctionSet classes

Detailed Description

Public Types

Public Member Functions

Protected Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation