Particle Class Reference
 
 
 
Particle Class Reference

#include <xsi_particle.h>


Class 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 ) ;
Inheritance diagram for Particle:
SIObject CBase

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.

Returns:
The sprite angle
See also:
Particle::PutSpriteAngle
CStatus PutSpriteAngle ( double  in_angle )

Sets the particle sprite angle.

Parameters:
in_angle Amount of rotation of the particle in the camera plane
See also:
Particle::GetSpriteAngle
double GetSize ( ) const

Returns the particle's size

Returns:
The particle size
See also:
Particle::PutSize
CStatus PutSize ( double  in_size )

Sets the particle's size

Parameters:
in_size Size of the particle
See also:
Particle::GetSize
double GetMass ( ) const

Returns the particle's mass

Returns:
The particle mass
See also:
Particle::PutMass
CStatus PutMass ( double  in_mass )

Sets the particle's mass

Parameters:
in_mass Mass controls how a particle is influenced by some forces
See also:
Particle::GetMass
double GetDensity ( ) const

Returns the particle's density

Returns:
The particle density
double GetPressure ( ) const

Returns the pressure on the particle

Returns:
The particle pressure
CRefArray GetAttributes ( ) const

Returns an array of references to the user-defined particle attributes.

Returns:
Array of references to ParticleAttribute objects.
See also:
ParticleAttribute, ParticleType::AddAttribute
Since:
4.0

The documentation for this class was generated from the following file: