Detailed Description

Represents one particle in a particle cloud.

Particles are accessible via ParticleCloudPrimitive::GetParticle.

See also:: ParticleCloud, ParticleCloudPrimitive, X3DObject::AddParticleCloud

Deprecated:: 8.0 (2010) Legacy particles are kept for backward compatibility.

Example:

Creates the initial state for a particle simulation

        using namespace XSI;
        Application app ;

        CValueArray args(2) ;
        CValue outArg;

        args[0] = (LONG) siSphereType ;
        app.ExecuteCommand( L"CreateParticleType", args, outArg ) ;

        Property myParType = args[1] ;
        myParType.PutName( CString(L"CustomParType") ) ;

        CRefArray particleTypeArray ;
        particleTypeArray.Add( myParType ) ;

        // Create a particle cloud.  This has no emittor, and no particle operator
        // so the cloud state is completely the responsibility of the plug-in
        // and will not change even if the current frame is changed
        ParticleCloud myParticleCloud ;
        app.GetActiveSceneRoot().AddParticleCloud(
                                    particleTypeArray,
                                    L"MyCloud",
                                    myParticleCloud ) ;

        ParticleCloudPrimitive myParticlePrim = myParticleCloud.GetActivePrimitive() ;

        // Our "CustomParType" will automatically be used because
        // we specified it in the call to AddParticleCloud
        myParticlePrim.AddParticles( 1000, CRef() ) ;

        // Position the particles in a 3D grid
        for ( LONG i = 0 ; i < 10 ; i++ )
        {
            for ( LONG j = 0 ; j < 10 ; j++ )
            {
                for ( LONG k = 0 ; k < 10 ; k++ )
                {
                    LONG index = i*100 + j*10 + k ;
                    Particle oParticle = myParticlePrim.GetParticle(index) ;
                    oParticle.PutPosition( MATH::CVector3(-5 + i, -3 +j, k)) ;

                    //Sets different ages so that the particles
                    //will die during the playback
                    oParticle.PutAge( 1 + j * 10 ) ;
                    oParticle.PutAgeLimit( 100 ) ;
                }
            }
        }

        // Call the CreateParticleCloud command to create a new
        // cloud which uses our "static" cloud as the initial state

        // This new cloud will include a particle operator so
        // it will perform a simulation, allowing us to see the
        // age change for the particles.
        args[0] = myParticleCloud ; // Where to add the particle cloud
        args[1] = CValue() ; // No emitter necessary, particles already exist
        app.ExecuteCommand( L"CreateParticleCloud", args, outArg ) ;

        // Sets some attributes on the new cloud's particle type
        CValueArray & NewParticleClouds = outArg ;
        ParticleCloud myNewCloud = NewParticleClouds[0] ;
        ParticleCloudPrimitive myNewCloudPrim = myNewCloud.GetActivePrimitive() ;
        Property myNewCloudParType = myNewCloudPrim.GetParticleTypes().GetItem(0) ;

        myNewCloudParType.PutParameterValue( L"Size", 0.3 ) ;
        myNewCloudParType.PutParameterValue( L"Red", 0.99 ) ;
        myNewCloudParType.PutParameterValue( L"Green", 0.00 ) ;
        myNewCloudParType.PutParameterValue( L"Blue", 0.10 ) ;
        myNewCloudParType.PutParameterValue( L"Alpha", 0.50 ) ;

        // Hide the original cloud (we could also delete it)
        args.Resize(1) ;
        args[0] = myParticleCloud ;
        app.ExecuteCommand( L"ToggleVisibility", args, outArg ) ;

        // Start playing to show the particles disappearing
        args.Resize(0) ;
        app.ExecuteCommand( L"PlayForwardsFromStart", args, outArg ) ;

#include <xsi_particle.h>

Inheritance diagram for Particle:

[legend]

List of all members.

