The Particle System Library

The Particle System Library is based on a Particles object. A Particles object is a homogeneous collection of particles that share the same behavior and appearance. For example, "floater" particles used to interrogate an implicit surface would be described by one Particles object, and "control particles" used to deform an implicit surface would be a second Particles object. Several Particles objects (for instance "floaters" and "control particles") can be collected together into a ParticleSystem object, whose member ParticleSystem::particles is a vector of (pointers to) Particles objects.

Each Particles object is composed of a collection of behaviors, attributes and shaders. The behaviors of a Particles object are stored in the member Particles::behaviors which is of type ParticleBehaviors, a vector of ParticleBehavior objects that ensures behaviors are performed in the proper order. The shared and per-particle data attributes are stored in the member Particles::attributes which is of type ParticleAttributes, a map of ParticleAttribute objects that makes it easy for a behavior to find attribute data by name. Finally, the appearance properties of the particles are stored in the member shaders which is of type ParticleShaders, a vector of ParticleShaders that too ensures shaders are applied in the proper order.

The classes ParticleAttribute, ParticleBehavior and ParticleShader contain some shared functionality which each inherits from the ParticleStuff class.

Behaviors

The motion of particles is represented by an ordered collection of ParticleBehavior objects. Each ParticleBehavior object represents a different component of the behavior of particles. The contribution of a ParticleBehavior object to the behavior of a particle is divided into four computational steps, computed by the four member functions:

• ParticleBehavior::applyForce() - add the behavior's force to each particle
• ParticleBehavior::applyConstraint() - remove the "illegal" component of the total force on a particle
• ParticleBehavior::integrate() - update the particles position (state) based on the constrained force
• ParticleBehavior::cleanup() - create and destroy particles based on population dynamics

This sequence of computations is applied by Particles::fullUpdate(). This computes the behavior of the Particles object by first calling applyForce() on all ParticleBehaviors (in order), then all behaviors' applyConstraint(), then all integrate() members, then all cleanup() members.

Shaders

Like behaviors, the Particles object contains an ordered collection of ParticleShader objects which are responsible for the appearance of (and user interaction with) the particles. Each subclass of ParticleShader implements appearance by redefining the ParticleShader::drawParticle() member. Each Particles object is rendered by calling ParticleShader::draw() for each of its ParticleShader objects, in order.

Attributes

Per-particle and shared data elements of a Particles object is stored in a ParticleAttribute object. These objects are accessed by name, and they typically contain member elements that compartmentalize various quantities used by the behaviors and shaders.

Behaviors and shaders can access the data held in a ParticleAttribute via the templated ParticleStuff::attachAttribute() class. The behavior/shader calls this member in its constructor with two parameters. The first is a pointer of the type of the desired ParticleAttribute that will afterward point to the attribute object. The second parameter is the name of the desired attribute, of type std::string. If attachAttribute cannot find the desired attribute in the current Particles object, it will create it.

Parameters

Following the same interface as the Implicit object, the attributes, behaviors and shaders of a Particles object have parameters accessed by the following interface:

• ParticleStuff::qlen() - returns the number of parameters
• ParticleStuff::getq(double *q) - returns the parameters in a preallocated double array q
• ParticleStuff::setq(double *q) - sets the parameters from double array q
• ParticleStuff::qname(char **qn) - returns the names of the parameters in an array preallocated with character pointers

The above parameters are uniform across all particles, e.g. the magnitude of a penalty force. There are also per-particle counterparts

• ParticleStuff::qlenpp(),
• ParticleStuff::getqpp(double *q, int i),
• ParticleStuff::setqpp(double *q, int i), and
• ParticleStuff::qnamepp(char **qn) which apply to data associated with each particle, such as for example the particle's orientation.

Construction

When attributes, behaviors and shaders are created, they need to be integrated into a Particles object. Using a constructor that accepts a pointer to the Particles object as a parameter automatically integrates the attribute/behavior/shader into the Particles object. For example

new ParticleAge(p)

will add the attribute ParticleAge to the Particles object p.

If you construct an attribute/behavior without a particle system (for example, from the factory via NEW_PARTICLESTUFF), then you need to call ParticleStuff::setParticleSystem to connect it to the particle system. If your attribute or behavior knows which particle system it references, but it is not known by that particle system, then call its ParticleStuff::addMeTo(Particles *) method.

---