ParticleAPI 3.0.0 Performant particle system API in C++ for interactive graphics

Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
PContextActions_t Class Reference

This class contains the Action API. More...

`#include <pAPIContext.h>`

Inheritance diagram for PContextActions_t:

## Public Member Functions
void | Avoid (Particle_t &m, const float magnitude, const float epsilon, const float look_ahead, const pDomain &dom)
| Steer particles away from a domain of space. More...
void | Bounce (Particle_t &m, const float friction, const float resilience, const float fric_min_vel, const pDomain &dom)
| Bounce particles off an object defined by a domain. More...
void | CopyVertexB (Particle_t &m, const bool copy_pos=true, const bool copy_vel=false)
| Set the secondary position and velocity from current. More...
void | Damping (Particle_t &m, const pVec &damping, const float min_vel=0.0f, const float max_vel=P_MAXFLOAT)
| Simulate air by dampening particle velocities. More...
void | RotDamping (Particle_t &m, const pVec &damping, const float min_vel=0.0f, const float max_vel=P_MAXFLOAT)
| Simulate air by dampening rotational velocities. More...
void | Explosion (Particle_t &m, const pVec &center, const float radius, const float magnitude, const float sigma, const float epsilon=P_EPS)
| Exert force on each particle away from explosion center. More...
void | Gravity (Particle_t &m, const pVec &dir)
| Accelerate particles in the given direction. More...
void | Jet (Particle_t &m, const pDomain &dom, const pDomain &acc)
| For particles in the domain of influence, accelerate them with a domain. More...
void | Move (Particle_t &m, const bool move_velocity=true, const bool move_rotational_velocity=true)
| Apply the particles' velocities to their positions, and age the particles. More...
void | OrbitLine (Particle_t &m, const pVec &p, const pVec &axis, const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Accelerate particles toward the closest point on the given line. More...
void | OrbitPoint (Particle_t &m, const pVec &center, const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Accelerate particles toward the given center point. More...
void | RandomAccel (Particle_t &m, const pDomain &dom)
| Accelerate particles in random directions. More...
void | RandomDisplace (Particle_t &m, const pDomain &dom)
| Immediately displace position by a random amount. More...
void | RandomVelocity (Particle_t &m, const pDomain &dom)
| Replace particle velocity with a random velocity. More...
void | RandomRotVelocity (Particle_t &m, const pDomain &dom)
| Immediately assign a random rotational velocity. More...
void | Restore (Particle_t &m, const float time, const bool vel=true, const bool rvel=true)
| Over time, restore particles to their target positionB and upB. More...
void | SpeedClamp (Particle_t &m, const float min_speed, const float max_speed)
| Clamp particle velocities to the given range. More...
void | TargetColor (Particle_t &m, const pVec &color, const float alpha, const float scale)
| Change color of all particles toward the specified color. More...
void | TargetSize (Particle_t &m, const pVec &size, const pVec &scale)
| Change sizes of all particles toward the specified size. More...
void | TargetVelocity (Particle_t &m, const pVec &vel, const float scale)
| Change velocity of all particles toward the specified velocity. More...
void | TargetRotVelocity (Particle_t &m, const pVec &rvel, const float scale)
| Change rotational velocity of all particles toward the specified rotational velocity. More...
void | Vortex (Particle_t &m, const pVec &tip, const pVec &axis, const float tightnessExponent, const float max_radius, const float inSpeed, const float upSpeed, const float aroundSpeed)
| Accelerate particles in a vortex-like way. More...
void | Follow (Particle_t &m, const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Accelerate toward the next particle in the list. More...
void | Gravitate (Particle_t &m, const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Accelerate each particle toward each other particle. More...
void | MatchVelocity (Particle_t &m, const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Modify each particle's velocity to be similar to that of its neighbors. More...
void | MatchRotVelocity (Particle_t &m, const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Modify each particle's rotational velocity to be similar to that of its neighbors. More...
void | Callback (Particle_t &m, P_PARTICLE_CALLBACK_ACTION callbackFunc, const pdata_t call_data=0)
| Call an arbitrary user-provided function on each particle in the group. More...
void | KillOld (Particle_t &m, const float age_limit, const bool kill_less_than=false)
| Get rid of older particles. More...
void | Sink (Particle_t &m, const bool kill_inside, const pDomain &kill_pos_dom)
| Kill particles that have positions on wrong side of the specified domain. More...
void | SinkVelocity (Particle_t &m, const bool kill_inside, const pDomain &kill_vel_dom)
| Kill particles that have velocities on wrong side of the specified domain. More...
void | Avoid (const float magnitude, const float epsilon, const float look_ahead, const pDomain &dom)
| Steer particles away from a domain of space. More...
void | Bounce (const float friction, const float resilience, const float fric_min_vel, const pDomain &dom)
| Bounce particles off an object defined by a domain. More...
void | CopyVertexB (const bool copy_pos=true, const bool copy_vel=false)
| Set the secondary position and velocity from current. More...
void | Damping (const pVec &damping, const float min_vel=0.0f, const float max_vel=P_MAXFLOAT)
| Simulate air by dampening particle velocities. More...
void | RotDamping (const pVec &damping, const float min_vel=0.0f, const float max_vel=P_MAXFLOAT)
| Simulate air by dampening rotational velocities. More...
void | Explosion (const pVec &center, const float radius, const float magnitude, const float sigma, const float epsilon=P_EPS)
| Exert force on each particle away from explosion center. More...
void | Gravity (const pVec &dir)
| Accelerate particles in the given direction. More...
void | Jet (const pDomain &dom, const pDomain &acc)
| For particles in the domain of influence, accelerate them with a domain. More...
void | Move (const bool move_velocity=true, const bool move_rotational_velocity=true)
| Apply the particles' velocities to their positions, and age the particles. More...
void | OrbitLine (const pVec &p, const pVec &axis, const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Accelerate particles toward the closest point on the given line. More...
void | OrbitPoint (const pVec &center, const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Accelerate particles toward the given center point. More...
void | RandomAccel (const pDomain &dom)
| Accelerate particles in random directions. More...
void | RandomDisplace (const pDomain &dom)
| Immediately displace position by a random amount. More...
void | RandomVelocity (const pDomain &dom)
| Replace particle velocity with a random velocity. More...
void | RandomRotVelocity (const pDomain &dom)
| Immediately assign a random rotational velocity. More...
void | Restore (const float time, const bool vel=true, const bool rvel=true)
| Over time, restore particles to their target positionB and upB. More...
void | SpeedClamp (const float min_speed, const float max_speed)
| Clamp particle velocities to the given range. More...
void | TargetColor (const pVec &color, const float alpha, const float scale)
| Change color of all particles toward the specified color. More...
void | TargetSize (const pVec &size, const pVec &scale)
| Change sizes of all particles toward the specified size. More...
void | TargetVelocity (const pVec &vel, const float scale)
| Change velocity of all particles toward the specified velocity. More...
void | TargetRotVelocity (const pVec &rvel, const float scale)
| Change rotational velocity of all particles toward the specified rotational velocity. More...
void | Vortex (const pVec &tip, const pVec &axis, const float tightnessExponent, const float max_radius, const float inSpeed, const float upSpeed, const float aroundSpeed)
| Accelerate particles in a vortex-like way. More...
void | Follow (const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Accelerate toward the next particle in the list. More...
void | Gravitate (const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Accelerate each particle toward each other particle. More...
void | MatchVelocity (const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Modify each particle's velocity to be similar to that of its neighbors. More...
void | MatchRotVelocity (const float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
| Modify each particle's rotational velocity to be similar to that of its neighbors. More...
void | Callback (P_PARTICLE_CALLBACK_ACTION callbackFunc, const pdata_t call_data=0)
| Call an arbitrary user-provided function on each particle in the group. More...
void | KillOld (const float age_limit, const bool kill_less_than=false)
| Get rid of older particles. More...
void | Sink (const bool kill_inside, const pDomain &kill_pos_dom)
| Kill particles that have positions on wrong side of the specified domain. More...
void | SinkVelocity (const bool kill_inside, const pDomain &kill_vel_dom)
| Kill particles that have velocities on wrong side of the specified domain. More...
void | CommitKills ()
| Delete particles tagged to be killed by inline P.I.KillOld(), P.I.Sink(), and P.I.SinkVelocity() More...
void | Sort (const pVec &eye, const pVec &look_dir, const bool front_to_back=false, const bool clamp_negative=false)
| Sort the particles by their projection onto the look vector. More...
void | Source (const float particle_rate, const pDomain &dom, const pSourceState &SrcSt)
| Add particles with positions in the specified domain. More...
void | Vertex (const pVec &v, const pSourceState &SrcSt, const pdata_t data=0)
| Add a single particle at the specified location. More...
template<class UnaryFunction >
void | ParticleLoop (UnaryFunction f)
| Loop over particles executing all actions expressed in function f More...
template<class ExPol , class UnaryFunction >
void | ParticleLoop (ExPol &&policy, UnaryFunction f)
| Loop over particles executing all actions expressed in function f using the given execution policy for CPU parallelization More...

## Protected Member Functions
void | InternalSetup (std::shared_ptr< PInternalState_t > Sr)

## Protected Attributes
PInternalShadow_t | PSh
std::shared_ptr< PInternalState_t > | PS

## Detailed Description

This class contains the Action API.

Actions modify the position, color, velocity, size, age, and other attributes of particles. All actions apply to the current particle group, as set by CurrentGroup(). Some actions will add particles to or delete them from the particle group, and others will modify the particles in other ways. Typically, a series of actions will be applied to each particle group once (or more) per rendered frame.

Remember that the amount of effect of an action call depends on the time step size, dt, as set by PAPI::PContextActionList_t::TimeStep().

Some functions have parameters with a default value of the constant P_EPS. P_EPS is a very small floating point constant that is most often used as the default value of the epsilon parameter to actions whose influence on a particle is relative to the inverse square of its distance from something. If that distance is very small, the amount of influence approaches infinity. Since all actions are computed using Euler's method, this can cause unsatisfying results in which particles are accelerated way too much. So this epsilon parameter is added to the distance before taking its inverse square, thus keeping the acceleration within reasonable limits. By varying epsilon, you specify what is reasonable. Larger epsilon make particles accelerate less.

## Inline Actions

The inline actions API calls take a Particle_t as the first argument. The actions modify this particle using a function call that will be inlined. This enables a very efficient programming model with a (normally) parallel std::for_each loop around a per-particle list of actions. It also enables the inline actions functions to be called from CUDA, HIP, or other threads, allowing GPU acceleration.

The inline actions are called only from within a call to ParticleLoop(). For example:

P.ParticleLoop(std::execution::par_unseq, [&](Particle_t& p_) {
P.Gravity(p_, Efx.GravityVec);
P.Bounce(p_, 0.f, 0.5f, 0.f, PDDisc(pVec(0, 0, 1.f), pVec(0, 0, 1.f), 5));
P.Move(p_, true, false);
P.Sink(p_, false, PDPlane(pVec(0, 0, -3), pVec(0, 0, 1)));
P.SinkVelocity(p_, true, PDSphere(pVec(0, 0, 0), 0.01));
});
P.CommitKills();

## Legacy Actions

The legacy, less performant, but perhaps more elegant Action API is still available. Other than not taking a Particle_t as the first parameter, the call signatures of the legacy API match those of the inline API.

## Member Function Documentation

## ◆ Avoid() [1/2]

void Avoid | ( | const float | magnitude,
|  | const float | epsilon,
|  | const float | look_ahead,
|  | const pDomain & | dom
| ) |  |

Steer particles away from a domain of space.

Particles are tested to see whether they will pass from being outside the specified domain to being inside it within look_ahead time units from now if the next Move() action were to occur now. The specific direction and amount of turn is dependent on the kind of domain being avoided.

At present the only domains for which Avoid() is implemented are PDSphere, PDRectangle, PDTriangle, PDDisc and PDPlane.

Parameters

  magnitude | how drastically the particle velocities are modified to avoid the obstacle at each time step.
  epsilon | added to distance to dampen acceleration
  look_ahead | how far forward along the velocity vector to look for the obstacle
  dom | the space to avoid

## ◆ Avoid() [2/2]

void Avoid | ( | Particle_t & | m,
|  | const float | magnitude,
|  | const float | epsilon,
|  | const float | look_ahead,
|  | const pDomain & | dom
| ) |  |
| inline

Steer particles away from a domain of space.

Particles are tested to see whether they will pass from being outside the specified domain to being inside it within look_ahead time units from now if the next Move() action were to occur now. The specific direction and amount of turn is dependent on the kind of domain being avoided.

At present the only domains for which Avoid() is implemented are PDSphere, PDRectangle, PDTriangle, PDDisc and PDPlane.

Parameters

  magnitude | how drastically the particle velocities are modified to avoid the obstacle at each time step.
  epsilon | added to distance to dampen acceleration
  look_ahead | how far forward along the velocity vector to look for the obstacle
  dom | the space to avoid

## ◆ Bounce() [1/2]

void Bounce | ( | const float | friction,
|  | const float | resilience,
|  | const float | fric_min_vel,
|  | const pDomain & | dom
| ) |  |

Bounce particles off an object defined by a domain.

Particles are tested to see whether they will pass from being outside the specified domain to being inside it if the next Move() action were to occur now. If they would pass through the surface of the domain, they are instead bounced off it. That is, their velocity vector is decomposed into components normal to the surface and tangent to the surface. The direction of the normal component is reversed, and friction, resilience and fric_min_vel are applied to the components. They are then recomposed into a new velocity heading away from the surface.

Since particles are tested to see whether they would pass through the domain if Move() were called now, it is best to have Bounce() be the last action that modifies a particle's velocity before calling Move(). Also, actions such as RandomDisplace() that modify a particle's position directly, rather than modifying its velocity vector, may yield unsatisfying results when used with Bounce().

At present Bounce() is not implemented for all domains. Feel free to implement others. For spheres, the particle bounces off either the inside or the outside of the sphere. For planes, triangles and discs, the particles bounce off either side of the surface. For rectangles, particles bounce off either side of the diamond-shaped patch whose corners are o, o+u, o+u+v, and o+v. See the documentation on domains for further explanation.

Bounce() doesn't work correctly with small time step sizes for particles sliding along a surface, despite fric_min_vel. The friction and resilience parameters should not be scaled by dt, since a bounce happens instantaneously. On the other hand, they should be scaled by dt because particles sliding along a surface will hit more often if dt is smaller. Adjust these parameters manually when you change dt.

Parameters

  friction | tangential component of the outgoing velocity vector is scaled by (1 - friction)
  resilience | normal component of the outgoing velocity vector is scaled by resilience
  fric_min_vel | only apply friction if tangential velocity is greater than fric_min_vel so particles can glide smoothly
  dom | bounce off the surface of this domain

## ◆ Bounce() [2/2]

void Bounce | ( | Particle_t & | m,
|  | const float | friction,
|  | const float | resilience,
|  | const float | fric_min_vel,
|  | const pDomain & | dom
| ) |  |
| inline

Bounce particles off an object defined by a domain.

Particles are tested to see whether they will pass from being outside the specified domain to being inside it if the next Move() action were to occur now. If they would pass through the surface of the domain, they are instead bounced off it. That is, their velocity vector is decomposed into components normal to the surface and tangent to the surface. The direction of the normal component is reversed, and friction, resilience and fric_min_vel are applied to the components. They are then recomposed into a new velocity heading away from the surface.

Since particles are tested to see whether they would pass through the domain if Move() were called now, it is best to have Bounce() be the last action that modifies a particle's velocity before calling Move(). Also, actions such as RandomDisplace() that modify a particle's position directly, rather than modifying its velocity vector, may yield unsatisfying results when used with Bounce().

At present Bounce() is not implemented for all domains. Feel free to implement others. For spheres, the particle bounces off either the inside or the outside of the sphere. For planes, triangles and discs, the particles bounce off either side of the surface. For rectangles, particles bounce off either side of the diamond-shaped patch whose corners are o, o+u, o+u+v, and o+v. See the documentation on domains for further explanation.

Bounce() doesn't work correctly with small time step sizes for particles sliding along a surface, despite fric_min_vel. The friction and resilience parameters should not be scaled by dt, since a bounce happens instantaneously. On the other hand, they should be scaled by dt because particles sliding along a surface will hit more often if dt is smaller. Adjust these parameters manually when you change dt.

Parameters

  friction | tangential component of the outgoing velocity vector is scaled by (1 - friction)
  resilience | normal component of the outgoing velocity vector is scaled by resilience
  fric_min_vel | only apply friction if tangential velocity is greater than fric_min_vel so particles can glide smoothly
  dom | bounce off the surface of this domain

## ◆ Callback() [1/2]

void Callback | ( | P_PARTICLE_CALLBACK_ACTION | callbackFunc,
|  | const pdata_t | call_data = `0`
| ) |  |

Call an arbitrary user-provided function on each particle in the group.

The function will receive both your call data and the full Particle_t struct, which contains per-particle user data.

Parameters

  callbackFunc | Pointer to function of yours to call.
  call_data | Arbitrary data of yours to pass into your function

## ◆ Callback() [2/2]

void Callback | ( | Particle_t & | m,
|  | P_PARTICLE_CALLBACK_ACTION | callbackFunc,
|  | const pdata_t | call_data = `0`
| ) |  |
| inline

Call an arbitrary user-provided function on each particle in the group.

The function will receive both your call data and the full Particle_t struct, which contains per-particle user data.

Parameters

  callbackFunc | Pointer to function of yours to call.
  call_data | Arbitrary data of yours to pass into your function

## ◆ CommitKills()

void CommitKills | ( |  | ) |

Delete particles tagged to be killed by inline P.I.KillOld(), P.I.Sink(), and P.I.SinkVelocity()

## ◆ CopyVertexB() [1/2]

void CopyVertexB | ( | const bool | copy_pos = `true`,
|  | const bool | copy_vel = `false`
| ) |  |

Set the secondary position and velocity from current.

Parameters

  copy_pos | If true, sets particle's PositionB to the current position of that particle. This makes each particle remember this position so it can later return to it using the Restore() action.
  copy_vel | If true, sets particle's velocityB to the current velocity of that particle. Compute particle orientation by copying velocity before other actions. Then velocity X velocityB yields a tangent vector.

## ◆ CopyVertexB() [2/2]

void CopyVertexB | ( | Particle_t & | m,
|  | const bool | copy_pos = `true`,
|  | const bool | copy_vel = `false`
| ) |  |
| inline

Set the secondary position and velocity from current.

Parameters

  copy_pos | If true, sets particle's PositionB to the current position of that particle. This makes each particle remember this position so it can later return to it using the Restore() action.
  copy_vel | If true, sets particle's velocityB to the current velocity of that particle. Compute particle orientation by copying velocity before other actions. Then velocity X velocityB yields a tangent vector.

## ◆ Damping() [1/2]

void Damping | ( | const pVec & | damping,
|  | const float | min_vel = `0.0f`,
|  | const float | max_vel = `P_MAXFLOAT`
| ) |  |

Simulate air by dampening particle velocities.

If a particle's velocity magnitude is within min_vel and max_vel, then multiply each component of the velocity by the respective damping constant. Typically, the three components of damping will have the same value.

There are no bounds on the damping constants. Thus, by giving values greater than 1.0 they may be used to speed up particles instead of slow them down.

Parameters

  damping | component-wise multiply this vector by the velocity vector
  min_vel | only dampen if velocity magnitude is greater than min_vel
  max_vel | only dampen if velocity magnitude is less than max_vel

## ◆ Damping() [2/2]

void Damping | ( | Particle_t & | m,
|  | const pVec & | damping,
|  | const float | min_vel = `0.0f`,
|  | const float | max_vel = `P_MAXFLOAT`
| ) |  |
| inline

Simulate air by dampening particle velocities.

If a particle's velocity magnitude is within min_vel and max_vel, then multiply each component of the velocity by the respective damping constant. Typically, the three components of damping will have the same value.

There are no bounds on the damping constants. Thus, by giving values greater than 1.0 they may be used to speed up particles instead of slow them down.

Parameters

  damping | component-wise multiply this vector by the velocity vector
  min_vel | only dampen if velocity magnitude is greater than min_vel
  max_vel | only dampen if velocity magnitude is less than max_vel

## ◆ Explosion() [1/2]

void Explosion | ( | const pVec & | center,
|  | const float | radius,
|  | const float | magnitude,
|  | const float | sigma,
|  | const float | epsilon = `P_EPS`
| ) |  |

Exert force on each particle away from explosion center.

Causes an explosion by accelerating all particles away from the center. Particles are accelerated away from the center by an amount proportional to magnitude. The shock wave of the explosion has a gaussian magnitude. The peak of the wave front travels spherically outward from the center at the specified velocity. So at a given time step, particles at a distance (velocity * age) from center will receive the most acceleration, and particles not at the peak of the shock wave will receive a lesser outward acceleration.

radius is the current radius of the explosion wave's peak. It is up to the application to increment the radius for each call to Explosion(). For Explosion() calls in action lists, this means you will need to recreate the action list each time step.

You can set up a standing wave by not incrementing the radius.

Parameters

  center | center point of shock wave
  radius | current radius of wave peak
  magnitude | scales the acceleration applied to particles
  sigma | standard deviation of the gaussian; the sharpness or broadness of the strength of the wave.
  epsilon | added to distance to dampen acceleration

## ◆ Explosion() [2/2]

void Explosion | ( | Particle_t & | m,
|  | const pVec & | center,
|  | const float | radius,
|  | const float | magnitude,
|  | const float | sigma,
|  | const float | epsilon = `P_EPS`
| ) |  |
| inline

Exert force on each particle away from explosion center.

Causes an explosion by accelerating all particles away from the center. Particles are accelerated away from the center by an amount proportional to magnitude. The shock wave of the explosion has a gaussian magnitude. The peak of the wave front travels spherically outward from the center at the specified velocity. So at a given time step, particles at a distance (velocity * age) from center will receive the most acceleration, and particles not at the peak of the shock wave will receive a lesser outward acceleration.

radius is the current radius of the explosion wave's peak. It is up to the application to increment the radius for each call to Explosion(). For Explosion() calls in action lists, this means you will need to recreate the action list each time step.

You can set up a standing wave by not incrementing the radius.

Parameters

  center | center point of shock wave
  radius | current radius of wave peak
  magnitude | scales the acceleration applied to particles
  sigma | standard deviation of the gaussian; the sharpness or broadness of the strength of the wave.
  epsilon | added to distance to dampen acceleration

## ◆ Follow() [1/2]

void Follow | ( | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |

Accelerate toward the next particle in the list.

This allows snaky effects where the particles follow each other. Each particle is accelerated toward the next particle in the group. The Follow() action does not affect the last particle in the group. This allows controlled effects where the last particle in the group is killed after each time step and replaced by a new particle at a slightly different position. See KillOld() to learn how to kill the last particle in the group after each step.

Parameters

  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from its predecessor is affected

## ◆ Follow() [2/2]

void Follow | ( | Particle_t & | m,
|  | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |
| inline

Accelerate toward the next particle in the list.

This allows snaky effects where the particles follow each other. Each particle is accelerated toward the next particle in the group. The Follow() action does not affect the last particle in the group. This allows controlled effects where the last particle in the group is killed after each time step and replaced by a new particle at a slightly different position. See KillOld() to learn how to kill the last particle in the group after each step.

Parameters

  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from its predecessor is affected

## ◆ Gravitate() [1/2]

void Gravitate | ( | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |

Accelerate each particle toward each other particle.

Each particle is accelerated toward each other particle. This action is more computationally intensive than the others are because each particle is affected by each other particle.

Parameters

  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from another particle is affected

## ◆ Gravitate() [2/2]

void Gravitate | ( | Particle_t & | m,
|  | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |
| inline

Accelerate each particle toward each other particle.

Each particle is accelerated toward each other particle. This action is more computationally intensive than the others are because each particle is affected by each other particle.

Parameters

  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from another particle is affected

## ◆ Gravity() [1/2]

void Gravity | ( | const pVec & | dir | ) |

Accelerate particles in the given direction.

The gravity acceleration vector is simply added to the velocity vector of each particle at each time step. The magnitude of the gravity vector is the acceleration due to gravity.

Parameters

  dir | acceleration vector

## ◆ Gravity() [2/2]

void Gravity | ( | Particle_t & | m,
|  | const pVec & | dir
| ) |  |
| inline

Accelerate particles in the given direction.

The gravity acceleration vector is simply added to the velocity vector of each particle at each time step. The magnitude of the gravity vector is the acceleration due to gravity.

Parameters

  dir | acceleration vector

## ◆ InternalSetup()

void InternalSetup | ( | std::shared_ptr< PInternalState_t > | Sr | ) |
| protected

## ◆ Jet() [1/2]

void Jet | ( | const pDomain & | dom,
|  | const pDomain & | acc
| ) |  |

For particles in the domain of influence, accelerate them with a domain.

For each particle within the jet's domain of influence, dom, Jet() chooses an acceleration vector from the domain acc and applies it to the particle's velocity.

Parameters

  dom | apply jet to particles in this domain
  acc | acceleration vector comes from this domain

## ◆ Jet() [2/2]

void Jet | ( | Particle_t & | m,
|  | const pDomain & | dom,
|  | const pDomain & | acc
| ) |  |
| inline

For particles in the domain of influence, accelerate them with a domain.

For each particle within the jet's domain of influence, dom, Jet() chooses an acceleration vector from the domain acc and applies it to the particle's velocity.

Parameters

  dom | apply jet to particles in this domain
  acc | acceleration vector comes from this domain

## ◆ KillOld() [1/2]

void KillOld | ( | const float | age_limit,
|  | const bool | kill_less_than = `false`
| ) |  |

Get rid of older particles.

Removes all particles older than age_limit. But if kill_less_than is true, it instead removes all particles newer than age_limit. age_limit is not clamped, so negative values are ok. This can be used in conjunction with StartingAge(-n) to create and then kill a particular set of particles.

In order to kill a particular particle, set StartingAge() to a number that will never be a typical age for any other particle in the group, for example -1.0. Then emit the particle using Source() or Vertex(). Then do the rest of the particle actions and finally call KillOld(-0.9, true) to kill the special particle because it is the only one with an age less than -0.9.

Parameters

  age_limit | max age of particles
  kill_less_than | true to kill particles younger than age_limit instead of older

## ◆ KillOld() [2/2]

void KillOld | ( | Particle_t & | m,
|  | const float | age_limit,
|  | const bool | kill_less_than = `false`
| ) |  |
| inline

Get rid of older particles.

Removes all particles older than age_limit. But if kill_less_than is true, it instead removes all particles newer than age_limit. age_limit is not clamped, so negative values are ok. This can be used in conjunction with StartingAge(-n) to create and then kill a particular set of particles.

In order to kill a particular particle, set StartingAge() to a number that will never be a typical age for any other particle in the group, for example -1.0. Then emit the particle using Source() or Vertex(). Then do the rest of the particle actions and finally call KillOld(-0.9, true) to kill the special particle because it is the only one with an age less than -0.9.

Parameters

  age_limit | max age of particles
  kill_less_than | true to kill particles younger than age_limit instead of older

## ◆ MatchRotVelocity() [1/2]

void MatchRotVelocity | ( | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |

Modify each particle's rotational velocity to be similar to that of its neighbors.

Each particle is accelerated toward the weighted mean of the rotational velocities of the other particles in the group.

Using an epsilon similar in size to magnitude can increase the range of influence of nearby particles on this particle.

Parameters

  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from another particle is affected

## ◆ MatchRotVelocity() [2/2]

void MatchRotVelocity | ( | Particle_t & | m,
|  | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |
| inline

Modify each particle's rotational velocity to be similar to that of its neighbors.

Each particle is accelerated toward the weighted mean of the rotational velocities of the other particles in the group.

Using an epsilon similar in size to magnitude can increase the range of influence of nearby particles on this particle.

Parameters

  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from another particle is affected

## ◆ MatchVelocity() [1/2]

void MatchVelocity | ( | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |

Modify each particle's velocity to be similar to that of its neighbors.

Each particle is accelerated toward the weighted mean of the velocities of the other particles in the group.

Using an epsilon similar in size to magnitude can increase the range of influence of nearby particles on this particle.

Parameters

  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from another particle is affected

## ◆ MatchVelocity() [2/2]

void MatchVelocity | ( | Particle_t & | m,
|  | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |
| inline

Modify each particle's velocity to be similar to that of its neighbors.

Each particle is accelerated toward the weighted mean of the velocities of the other particles in the group.

Using an epsilon similar in size to magnitude can increase the range of influence of nearby particles on this particle.

Parameters

  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from another particle is affected

## ◆ Move() [1/2]

void Move | ( | const bool | move_velocity = `true`,
|  | const bool | move_rotational_velocity = `true`
| ) |  |

Apply the particles' velocities to their positions, and age the particles.

This action actually updates the particle positions by adding the current velocity to the current position and the current rotational velocity to the current up vector. This is typically the last particle action performed in an iteration of a particle simulation, and typically only occurs once per iteration.

The velocity is multiplied by the time step length, dt, before being added to the position. This implements Euler's method of numerical integration with a constant but specifiable step size. See TimeStep() for more on varying the time step size.

Parameters

  move_velocity | apply velocity to position.
  move_rotational_velocity | apply rotational velocity to Up vector. This is an optimization.

## ◆ Move() [2/2]

void Move | ( | Particle_t & | m,
|  | const bool | move_velocity = `true`,
|  | const bool | move_rotational_velocity = `true`
| ) |  |
| inline

Apply the particles' velocities to their positions, and age the particles.

This action actually updates the particle positions by adding the current velocity to the current position and the current rotational velocity to the current up vector. This is typically the last particle action performed in an iteration of a particle simulation, and typically only occurs once per iteration.

The velocity is multiplied by the time step length, dt, before being added to the position. This implements Euler's method of numerical integration with a constant but specifiable step size. See TimeStep() for more on varying the time step size.

Parameters

  move_velocity | apply velocity to position.
  move_rotational_velocity | apply rotational velocity to Up vector. This is an optimization.

## ◆ OrbitLine() [1/2]

void OrbitLine | ( | const pVec & | p,
|  | const pVec & | axis,
|  | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |

Accelerate particles toward the closest point on the given line.

For each particle, this action computes the vector to the closest point on the line, and accelerates the particle in that direction.

Parameters

  p | a point on the line
  axis | any vector parallel to the line
  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from the line is affected

## ◆ OrbitLine() [2/2]

void OrbitLine | ( | Particle_t & | m,
|  | const pVec & | p,
|  | const pVec & | axis,
|  | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |
| inline

Accelerate particles toward the closest point on the given line.

For each particle, this action computes the vector to the closest point on the line, and accelerates the particle in that direction.

Parameters

  p | a point on the line
  axis | any vector parallel to the line
  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from the line is affected

## ◆ OrbitPoint() [1/2]

void OrbitPoint | ( | const pVec & | center,
|  | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |

Accelerate particles toward the given center point.

For each particle, this action computes the vector to the center point, and accelerates the particle in the vector direction.

Parameters

  center | accelerate toward this point
  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from the center is affected

## ◆ OrbitPoint() [2/2]

void OrbitPoint | ( | Particle_t & | m,
|  | const pVec & | center,
|  | const float | magnitude = `1.0f`,
|  | const float | epsilon = `P_EPS`,
|  | const float | max_radius = `P_MAXFLOAT`
| ) |  |
| inline

Accelerate particles toward the given center point.

For each particle, this action computes the vector to the center point, and accelerates the particle in the vector direction.

Parameters

  center | accelerate toward this point
  magnitude | scales each particle's acceleration
  epsilon | added to distance to dampen acceleration
  max_radius | no particle further than max_radius from the center is affected

## ◆ ParticleLoop() [1/2]

void ParticleLoop | ( | ExPol && | policy,
|  | UnaryFunction | f
| ) |  |
| inline

Loop over particles executing all actions expressed in function f using the given execution policy for CPU parallelization

Template Parameters

  UnaryFunction |

Parameters

  f | a lambda function expressing all operations to be performed on each particle
  policy | execution policy to be used for parallelization, for example std::execution::par_unseq

## ◆ ParticleLoop() [2/2]

void ParticleLoop | ( | UnaryFunction | f | ) |
| inline

Loop over particles executing all actions expressed in function f

Template Parameters

  UnaryFunction |

Parameters

  f | a lambda function expressing all operations to be performed on each particle

## ◆ RandomAccel() [1/2]

void RandomAccel | ( | const pDomain & | dom | ) |

Accelerate particles in random directions.

For each particle, chooses an acceleration vector from the specified domain and adds it to the particle's velocity. Reducing the time step, dt, will make a higher probability of being near the original velocity after unit time. Smaller dt approach a normal distribution of velocity vectors instead of a square wave distribution.

Parameters

  dom | choose acceleration from this domain

## ◆ RandomAccel() [2/2]

void RandomAccel | ( | Particle_t & | m,
|  | const pDomain & | dom
| ) |  |
| inline

Accelerate particles in random directions.

For each particle, chooses an acceleration vector from the specified domain and adds it to the particle's velocity. Reducing the time step, dt, will make a higher probability of being near the original velocity after unit time. Smaller dt approach a normal distribution of velocity vectors instead of a square wave distribution.

Parameters

  dom | choose acceleration from this domain

## ◆ RandomDisplace() [1/2]

void RandomDisplace | ( | const pDomain & | dom | ) |

Immediately displace position by a random amount.

Chooses a displacement vector from the specified domain and adds it to the particle's position. Reducing the time step, dt, will make a higher probability of being near the original position after unit time. Smaller dt approach a normal distribution of particle positions instead of a square wave distribution.

Since this action changes particle positions, rather than changing their velocities and depending on the Move() action to change the positions, unsatisfying results may occur when used with the Avoid() or Bounce() actions. In particular, particles may be displaced to the opposite side of the surface without bouncing off it.

Parameters

  dom | choose position offset from this domain

## ◆ RandomDisplace() [2/2]

void RandomDisplace | ( | Particle_t & | m,
|  | const pDomain & | dom
| ) |  |
| inline

Immediately displace position by a random amount.

Chooses a displacement vector from the specified domain and adds it to the particle's position. Reducing the time step, dt, will make a higher probability of being near the original position after unit time. Smaller dt approach a normal distribution of particle positions instead of a square wave distribution.

Since this action changes particle positions, rather than changing their velocities and depending on the Move() action to change the positions, unsatisfying results may occur when used with the Avoid() or Bounce() actions. In particular, particles may be displaced to the opposite side of the surface without bouncing off it.

Parameters

  dom | choose position offset from this domain

## ◆ RandomRotVelocity() [1/2]

void RandomRotVelocity | ( | const pDomain & | dom | ) |

Immediately assign a random rotational velocity.

Sets each particle's rotational velocity vector to a random vector in the specified domain. This function is not affected by dt.

Parameters

  dom | choose rotational velocity from this domain

## ◆ RandomRotVelocity() [2/2]

void RandomRotVelocity | ( | Particle_t & | m,
|  | const pDomain & | dom
| ) |  |
| inline

Immediately assign a random rotational velocity.

Sets each particle's rotational velocity vector to a random vector in the specified domain. This function is not affected by dt.

Parameters

  dom | choose rotational velocity from this domain

## ◆ RandomVelocity() [1/2]

void RandomVelocity | ( | const pDomain & | dom | ) |

Replace particle velocity with a random velocity.

Sets each particle's velocity vector to a random vector in the specified domain. This function is not affected by dt.

Parameters

  dom | choose velocity from this domain

## ◆ RandomVelocity() [2/2]

void RandomVelocity | ( | Particle_t & | m,
|  | const pDomain & | dom
| ) |  |
| inline

Replace particle velocity with a random velocity.

Sets each particle's velocity vector to a random vector in the specified domain. This function is not affected by dt.

Parameters

  dom | choose velocity from this domain

## ◆ Restore() [1/2]

void Restore | ( | const float | time,
|  | const bool | vel = `true`,
|  | const bool | rvel = `true`
| ) |  |

Over time, restore particles to their target positionB and upB.

If vel is true, computes a new velocity for each particle that will make the particle arrive at its positionB at the specified amount of time in the future. If rvel is true, computes a new rotational velocity that moves up toward upB.

The curved path that the particles take is a parametric quadratic. Once the specified amount of time has passed, Restore() instead sets position and Up to equal positionB and upB and sets velocity and rotational velocity to 0 to freeze them in place.

It is the application's responsibility to decrease time_left by dt on each call. When in an action list, this means you need to recreate the action list each time step.

The positionB attribute of each particle is typically the particle's position when it was created, or it can be specified within a domain. This is controlled by VertexBTracks(), and VertexB(). The positionB can be set at any time to the particle's current position using the CopyVertexB() action.

Restore(0) is the opposite of CopyVertexB(); it sets each particle's position to be equal to its positionB. However, this has the side effect of setting each particle's velocity to 0.

Parameters

  time | how long more until particles should arrive at target position and orientation
  vel | restore positions
  rvel | restore up vectors

## ◆ Restore() [2/2]

void Restore | ( | Particle_t & | m,
|  | const float | time,
|  | const bool | vel = `true`,
|  | const bool | rvel = `true`
| ) |  |
| inline

Over time, restore particles to their target positionB and upB.

If vel is true, computes a new velocity for each particle that will make the particle arrive at its positionB at the specified amount of time in the future. If rvel is true, computes a new rotational velocity that moves up toward upB.

The curved path that the particles take is a parametric quadratic. Once the specified amount of time has passed, Restore() instead sets position and Up to equal positionB and upB and sets velocity and rotational velocity to 0 to freeze them in place.

It is the application's responsibility to decrease time_left by dt on each call. When in an action list, this means you need to recreate the action list each time step.

The positionB attribute of each particle is typically the particle's position when it was created, or it can be specified within a domain. This is controlled by VertexBTracks(), and VertexB(). The positionB can be set at any time to the particle's current position using the CopyVertexB() action.

Restore(0) is the opposite of CopyVertexB(); it sets each particle's position to be equal to its positionB. However, this has the side effect of setting each particle's velocity to 0.

Parameters

  time | how long more until particles should arrive at target position and orientation
  vel | restore positions
  rvel | restore up vectors

## ◆ RotDamping() [1/2]

void RotDamping | ( | const pVec & | damping,
|  | const float | min_vel = `0.0f`,
|  | const float | max_vel = `P_MAXFLOAT`
| ) |  |

Simulate air by dampening rotational velocities.

If a particle's rotational velocity magnitude is within min_vel and max_vel, then multiply each component of the rotational velocity by the respective damping constant. Typically, the three components of damping will have the same value.

There are no bounds on the damping constants. Thus, by giving values greater than 1.0 they may be used to speed up particles instead of slow them down.

Parameters

  damping | component-wise multiply this vector by the rotational velocity vector
  min_vel | only dampen if velocity magnitude is greater than min_vel
  max_vel | only dampen if velocity magnitude is less than max_vel

## ◆ RotDamping() [2/2]

void RotDamping | ( | Particle_t & | m,
|  | const pVec & | damping,
|  | const float | min_vel = `0.0f`,
|  | const float | max_vel = `P_MAXFLOAT`
| ) |  |
| inline

Simulate air by dampening rotational velocities.

If a particle's rotational velocity magnitude is within min_vel and max_vel, then multiply each component of the rotational velocity by the respective damping constant. Typically, the three components of damping will have the same value.

There are no bounds on the damping constants. Thus, by giving values greater than 1.0 they may be used to speed up particles instead of slow them down.

Parameters

  damping | component-wise multiply this vector by the rotational velocity vector
  min_vel | only dampen if velocity magnitude is greater than min_vel
  max_vel | only dampen if velocity magnitude is less than max_vel

## ◆ Sink() [1/2]

void Sink | ( | const bool | kill_inside,
|  | const pDomain & | kill_pos_dom
| ) |  |

Kill particles that have positions on wrong side of the specified domain.

If kill_inside is true, deletes all particles inside the given domain. If kill_inside is false, deletes all particles outside the given domain.

Parameters

  kill_inside | true to kill particles inside the domain
  kill_pos_dom | kill particles in this domain

## ◆ Sink() [2/2]

void Sink | ( | Particle_t & | m,
|  | const bool | kill_inside,
|  | const pDomain & | kill_pos_dom
| ) |  |
| inline

Kill particles that have positions on wrong side of the specified domain.

If kill_inside is true, deletes all particles inside the given domain. If kill_inside is false, deletes all particles outside the given domain.

Parameters

  kill_inside | true to kill particles inside the domain
  kill_pos_dom | kill particles in this domain

## ◆ SinkVelocity() [1/2]

void SinkVelocity | ( | const bool | kill_inside,
|  | const pDomain & | kill_vel_dom
| ) |  |

Kill particles that have velocities on wrong side of the specified domain.

If kill_inside is true, deletes all particles whose velocity vectors are inside the given domain. If kill_inside is false, deletes all particles whose velocity vectors are outside the given domain. This allows particles to die when they turn around, get too fast or too slow, etc. For example, use a sphere domain centered at the origin with a radius equal to the minimum velocity to kill particles that are too slow.

Parameters

  kill_inside | true to kill particles with velocities inside the domain
  kill_vel_dom | kill particles with velocities in this domain

## ◆ SinkVelocity() [2/2]

void SinkVelocity | ( | Particle_t & | m,
|  | const bool | kill_inside,
|  | const pDomain & | kill_vel_dom
| ) |  |
| inline

Kill particles that have velocities on wrong side of the specified domain.

If kill_inside is true, deletes all particles whose velocity vectors are inside the given domain. If kill_inside is false, deletes all particles whose velocity vectors are outside the given domain. This allows particles to die when they turn around, get too fast or too slow, etc. For example, use a sphere domain centered at the origin with a radius equal to the minimum velocity to kill particles that are too slow.

Parameters

  kill_inside | true to kill particles with velocities inside the domain
  kill_vel_dom | kill particles with velocities in this domain

## ◆ Sort()

void Sort | ( | const pVec & | eye,
|  | const pVec & | look_dir,
|  | const bool | front_to_back = `false`,
|  | const bool | clamp_negative = `false`
| ) |  |

Sort the particles by their projection onto the look vector.

Many rendering systems require rendering transparent particles in back-to-front order. The ordering is defined by the eye point and the look vector. These are the same vectors you pass into gluLookAt(), for example. The vector from the eye point to each particle's position is computed, then projected onto the look vector. Particles are sorted back-to-front by the result of this dot product. Setting clamp_negative to true speeds up sorting time. Particles behind the viewer won't be visible so their relative order doesn't matter.

Parameters

  eye | eye point is a point on the line the particles project onto
  look_dir | direction vector of projection line; does not need to be normalized
  front_to_back | true to sort in front-to-back order instead of back-to-front
  clamp_negative | true to set negative dot product values to zero before sorting

## ◆ Source()

void Source | ( | const float | particle_rate,
|  | const pDomain & | dom,
|  | const pSourceState & | SrcSt
| ) |  |

Add particles with positions in the specified domain.

Adds new particles to the current particle group. The particle positions are chosen from the given domain. All the other particle attributes such as color and velocity are chosen according to their current domains.

When the Source action is called within an action list, the particle attribute domains used are those that were current when the Source command was called within the NewActionList() / EndActionList() block instead of when CallActionList() was called. Note that this is unlike OpenGL display lists.

If particle_rate / dt is not an integer then Source() adjusts the number of particles to add during this time step so that the average number added per unit time is particle_rate.

If too few particles seem to be added each frame, it is probably because the particle group is already full. If this is bad, you can grow the group using SetMaxParticles().

Parameters

  particle_rate | how many particles to add per unit time
  dom | particle positions are chosen from this domain
  SrcSt | all other particle attributes are chosen from this source state

## ◆ SpeedClamp() [1/2]

void SpeedClamp | ( | const float | min_speed,
|  | const float | max_speed
| ) |  |

Clamp particle velocities to the given range.

Computes each particle's speed (the magnitude of its velocity vector) and if it is less than min_speed or greater than max_speed the velocity is scaled to within those bounds, while preserving the velocity vector's direction.

The vector [0,0,0] is an exception because it has no direction. Such vectors are not modified by SpeedClamp().

Parameters

  min_speed | set velocity vectors below min_speed to min_speed
  max_speed | set velocity vectors above max_speed to max_speed

## ◆ SpeedClamp() [2/2]

void SpeedClamp | ( | Particle_t & | m,
|  | const float | min_speed,
|  | const float | max_speed
| ) |  |
| inline

Clamp particle velocities to the given range.

Computes each particle's speed (the magnitude of its velocity vector) and if it is less than min_speed or greater than max_speed the velocity is scaled to within those bounds, while preserving the velocity vector's direction.

The vector [0,0,0] is an exception because it has no direction. Such vectors are not modified by SpeedClamp().

Parameters

  min_speed | set velocity vectors below min_speed to min_speed
  max_speed | set velocity vectors above max_speed to max_speed

## ◆ TargetColor() [1/2]

void TargetColor | ( | const pVec & | color,
|  | const float | alpha,
|  | const float | scale
| ) |  |

Change color of all particles toward the specified color.

Modifies the color and alpha of each particle to be scale percent of the way closer to the specified color and alpha. scale is multiplied by dt before scaling the sizes. Thus, using smaller dt causes a slightly faster approach to the target color.

This action makes all colors tend toward the specified, uniform color. The value of scale will usually be very small (less than 0.01) to yield a gradual transition.

Parameters

  color | target color
  alpha | target alpha value
  scale | what percent of the way from the current color to the target color to transition in unit time

## ◆ TargetColor() [2/2]

void TargetColor | ( | Particle_t & | m,
|  | const pVec & | color,
|  | const float | alpha,
|  | const float | scale
| ) |  |
| inline

Change color of all particles toward the specified color.

Modifies the color and alpha of each particle to be scale percent of the way closer to the specified color and alpha. scale is multiplied by dt before scaling the sizes. Thus, using smaller dt causes a slightly faster approach to the target color.

This action makes all colors tend toward the specified, uniform color. The value of scale will usually be very small (less than 0.01) to yield a gradual transition.

Parameters

  color | target color
  alpha | target alpha value
  scale | what percent of the way from the current color to the target color to transition in unit time

## ◆ TargetRotVelocity() [1/2]

void TargetRotVelocity | ( | const pVec & | rvel,
|  | const float | scale
| ) |  |

Change rotational velocity of all particles toward the specified rotational velocity.

Modifies the rotational velocity of each particle to be scale percent of the way closer to the specified rotational velocity. This makes rotational velocities grow asymptotically closer to the given rotational velocity. scale is multiplied by dt before scaling the velocities. Thus, using smaller dt causes a slightly faster approach to the target rotational velocity.

This action makes all rotational velocities tend toward the specified, uniform rotational velocity. The value of scale will usually be very small (less than 0.01) to yield a gradual transition.

Parameters

  rvel | rotational velocity
  scale | percent of the way from the current to the target rotational velocity to transition in unit time

## ◆ TargetRotVelocity() [2/2]

void TargetRotVelocity | ( | Particle_t & | m,
|  | const pVec & | rvel,
|  | const float | scale
| ) |  |
| inline

Change rotational velocity of all particles toward the specified rotational velocity.

Modifies the rotational velocity of each particle to be scale percent of the way closer to the specified rotational velocity. This makes rotational velocities grow asymptotically closer to the given rotational velocity. scale is multiplied by dt before scaling the velocities. Thus, using smaller dt causes a slightly faster approach to the target rotational velocity.

This action makes all rotational velocities tend toward the specified, uniform rotational velocity. The value of scale will usually be very small (less than 0.01) to yield a gradual transition.

Parameters

  rvel | rotational velocity
  scale | percent of the way from the current to the target rotational velocity to transition in unit time

## ◆ TargetSize() [1/2]

void TargetSize | ( | const pVec & | size,
|  | const pVec & | scale
| ) |  |

Change sizes of all particles toward the specified size.

Modifies the size of each particle to be scale percent of the way closer to the specified size triple. This makes sizes grow asymptotically closer to the given size. scale is multiplied by dt before scaling the sizes. Thus, using smaller dt causes a slightly faster approach to the target size. The separate scales for each component allow only selected components to be scaled.

This action makes all sizes tend toward the specified, uniform size. Future versions will have more actions that modify size. Please send me suggestions (perhaps with sample implementations).

The value of scale will usually be very small (less than 0.01) to yield a gradual transition.

Parameters

  size | target size
  scale | what percent of the way from the current size to the target size to transition in unit time

## ◆ TargetSize() [2/2]

void TargetSize | ( | Particle_t & | m,
|  | const pVec & | size,
|  | const pVec & | scale
| ) |  |
| inline

Change sizes of all particles toward the specified size.

Modifies the size of each particle to be scale percent of the way closer to the specified size triple. This makes sizes grow asymptotically closer to the given size. scale is multiplied by dt before scaling the sizes. Thus, using smaller dt causes a slightly faster approach to the target size. The separate scales for each component allow only selected components to be scaled.

This action makes all sizes tend toward the specified, uniform size. Future versions will have more actions that modify size. Please send me suggestions (perhaps with sample implementations).

The value of scale will usually be very small (less than 0.01) to yield a gradual transition.

Parameters

  size | target size
  scale | what percent of the way from the current size to the target size to transition in unit time

## ◆ TargetVelocity() [1/2]

void TargetVelocity | ( | const pVec & | vel,
|  | const float | scale
| ) |  |

Change velocity of all particles toward the specified velocity.

Modifies the velocity of each particle to be scale percent of the way closer to the specified velocity. This makes velocities grow asymptotically closer to the given velocity. scale is multiplied by dt before scaling the velocities. Thus, using smaller dt causes a slightly faster approach to the target velocity.

This action makes all velocities tend toward the specified, uniform velocity. The value of scale will usually be very small (less than 0.01) to yield a gradual transition.

Parameters

  vel | target velocity
  scale | percent of the way from the current velocity to the target velocity to transition in unit time

## ◆ TargetVelocity() [2/2]

void TargetVelocity | ( | Particle_t & | m,
|  | const pVec & | vel,
|  | const float | scale
| ) |  |
| inline

Change velocity of all particles toward the specified velocity.

Modifies the velocity of each particle to be scale percent of the way closer to the specified velocity. This makes velocities grow asymptotically closer to the given velocity. scale is multiplied by dt before scaling the velocities. Thus, using smaller dt causes a slightly faster approach to the target velocity.

This action makes all velocities tend toward the specified, uniform velocity. The value of scale will usually be very small (less than 0.01) to yield a gradual transition.

Parameters

  vel | target velocity
  scale | percent of the way from the current velocity to the target velocity to transition in unit time

## ◆ Vertex()

void Vertex | ( | const pVec & | v,
|  | const pSourceState & | SrcSt,
|  | const pdata_t | data = `0`
| ) |  |

Add a single particle at the specified location.

This action mostly is a shorthand for Source(1, PDPoint(x, y, z)) but allows different callback data per particle.

When called in immediate mode, this action uses a slightly faster method to add a single particle to the current particle group. Also when in immediate mode, exactly one particle will be added per call, instead of an average of 1 / dt particles being added. Particle attributes are chosen according to their current domains, as with Source.

The user data attribute is an exception. It always takes the attribute from the optional data parameter to Vertex(), overriding the source state value.

This call is patterned after the glVertex() calls. It is useful for creating a particle group with exactly specified initial positions. For example, you can specify a geometrical model using Vertex calls, and then explode or deform it.

Parameters

  v | position of particle to create
  SrcSt | all other particle attributes are chosen from this source state
  data | application data to be passed to the birth and death callbacks

## ◆ Vortex() [1/2]

void Vortex | ( | const pVec & | tip,
|  | const pVec & | axis,
|  | const float | tightnessExponent,
|  | const float | max_radius,
|  | const float | inSpeed,
|  | const float | upSpeed,
|  | const float | aroundSpeed
| ) |  |

Accelerate particles in a vortex-like way.

The vortex is a complicated action to use, but when done correctly it makes particles fly around like in a tornado.

Parameters

  tip | tip of the vortex
  axis | the ray along the center of the vortex
  tightnessExponent | exponent that curves the vortex silhouette; 1.0 is a cone; greater curves inward
  max_radius | no particle further than max_radius from the axis is affected
  inSpeed | inward acceleration of particles OUTSIDE the vortex
  upSpeed | vertical acceleration of particles INSIDE the vortex. Can be negative to apply gravity.
  aroundSpeed | acceleration around vortex of particles INSIDE the vortex.

## ◆ Vortex() [2/2]

void Vortex | ( | Particle_t & | m,
|  | const pVec & | tip,
|  | const pVec & | axis,
|  | const float | tightnessExponent,
|  | const float | max_radius,
|  | const float | inSpeed,
|  | const float | upSpeed,
|  | const float | aroundSpeed
| ) |  |
| inline

Accelerate particles in a vortex-like way.

The vortex is a complicated action to use, but when done correctly it makes particles fly around like in a tornado.

Parameters

  tip | tip of the vortex
  axis | the ray along the center of the vortex
  tightnessExponent | exponent that curves the vortex silhouette; 1.0 is a cone; greater curves inward
  max_radius | no particle further than max_radius from the axis is affected
  inSpeed | inward acceleration of particles OUTSIDE the vortex
  upSpeed | vertical acceleration of particles INSIDE the vortex. Can be negative to apply gravity.
  aroundSpeed | acceleration around vortex of particles INSIDE the vortex.

## Member Data Documentation

## ◆ PS

std::shared_ptr<PInternalState_t> PS
| protected

## ◆ PSh

PInternalShadow_t PSh
| protected

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

- pAPIContext.h
- pInlineActionsAPI.h