MFnParticleSystem Class Reference
[OpenMayaFX - API module for effects, FunctionSet classes]

#include <MFnParticleSystem.h>

Inheritance diagram for MFnParticleSystem:

[legend]

Collaboration diagram for MFnParticleSystem:

[legend]

List of all members.

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
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.


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)
MObject	create (MObject parent, MStatus *status=NULL)
MStatus	emit (const MPoint &position)
MStatus	emit (const MPointArray &positionArray)
MStatus	emit (const MPoint &position, const MVector &velocity)
MStatus	emit (const MPointArray &positionArray, const MVectorArray &velocityArray)
MStatus	saveInitialState () const
void	evaluateDynamics (MTime &to, bool runupFromStart)
bool	isValid () const
MString	particleName () const
unsigned int	count () const
RenderType	renderType () const
void	position (MVectorArray &) const
void	velocity (MVectorArray &) const
void	acceleration (MVectorArray &) const
void	position0 (MVectorArray &) const
void	position1 (MVectorArray &) const
void	radius (MDoubleArray &) const
void	radius0 (MDoubleArray &) const
void	radius1 (MDoubleArray &) const
double	surfaceShading () const
double	threshold () const
bool	betterIllum () const
bool	disableCloudAxis () const
double	tailSize () const
void	particleIds (MIntArray &) const
void	age (MDoubleArray &) const
void	lifespan (MDoubleArray &) const
void	rgb (MVectorArray &) const
void	opacity (MDoubleArray &) const
void	mass (MDoubleArray &) const
void	emission (MVectorArray &) const
bool	hasLifespan () const
bool	hasRgb () const
bool	hasOpacity () const
bool	hasEmission () const
bool	primaryVisibility () const
bool	visibleInReflections () const
bool	visibleInRefractions () const
bool	castsShadows () const
bool	receiveShadows () const
unsigned int	getPerParticleAttribute (const MString &attrName, MIntArray &, MStatus *status=NULL) const
unsigned int	getPerParticleAttribute (const MString &attrName, MVectorArray &, MStatus *status=NULL) const
unsigned int	getPerParticleAttribute (const MString &attrName, MDoubleArray &, MStatus *status=NULL) const
void	setPerParticleAttribute (const MString &attrName, MVectorArray &, MStatus *status=NULL) const
void	setPerParticleAttribute (const MString &attrName, MDoubleArray &, MStatus *status=NULL) const
bool	isPerParticleIntAttribute (const MString &attrName, MStatus *status=NULL) const
bool	isPerParticleDoubleAttribute (const MString &attrName, MStatus *status=NULL) const
bool	isPerParticleVectorAttribute (const MString &attrName, MStatus *status=NULL) const
bool	isDeformedParticleShape (MStatus *status=NULL) const
MObject	deformedParticleShape (MStatus *status=NULL) const
MObject	originalParticleShape (MStatus *status=NULL) const
	MFnParticleSystem (const MObject &object, MStatus *ret=NULL)
	Constructor.
Protected Member Functions
virtual const char *	className () const
	Class name.

Member Enumeration Documentation

enum MFnParticleSystem::RenderType

Ways in which particles can be rendered.

Enumerator:

kCloud
kTube
kBlobby
kMultiPoint
kMultiStreak
kNumeric
kPoints
kSpheres
kSprites
kStreak

Constructor & Destructor Documentation

MFnParticleSystem::~MFnParticleSystem ( ) [virtual]

Destructor.

Class destructor.

MFnParticleSystem::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::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::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 MFnParticleSystem::type ( ) const [virtual]

Function set type.

Return the class type : MFn::kParticle

Reimplemented from MFnDagNode.

MObject MFnParticleSystem::create ( MStatus * ReturnStatus = NULL )

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 MFnParticleSystem::create	(	MObject	parentMObj,
		MStatus *	ReturnStatus = `NULL`
	)

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 MFnParticleSystem::emit ( const MPoint & v )

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 MFnParticleSystem::emit ( const MPointArray & pArray )

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 MFnParticleSystem::emit	(	const MPoint &	p,
		const MVector &	v
	)

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 MFnParticleSystem::emit	(	const MPointArray &	pArray,
		const MVectorArray &	vArray
	)

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 MFnParticleSystem::saveInitialState ( ) const

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 MFnParticleSystem::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 MFnParticleSystem::isValid ( ) const

Returns false if the particle array is NULL.

Returns true otherwise.

MString MFnParticleSystem::particleName ( ) const

Returns the name of this particle system.

unsigned int MFnParticleSystem::count ( ) const

Returns the particle count at the current frame.

MFnParticleSystem::RenderType MFnParticleSystem::renderType ( ) const

Return the render type used by the particle object.

void MFnParticleSystem::position ( MVectorArray & positions ) const

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 MFnParticleSystem::velocity ( MVectorArray & array ) const

To return velocity array for all particles.

Parameters:

