PContextActions_t Class Reference

This class contains the actual Action API calls. More...

#include <pAPI.h>

Inheritance diagram for PContextActions_t:

List of all members.

Public Member Functions
void	Avoid (float magnitude, const float epsilon, const float look_ahead, const pDomain &dom)
	Steer particles away from a domain of space.
void	Bounce (float friction, const float resilience, const float cutoff, const pDomain &dom)
	Bounce particles off an object defined by a domain.
void	Callback (P_PARTICLE_CALLBACK callback, puint64 call_data=0)
	Call an arbitrary user-provided function on each particle in the group.
void	CopyVertexB (const bool copy_pos=true, const bool copy_vel=false)
	Set the secondary position and velocity from current.
void	Damping (const pVec &damping, const float vlow=0.0f, const float vhigh=P_MAXFLOAT)
	Simulate air by dampening particle velocities.
void	RotDamping (const pVec &damping, const float vlow=0.0f, const float vhigh=P_MAXFLOAT)
	Simulate air by dampening rotational velocities.
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.
void	Follow (float magnitude=1.0f, const float epsilon=P_EPS, const float max_radius=P_MAXFLOAT)
	Accelerate toward the next particle in the list.
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.
void	Gravity (const pVec &dir)
	Accelerate particles in the given direction.
void	Jet (const pDomain &dom, const pDomain &acc)
	For particles in the domain of influence, accelerate them with a domain.
void	KillOld (const float age_limit, const bool kill_less_than=false)
	Get rid of older particles.
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.
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.
void	Move (const bool move_velocity=true, const bool move_rotational_velocity=true)
	Apply the particles' velocities to their positions, and age the particles.
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.
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.
void	RandomAccel (const pDomain &dom)
	Accelerate particles in random directions.
void	RandomDisplace (const pDomain &dom)
	Immediately displace position by a random amount.
void	RandomVelocity (const pDomain &dom)
	Replace particle velocity with a random velocity.
void	RandomRotVelocity (const pDomain &dom)
	Immediately assign a random rotational velocity.
void	Restore (const float time, const bool vel=true, const bool rvel=true)
	Over time, restore particles to their target positionB and upB.
void	Sink (const bool kill_inside, const pDomain &dom)
	Kill particles that have positions on wrong side of the specified domain.
void	SinkVelocity (const bool kill_inside, const pDomain &dom)
	Kill particles that have velocities on wrong side of the specified domain.
void	Sort (const pVec &eye, const pVec &look, const bool front_to_back=false, const bool clamp_negative=false)
	Sort the particles by their projection onto the look vector.
void	Source (const float particle_rate, const pDomain &dom)
	Add particles with positions in the specified domain.
void	SpeedLimit (const float min_speed, const float max_speed=P_MAXFLOAT)
	Clamp particle velocities to the given range.
void	TargetColor (const pVec &color, const float alpha, const float scale)
	Change color of all particles toward the specified color.
void	TargetSize (const pVec &size, const pVec &scale)
	Change sizes of all particles toward the specified size.
void	TargetVelocity (const pVec &vel, const float scale)
	Change velocity of all particles toward the specified velocity.
void	TargetRotVelocity (const pVec &rvel, const float scale)
	Change rotational velocity of all particles toward the specified rotational velocity.
void	Vertex (const pVec &v, puint64 data=0)
	Add a single particle at the specified location.
