# Particle Class Reference

Related Scripting Object: Particle

Represents one particle in a particle cloud. More...

`#include <xsi_particle.h>`

Inheritance diagram for Particle:

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

## Detailed Description

Represents one particle in a particle cloud.

Particles are accessible via ParticleCloudPrimitive::GetParticle.

See also:
  ParticleCloud, ParticleCloudPrimitive, X3DObject::AddParticleCloud

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 ) ;

## 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:

- xsi_particle.h