[out] array The resulting velocity array

void MFnParticleSystem::acceleration ( MVectorArray & array ) const

To return acceleration array for all particles.

Parameters:

[out] array The resulting acceleration array

void MFnParticleSystem::position0 ( MVectorArray & positions ) const

Only for use with an MFnParticleSystem of renderType kTube.

Calculates particle start positions.

void MFnParticleSystem::position1 ( MVectorArray & positions ) const

Only for use with an MFnParticleSystem of renderType kTube.

Calculates particle end positions.

void MFnParticleSystem::radius ( MDoubleArray & radii ) const

Calculates particle radii.

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

void MFnParticleSystem::radius0 ( MDoubleArray & radii ) const

Only for use with an MFnParticleSystem of renderType kTube.

Calculates the particles' start radii.

void MFnParticleSystem::radius1 ( MDoubleArray & radii ) const

Only for use with an MFnParticleSystem of renderType kTube.

Calculates the particles' end radii.

double MFnParticleSystem::surfaceShading ( ) const

Only for use with an MFnParticleSystem of renderType kCloud.

Returns the object surface shading value.

double MFnParticleSystem::threshold ( ) const

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

Returns the object threshold.

bool MFnParticleSystem::betterIllum ( ) const

Only for use with an MFnParticleSystem of renderType kCloud.

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

bool MFnParticleSystem::disableCloudAxis ( ) const

Only for use with an MFnParticleSystem of renderType kCloud.

Internal use for better illum.

NOTE: Internal use only. Do not call.

double MFnParticleSystem::tailSize ( ) const

Only for use with an MFnParticleSystem of renderType kTube.

Returns the length scale factor.

void MFnParticleSystem::particleIds ( MIntArray & ids ) const

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 MFnParticleSystem::age ( MDoubleArray & ages ) const

Populates the given array with the age values of the particles in this system.

void MFnParticleSystem::lifespan ( MDoubleArray & lifespans ) const

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

void MFnParticleSystem::rgb ( MVectorArray & colors ) const

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 MFnParticleSystem::opacity ( MDoubleArray & opacities ) const

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

void MFnParticleSystem::mass ( MDoubleArray & array ) const

To return mass array for all particles.

Parameters:

[out] array The resulting mass array

void MFnParticleSystem::emission ( MVectorArray & emissions ) const

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

bool MFnParticleSystem::hasLifespan ( ) const

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

bool MFnParticleSystem::hasRgb ( ) const

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

bool MFnParticleSystem::hasOpacity ( ) const

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

bool MFnParticleSystem::hasEmission ( ) const

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

bool MFnParticleSystem::primaryVisibility ( ) const

Returns whether or not the rendering attribute for primary visibility in reflections has been enabled.

bool MFnParticleSystem::visibleInReflections ( ) const

Returns whether or not the rendering attribute for particle visibility in reflections has been enabled.

bool MFnParticleSystem::visibleInRefractions ( ) const

Returns whether or not the rendering attribute for particle visibility in refractions has been enabled.

bool MFnParticleSystem::castsShadows ( ) const

Returns whether or not the rendering attribute for particles casting shadows has been enabled.

bool MFnParticleSystem::receiveShadows ( ) const

Returns whether or not the rendering attribute for particles receiving shadows has been enabled.

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

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 MFnParticleSystem::getPerParticleAttribute	(	const MString &	attrName,
		MVectorArray &	array,
		MStatus *	ReturnStatus = `NULL`
	)			const

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 MFnParticleSystem::getPerParticleAttribute	(	const MString &	attrName,
		MDoubleArray &	array,
		MStatus *	ReturnStatus = `NULL`
	)			const

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 MFnParticleSystem::setPerParticleAttribute	(	const MString &	attrName,
		MVectorArray &	array,
		MStatus *	ReturnStatus = `NULL`
	)			const

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 MFnParticleSystem::setPerParticleAttribute	(	const MString &	attrName,
		MDoubleArray &	array,
		MStatus *	ReturnStatus = `NULL`
	)			const

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 MFnParticleSystem::isPerParticleIntAttribute	(	const MString &	attrName,
		MStatus *	ReturnStatus = `NULL`
	)			const

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 MFnParticleSystem::isPerParticleDoubleAttribute	(	const MString &	attrName,
		MStatus *	ReturnStatus = `NULL`
	)			const

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 MFnParticleSystem::isPerParticleVectorAttribute	(	const MString &	attrName,
		MStatus *	ReturnStatus = `NULL`
	)			const

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 MFnParticleSystem::isDeformedParticleShape ( MStatus * ReturnStatus = NULL ) const

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 MFnParticleSystem::deformedParticleShape ( MStatus * ReturnStatus = NULL ) const

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 MFnParticleSystem::originalParticleShape ( MStatus * ReturnStatus = NULL ) const

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

MFnParticleSystem Class Reference
[OpenMayaFX - API module for effects, FunctionSet classes]