void	Vortex (const pVec &center, 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.
Protected Member Functions
void	InternalSetup (PInternalState_t *Sr)
Protected Attributes
PInternalState_t *	PS

---

Detailed Description

This class contains the actual Action API calls.

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 TimeStep. See TimeStep() for an explanation of time steps.

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.

---

Member Function Documentation

void Avoid	(	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	The amount of acceleration falls off inversely with the squared distance to the edge of the domain. But when that distance is small, the acceleration would be infinite, so epsilon is always added to the distance.
	look_ahead	how far forward along the velocity vector to look for the obstacle
	dom	the space to avoid

void Bounce	(	float	friction,
		const float	resilience,
		const float	cutoff,
		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 cutoff 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 the only domains for which Bounce() is implemented are PDSphere, PDRectangle, PDTriangle, PDDisc and PDPlane. 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. 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	The tangential component of the outgoing velocity vector is scaled by (1 - friction).
	resilience	The normal component of the outgoing velocity vector is scaled by resilience.
	cutoff	Only apply friction if the outgoing tangential velocity is greater than cutoff. This can allow particles to glide smoothly along a surface without sticking.
	dom	Bounce off the surface of this domain.

void Callback	(	P_PARTICLE_CALLBACK	callback,
		puint64	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:

	callback	Pointer to function of yours to call
	call_data	Arbitrary data of yours to pass into your function

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 the PositionB of each particle 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 the velocityB of each particle to the current velocity of that particle. This can be useful for computing the orientation of the particle by copying a particle's velocity at the beginning of each time step. Then when drawing a particle, the cross-product velocity and velocityB yields a tangent vector.

void Damping	(	const pVec &	damping,
		const float	vlow = 0.0f,
		const float	vhigh = P_MAXFLOAT
	)

Simulate air by dampening particle velocities.

If a particle's velocity magnitude is within vlow and vhigh, 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

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	The amount of acceleration falls off inversely with the squared distance to the edge of the domain. But when that distance is small, the acceleration would be infinite, so epsilon is always added to the distance.

void Follow	(	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	The amount of acceleration falls off inversely with the squared distance to the edge of the domain. But when that distance is small, the acceleration would be infinite, so epsilon is always added to the distance.
	max_radius	defines the sphere of influence of this action. No particle further than max_radius from its predecessor is affected.

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	The amount of acceleration falls off inversely with the squared distance to the edge of the domain. But when that distance is small, the acceleration would be infinite, so epsilon is always added to the distance.
	max_radius	defines the sphere of influence of this action. No particle further than max_radius from another particle is affected.

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.

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. acceleration vector comes from this domain

Parameters:

dom

apply jet to particles in this domain

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:

kill_less_than

true to kill particles younger than age_limit

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	The amount of acceleration falls off inversely with the squared distance to the edge of the domain. But when that distance is small, the acceleration would be infinite, so epsilon is always added to the distance.
	max_radius	defines the sphere of influence of this action. No particle further than max_radius from another particle is affected.

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	The amount of acceleration falls off inversely with the squared distance to the edge of the domain. But when that distance is small, the acceleration would be infinite, so epsilon is always added to the distance.
	max_radius	defines the sphere of influence of this action. No particle further than max_radius from another particle is affected.

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.

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	The amount of acceleration falls off inversely with the squared distance to the edge of the domain. But when that distance is small, the acceleration would be infinite, so epsilon is always added to the distance.
	max_radius	defines the cylinder of influence of this action. No particle further than max_radius from the line is affected.

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	The amount of acceleration falls off inversely with the squared distance to the edge of the domain. But when that distance is small, the acceleration would be infinite, so epsilon is always added to the distance.
	max_radius	defines the sphere of influence of this action. No particle further than max_radius from the center is affected.

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.

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.

void RandomRotVelocity

(

const pDomain &

dom

)

Immediately assign a random rotational velocity.

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

void RandomVelocity

(

const pDomain &

dom

)

Replace particle velocity with a random velocity.

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

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

void RotDamping	(	const pVec &	damping,
		const float	vlow = 0.0f,
		const float	vhigh = P_MAXFLOAT
	)

Simulate air by dampening rotational velocities.

If a particle's rotational velocity magnitude is within vlow and vhigh, 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

void Sink	(	const bool	kill_inside,
		const pDomain &	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

void SinkVelocity	(	const bool	kill_inside,
		const pDomain &	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

void Sort	(	const pVec &	eye,
		const pVec &	look,
		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.

Parameters:

	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. This speeds up sorting time. Particles behind the viewer won't be visible so their relative order doesn't matter.

void Source	(	const float	particle_rate,
		const pDomain &	dom
	)

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

void SpeedLimit	(	const float	min_speed,
		const float	max_speed = P_MAXFLOAT
	)

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 SpeedLimit().

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

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	what percent of the way from the current rotational velocity to the target rotational velocity to transition in unit time

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

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	what percent of the way from the current velocity to the target velocity to transition in unit time

void Vertex	(	const pVec &	v,
		puint64	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
	data	application data to be passed to the birth and death callbacks

void Vortex	(	const pVec &	center,
		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:

	center	tip of the vortex
	axis	the ray along the center of the vortex
	tightnessExponent	like a Phong exponent that gives a curve to the vortex silhouette; 1.0 is a cone; greater than 1.0 curves inward.
	max_radius	defines the radius at the top of the vortex and the infinite cylinder of influence. 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.