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:

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Inline Actions

Legacy Actions

Member Function Documentation

◆ Avoid() [1/2]

◆ Avoid() [2/2]

◆ Bounce() [1/2]

◆ Bounce() [2/2]

◆ Callback() [1/2]

◆ Callback() [2/2]

◆ CommitKills()

◆ CopyVertexB() [1/2]

◆ CopyVertexB() [2/2]

◆ Damping() [1/2]

◆ Damping() [2/2]

◆ Explosion() [1/2]

◆ Explosion() [2/2]

◆ Follow() [1/2]

◆ Follow() [2/2]

◆ Gravitate() [1/2]

◆ Gravitate() [2/2]

◆ Gravity() [1/2]

◆ Gravity() [2/2]

◆ InternalSetup()

◆ Jet() [1/2]

◆ Jet() [2/2]

◆ KillOld() [1/2]

◆ KillOld() [2/2]

◆ MatchRotVelocity() [1/2]

◆ MatchRotVelocity() [2/2]

◆ MatchVelocity() [1/2]

◆ MatchVelocity() [2/2]

◆ Move() [1/2]

◆ Move() [2/2]

◆ OrbitLine() [1/2]

◆ OrbitLine() [2/2]

◆ OrbitPoint() [1/2]

◆ OrbitPoint() [2/2]

◆ ParticleLoop() [1/2]

◆ ParticleLoop() [2/2]

◆ RandomAccel() [1/2]

◆ RandomAccel() [2/2]

◆ RandomDisplace() [1/2]

◆ RandomDisplace() [2/2]

◆ RandomRotVelocity() [1/2]

◆ RandomRotVelocity() [2/2]

◆ RandomVelocity() [1/2]

◆ RandomVelocity() [2/2]

◆ Restore() [1/2]

◆ Restore() [2/2]

◆ RotDamping() [1/2]

◆ RotDamping() [2/2]

◆ Sink() [1/2]

◆ Sink() [2/2]

◆ SinkVelocity() [1/2]

◆ SinkVelocity() [2/2]

◆ Sort()

◆ Source()

◆ SpeedClamp() [1/2]

◆ SpeedClamp() [2/2]

◆ TargetColor() [1/2]

◆ TargetColor() [2/2]

◆ TargetRotVelocity() [1/2]

◆ TargetRotVelocity() [2/2]

◆ TargetSize() [1/2]

◆ TargetSize() [2/2]

◆ TargetVelocity() [1/2]

◆ TargetVelocity() [2/2]

◆ Vertex()

◆ Vortex() [1/2]

◆ Vortex() [2/2]

Member Data Documentation

◆ PS

◆ PSh