Public Member Functions
	Particle ()
	~Particle ()
	Particle (const CRef &in_ref)
	Particle (const Particle &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Particle &	operator= (const Particle &in_obj)
Particle &	operator= (const CRef &in_ref)
LONG	GetIndex () const
LONG	GetID () const
LONG	GetTypeID () const
CStatus	PutTypeID (LONG in_TypeID)
MATH::CVector3	GetPosition () const
CStatus	PutPosition (const MATH::CVector3 &in_vect)
MATH::CVector3	GetVelocity () const
CStatus	PutVelocity (const MATH::CVector3 &in_vect)
MATH::CRotation	GetAngularVelocity () const
CStatus	PutAngularVelocity (const MATH::CRotation &in_vect)
MATH::CVector3	GetRotation () const
CStatus	PutRotation (const MATH::CVector3 &in_vect)
double	GetPathLength () const
LONG	GetAge () const
CStatus	PutAge (LONG in_age)
LONG	GetAgeLimit () const
CStatus	PutAgeLimit (LONG in_agelimit)
LONG	GetSeed () const
CStatus	PutSeed (LONG in_seed)
CColor	GetColor () const
CStatus	PutColor (const CColor &in_vColor)
MATH::CVector3	GetUVW () const
CStatus	PutUVW (const MATH::CVector3 &in_vect)
LONG	GetSpriteIndex () const
CStatus	PutSpriteIndex (LONG in_index)
double	GetSpriteAngle () const
CStatus	PutSpriteAngle (double in_angle)
double	GetSize () const
CStatus	PutSize (double in_size)
double	GetMass () const
CStatus	PutMass (double in_mass)
double	GetDensity () const
double	GetPressure () const
CRefArray	GetAttributes () const

Constructor & Destructor Documentation

Particle ( )

Default constructor.

~Particle ( )

Default destructor.

Particle ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

Particle ( const Particle & in_obj )

Copy constructor.

Parameters:

in_obj constant class object.

Member Function Documentation

bool IsA ( siClassID in_ClassID ) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID class type.

Returns:: true if the class is compatible, false otherwise.

Reimplemented from SIObject.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:: The class type.

Reimplemented from SIObject.

Particle& operator= ( const Particle & in_obj )

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj constant class object.

Returns:: The new Particle object.

Particle& operator= ( const CRef & in_ref )

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref constant class object.

Returns:: The new Particle object.

Reimplemented from SIObject.

LONG GetIndex ( ) const

Returns the index of the particle in the particle collection. A particle's index can change throughout a simulation when particles are added or removed from the cloud.

Returns:: The index of the particle

LONG GetID ( ) const

Returns the particle's ID. A particle ID is a number that uniquely identifies the particle within a cloud. It is invariant throughout the simulation.

Returns:: The particle ID

LONG GetTypeID ( ) const

Returns the type ID for the particle. A cloud can contain particles from multiple particle types.

Returns:: The type ID for the particle

See also:: Particle::PutTypeID, ParticleCloudPrimitive::GetParticleTypes

CStatus PutTypeID ( LONG in_TypeID )

Changes the type ID of the particle.

Parameters:

in_TypeID The new type ID for the particle

See also:: Particle::GetTypeID

MATH::CVector3 GetPosition ( ) const

Returns the particle position

Returns:: The position of the particle

See also:: Particle::GetVelocity

CStatus PutPosition ( const MATH::CVector3 & in_vect )

Sets the particle position

Parameters:

in_vect The position of the particle

See also:: Particle::GetVelocity

MATH::CVector3 GetVelocity ( ) const

Returns the particle velocity

Returns:: The speed of the particle

See also:: Particle::PutVelocity

CStatus PutVelocity ( const MATH::CVector3 & in_vect )

Sets the particle velocity

Parameters:

in_vect The speed of the particle

See also:: Particle::GetVelocity

MATH::CRotation GetAngularVelocity ( ) const

Returns the particle angular velocity

Returns:: The speed of the particle's rotation

See also:: Particle::PutAngularVelocity

CStatus PutAngularVelocity ( const MATH::CRotation & in_vect )

Sets the particle angular velocity

Parameters:

in_vect The speed of the particle's rotation

See also:: Particle::GetAngularVelocity

MATH::CVector3 GetRotation ( ) const

Returns the particle rotation

Returns:: The particle's rotation

See also:: Particle::PutRotation

CStatus PutRotation ( const MATH::CVector3 & in_vect )

Sets the particle rotation

Parameters:

in_vect The particle's rotation

See also:: Particle::GetRotation

double GetPathLength ( ) const

Returns the distance that the particle has travelled since birth.

Returns:: The particle's path length

LONG GetAge ( ) const

Returns the particle's age (frames since the particles birth). This can be a useful function in a custom operator for detecting if a particle is freshly born to run special initialization code.

Returns:: The particle's age

See also:: Particle::PutAge

CStatus PutAge ( LONG in_age )

Sets the particle's age (in frames)

Parameters:

in_age The particle's age

See also:: Particle::GetAge

LONG GetAgeLimit ( ) const

Returns the particle life span (in frames)

Returns:: The particle's lifespan

See also:: Particle::PutAgeLimit

CStatus PutAgeLimit ( LONG in_agelimit )

Sets the particle life span

Parameters:

in_agelimit The particle's lifespan

See also:: Particle::GetAgeLimit

LONG GetSeed ( ) const

Returns the random number generator seed for the particle

Returns:: The number to use as a seed

See also:: Particle::PutSeed

CStatus PutSeed ( LONG in_seed )

Sets the random number generator seed of the particle

Parameters:

in_seed The number to use as a seed

See also:: Particle::GetSeed

CColor GetColor ( ) const

Returns the particle's color

Returns:: The particle color

See also:: Particle::PutColor

CStatus PutColor ( const CColor & in_vColor )

Sets the particle's color

Parameters:

in_vColor The color to set, normalized with each component in the range 0 to 1

See also:: Particle::GetColor

MATH::CVector3 GetUVW ( ) const

Returns the parametric surface coordinates where the particle was emitted. As these are parametric coordinates, they make more sense when the emitters are NURBS curves or surfaces.

Returns:: The parametric surface coordinates on the emitter where the particle is emitted

See also:: Particle::PutUVW

CStatus PutUVW ( const MATH::CVector3 & in_vect )

Sets the parametric surface coordinates on the emitter where the particle is emitted. As these are parametric coordinates, they make more sense when the emitters are NURBS curves or surfaces.

Parameters:

in_vect Parametric surface coordinates where the particle was emitted

See also:: Particle::GetUVW

LONG GetSpriteIndex ( ) const

Returns the sprite index for the particle. The sprite index refers to a frame in the image clip associated with the particle's particle type property. You can set the image clip to be used by the particle via the particletype. The sprite index is only used when the particle type's shape type is set to sprite.

Returns:: The sprite index

See also:: ParticleCloudPrimitive::GetParticleTypes, Particle::GetTypeID, Particle::GetSpriteAngle, Particle::PutSpriteIndex

CStatus PutSpriteIndex ( LONG in_index )

Sets the sprite index of the particle.

Parameters:

in_index The frame in the image clip associated with the particle's ParticleType property

See also:: Particle::GetSpriteIndex

double GetSpriteAngle ( ) const

Returns the particle sprite angle. The sprite angle is the amount of rotation of the particle in the camera plane. The rotation is expressed in degrees and increases counter-clockwise.