Public Member Functions
int32	CreateParticle (const b2ParticleDef &def)

const b2ParticleHandle *	GetParticleHandleFromIndex (const int32 index)
	Retrieve a handle to the particle at the specified index. More...

void	DestroyParticle (int32 index)

void	DestroyParticle (int32 index, bool callDestructionListener)

void	DestroyOldestParticle (const int32 index, const bool callDestructionListener)

int32	DestroyParticlesInShape (const b2Shape &shape, const b2Transform &xf)

int32	DestroyParticlesInShape (const b2Shape &shape, const b2Transform &xf, bool callDestructionListener)

b2ParticleGroup *	CreateParticleGroup (const b2ParticleGroupDef &def)

void	JoinParticleGroups (b2ParticleGroup groupA, b2ParticleGroup groupB)

void	SplitParticleGroup (b2ParticleGroup *group)

b2ParticleGroup *	GetParticleGroupList ()

const b2ParticleGroup *	GetParticleGroupList () const

int32	GetParticleGroupCount () const
	Get the number of particle groups.

int32	GetParticleCount () const
	Get the number of particles.

int32	GetMaxParticleCount () const
	Get the maximum number of particles.

void	SetMaxParticleCount (int32 count)

uint32	GetAllParticleFlags () const
	Get all existing particle flags.

uint32	GetAllGroupFlags () const
	Get all existing particle group flags.

void	SetPaused (bool paused)

bool	GetPaused () const

void	SetDensity (float32 density)

float32	GetDensity () const
	Get the particle density.

void	SetGravityScale (float32 gravityScale)

float32	GetGravityScale () const
	Get the particle gravity scale.

void	SetDamping (float32 damping)

float32	GetDamping () const
	Get damping for particles.

void	SetStaticPressureIterations (int32 iterations)

int32	GetStaticPressureIterations () const
	Get the number of iterations for static pressure of particles.

void	SetRadius (float32 radius)

float32	GetRadius () const
	Get the particle radius.

b2Vec2 *	GetPositionBuffer ()

const b2Vec2 *	GetPositionBuffer () const

b2Vec2 *	GetVelocityBuffer ()

const b2Vec2 *	GetVelocityBuffer () const

b2ParticleColor *	GetColorBuffer ()

const b2ParticleColor *	GetColorBuffer () const

b2ParticleGroup const	GetGroupBuffer ()

const b2ParticleGroup const	GetGroupBuffer () const

float32 *	GetWeightBuffer ()

const float32 *	GetWeightBuffer () const

void **	GetUserDataBuffer ()

void const	GetUserDataBuffer () const

const uint32 *	GetFlagsBuffer () const

void	SetParticleFlags (int32 index, uint32 flags)
	Set flags for a particle. See the b2ParticleFlag enum.

uint32	GetParticleFlags (const int32 index)
	Get flags for a particle. See the b2ParticleFlag enum.

void	SetFlagsBuffer (uint32 *buffer, int32 capacity)

void	SetPositionBuffer (b2Vec2 *buffer, int32 capacity)

void	SetVelocityBuffer (b2Vec2 *buffer, int32 capacity)

void	SetColorBuffer (b2ParticleColor *buffer, int32 capacity)

void	SetUserDataBuffer (void **buffer, int32 capacity)

const b2ParticleContact *	GetContacts () const

int32	GetContactCount () const

const b2ParticleBodyContact *	GetBodyContacts () const

int32	GetBodyContactCount () const

const b2ParticlePair *	GetPairs () const

int32	GetPairCount () const

const b2ParticleTriad *	GetTriads () const

int32	GetTriadCount () const

void	SetStuckThreshold (int32 iterations)

const int32 *	GetStuckCandidates () const

int32	GetStuckCandidateCount () const
	Get the number of stuck particle candidates from the last step.

float32	ComputeCollisionEnergy () const
	Compute the kinetic energy that can be lost by damping force.

void	SetStrictContactCheck (bool enabled)

bool	GetStrictContactCheck () const
	Get the status of the strict contact check.

void	SetParticleLifetime (const int32 index, const float32 lifetime)

float32	GetParticleLifetime (const int32 index)

void	SetDestructionByAge (const bool enable)

bool	GetDestructionByAge () const

const int32 *	GetExpirationTimeBuffer ()

float32	ExpirationTimeToLifetime (const int32 expirationTime) const

const int32 *	GetIndexByExpirationTimeBuffer ()

void	ParticleApplyLinearImpulse (int32 index, const b2Vec2 &impulse)

void	ApplyLinearImpulse (int32 firstIndex, int32 lastIndex, const b2Vec2 &impulse)

void	ParticleApplyForce (int32 index, const b2Vec2 &force)

void	ApplyForce (int32 firstIndex, int32 lastIndex, const b2Vec2 &force)

b2ParticleSystem *	GetNext ()
	Get the next particle-system in the world's particle-system list.

const b2ParticleSystem *	GetNext () const

void	QueryAABB (b2QueryCallback *callback, const b2AABB &aabb) const

void	QueryShapeAABB (b2QueryCallback *callback, const b2Shape &shape, const b2Transform &xf) const

void	RayCast (b2RayCastCallback *callback, const b2Vec2 &point1, const b2Vec2 &point2) const

void	ComputeAABB (b2AABB *const aabb) const

Friends
class	b2World

class	b2ParticleGroup

class	b2ParticleBodyContactRemovePredicate

class	b2FixtureParticleQueryCallback

Member Function Documentation

void b2ParticleSystem::ApplyForce	(	int32	firstIndex,
		int32	lastIndex,
		const b2Vec2 &	force
	)

Distribute a force across several particles. The particles must not be wall particles. Note that the force is distributed across all the particles, so calling this function for indices 0..N is not the same as calling ApplyForce(i, force) for i in 0..N.

Parameters

firstIndex	the first particle to be modified.
lastIndex	the last particle to be modified.
force	the world force vector, usually in Newtons (N).

void b2ParticleSystem::ApplyLinearImpulse	(	int32	firstIndex,
		int32	lastIndex,
		const b2Vec2 &	impulse
	)

Apply an impulse to all particles between 'firstIndex' and 'lastIndex'. This immediately modifies the velocity. Note that the impulse is applied to the total mass of all particles. So, calling ApplyLinearImpulse(0, impulse) and ApplyLinearImpulse(1, impulse) will impart twice as much velocity as calling just ApplyLinearImpulse(0, 1, impulse).

Parameters

firstIndex	the first particle to be modified.
lastIndex	the last particle to be modified.
impulse	the world impulse vector, usually in N-seconds or kg-m/s.

void b2ParticleSystem::ComputeAABB ( b2AABB *const aabb ) const

Compute the axis-aligned bounding box for all particles contained within this particle system.

Parameters

aabb	Returns the axis-aligned bounding box of the system.

int32 b2ParticleSystem::CreateParticle ( const b2ParticleDef & def )

Create a particle whose properties have been defined. No reference to the definition is retained. A simulation step must occur before it's possible to interact with a newly created particle. For example, DestroyParticleInShape() will not destroy a particle until b2World::Step() has been called.

Warning: This function is locked during callbacks.

Returns: the index of the particle.

b2ParticleGroup * b2ParticleSystem::CreateParticleGroup ( const b2ParticleGroupDef & def )

Create a particle group whose properties have been defined. No reference to the definition is retained.

Warning: This function is locked during callbacks.

void b2ParticleSystem::DestroyOldestParticle	(	const int32	index,
		const bool	callDestructionListener
	)

Destroy the Nth oldest particle in the system. The particle is removed after the next b2World::Step().

Parameters

Index	of the Nth oldest particle to destroy, 0 will destroy the oldest particle in the system, 1 will destroy the next oldest particle etc.
Whether	to call the destruction listener just before the particle is destroyed.

void b2ParticleSystem::DestroyParticle ( int32 index )

inline

Destroy a particle. The particle is removed after the next simulation step (see b2World::Step()).

void b2ParticleSystem::DestroyParticle	(	int32	index,
		bool	callDestructionListener
	)

Destroy a particle. The particle is removed after the next step.

Parameters

Index	of the particle to destroy.
Whether	to call the destruction listener just before the particle is destroyed.

int32 b2ParticleSystem::DestroyParticlesInShape	(	const b2Shape &	shape,
		const b2Transform &	xf
	)

inline

Destroy particles inside a shape without enabling the destruction callback for destroyed particles. This function is locked during callbacks. For more information see DestroyParticleInShape(const b2Shape&, const b2Transform&,bool).

Parameters

Shape	which encloses particles that should be destroyed.
Transform	applied to the shape.

Warning: This function is locked during callbacks.

Returns: Number of particles destroyed.

int32 b2ParticleSystem::DestroyParticlesInShape	(	const b2Shape &	shape,
		const b2Transform &	xf,
		bool	callDestructionListener
	)

Destroy particles inside a shape. This function is locked during callbacks. In addition, this function immediately destroys particles in the shape in constrast to DestroyParticle() which defers the destruction until the next simulation step.

Parameters

Shape	which encloses particles that should be destroyed.
Transform	applied to the shape.
Whether	to call the world b2DestructionListener for each particle destroyed.

Warning: This function is locked during callbacks.

Returns: Number of particles destroyed.

float32 b2ParticleSystem::ExpirationTimeToLifetime ( const int32 expirationTime ) const

Convert a expiration time value in returned by GetExpirationTimeBuffer() to a time in seconds relative to the current simulation time.

Convert a lifetime value in returned by GetExpirationTimeBuffer() to a value in seconds relative to the current simulation time.

const b2ParticleBodyContact * b2ParticleSystem::GetBodyContacts ( ) const

inline

Get contacts between particles and bodies Contact data can be used for many reasons, for example to trigger rendering or audio effects.

b2ParticleColor * b2ParticleSystem::GetColorBuffer ( )

Get the color of each particle Array is length GetParticleCount()

Returns: the pointer to the head of the particle colors array.

const b2ParticleContact * b2ParticleSystem::GetContacts ( ) const

inline

Get contacts between particles Contact data can be used for many reasons, for example to trigger rendering or audio effects.

bool b2ParticleSystem::GetDestructionByAge ( ) const

inline

Get whether the oldest particle will be destroyed in CreateParticle() when the maximum number of particles are present in the system.

const int32 * b2ParticleSystem::GetExpirationTimeBuffer ( )

Get the array of particle expiration times indexed by particle index. GetParticleCount() items are in the returned array.

Get the array of particle lifetimes indexed by particle index. GetParticleCount() items are in the returned array.

const uint32 * b2ParticleSystem::GetFlagsBuffer ( ) const

inline

Get the flags for each particle. See the b2ParticleFlag enum. Array is length GetParticleCount()

Returns: the pointer to the head of the particle-flags array.

b2ParticleGroup *const * b2ParticleSystem::GetGroupBuffer ( )

inline

Get the particle-group of each particle. Array is length GetParticleCount()

Returns: the pointer to the head of the particle group array.

const int32 * b2ParticleSystem::GetIndexByExpirationTimeBuffer ( )

Get the array of particle indices ordered by reverse lifetime. The oldest particle indexes are at the end of the array with the newest at the start. Particles with infinite lifetimes (i.e expiration times less than or equal to 0) are placed at the start of the array. ExpirationTimeToLifetime(GetExpirationTimeBuffer()[index]) is equivalent to GetParticleLifetime(index). GetParticleCount() items are in the returned array.

Get the array of particle indices ordered by lifetime. GetExpirationTimeBuffer( GetIndexByExpirationTimeBuffer()[index]) is equivalent to GetParticleLifetime(index). GetParticleCount() items are in the returned array.

const b2ParticlePair * b2ParticleSystem::GetPairs ( ) const

inline

Get array of particle pairs. The particles in a pair: (1) are contacting, (2) are in the same particle group, (3) are part of a rigid particle group, or are spring, elastic, or wall particles. (4) have at least one particle that is a spring or barrier particle (i.e. one of the types in k_pairFlags), (5) have at least one particle that returns true for ConnectionFilter::IsNecessary, (6) are not zombie particles. Essentially, this is an array of spring or barrier particles that are interacting. The array is sorted by b2ParticlePair's indexA, and then indexB. There are no duplicate entries.

b2ParticleGroup * b2ParticleSystem::GetParticleGroupList ( )

inline

Get the world particle group list. With the returned group, use b2ParticleGroup::GetNext to get the next group in the world list. A NULL group indicates the end of the list.

Returns: the head of the world particle group list.

const b2ParticleHandle * b2ParticleSystem::GetParticleHandleFromIndex ( const int32 index )

Retrieve a handle to the particle at the specified index.

Retrieve a handle to the particle at the specified index. Please see b2ParticleHandle for why you might want a handle.

float32 b2ParticleSystem::GetParticleLifetime ( const int32 index )

Get the lifetime (in seconds) of a particle relative to the current time. A value > 0.0f is returned if the particle is scheduled to be destroyed in the future, values <= 0.0f indicate the particle has an infinite lifetime.

Get the lifetime (in seconds) of a particle relative to the current time.

bool b2ParticleSystem::GetPaused ( ) const

inline

Returns: true if the particle system is being updated in b2World::Step(). Initially, true, then, the last value passed into SetPaused().

b2Vec2 * b2ParticleSystem::GetPositionBuffer ( )

inline

Get the position of each particle Array is length GetParticleCount()

Returns: the pointer to the head of the particle positions array.

const int32 * b2ParticleSystem::GetStuckCandidates ( ) const

inline

Get potentially stuck particles from the last step; the user must decide if they are stuck or not, and if so, delete or move them

const b2ParticleTriad * b2ParticleSystem::GetTriads ( ) const

inline

Get array of particle triads. The particles in a triad: (1) are in the same particle group, (2) are in a Voronoi triangle together, (3) are within b2_maxTriadDistance particle diameters of each other, (4) return true for ConnectionFilter::ShouldCreateTriad (5) have at least one particle of type elastic (i.e. one of the types in k_triadFlags), (6) are part of a rigid particle group, or are spring, elastic, or wall particles. (7) are not zombie particles. Essentially, this is an array of elastic particles that are interacting. The array is sorted by b2ParticleTriad's indexA, then indexB, then indexC. There are no duplicate entries.

void ** b2ParticleSystem::GetUserDataBuffer ( )

Get the user-specified data of each particle. Array is length GetParticleCount()

Returns: the pointer to the head of the particle user-data array.

b2Vec2 * b2ParticleSystem::GetVelocityBuffer ( )

inline

Get the velocity of each particle Array is length GetParticleCount()

Returns: the pointer to the head of the particle velocities array.

float32 * b2ParticleSystem::GetWeightBuffer ( )

inline

Get the weight of each particle Array is length GetParticleCount()

Returns: the pointer to the head of the particle positions array.

void b2ParticleSystem::JoinParticleGroups	(	b2ParticleGroup *	groupA,
		b2ParticleGroup *	groupB
	)

Join two particle groups.

Parameters

the	first group. Expands to encompass the second group.
the	second group. It is destroyed.

Warning: This function is locked during callbacks.

void b2ParticleSystem::ParticleApplyForce	(	int32	index,
		const b2Vec2 &	force
	)

Apply a force to the center of a particle.

Parameters

index	the particle that will be modified.
force	the world force vector, usually in Newtons (N).

void b2ParticleSystem::ParticleApplyLinearImpulse	(	int32	index,
		const b2Vec2 &	impulse
	)

inline

Apply an impulse to one particle. This immediately modifies the velocity. Similar to b2Body::ApplyLinearImpulse.

Parameters

index	the particle that will be modified.
impulse	the world impulse vector, usually in N-seconds or kg-m/s.

void b2ParticleSystem::QueryAABB	(	b2QueryCallback *	callback,
		const b2AABB &	aabb
	)		const

Query the particle system for all particles that potentially overlap the provided AABB. b2QueryCallback::ShouldQueryParticleSystem is ignored.

Parameters

callback	a user implemented callback class.
aabb	the query box.

void b2ParticleSystem::QueryShapeAABB	(	b2QueryCallback *	callback,
		const b2Shape &	shape,
		const b2Transform &	xf
	)		const

Query the particle system for all particles that potentially overlap the provided shape's AABB. Calls QueryAABB internally. b2QueryCallback::ShouldQueryParticleSystem is ignored.

Parameters

callback	a user implemented callback class.
shape	the query shape
xf	the transform of the AABB

void b2ParticleSystem::RayCast	(	b2RayCastCallback *	callback,
		const b2Vec2 &	point1,
		const b2Vec2 &	point2
	)		const

Ray-cast the particle system for all particles in the path of the ray. Your callback controls whether you get the closest point, any point, or n-points. The ray-cast ignores particles that contain the starting point. b2RayCastCallback::ShouldQueryParticleSystem is ignored.

Parameters

callback	a user implemented callback class.
point1	the ray starting point
point2	the ray ending point

void b2ParticleSystem::SetDamping ( float32 damping )

inline

Damping is used to reduce the velocity of particles. The damping parameter can be larger than 1.0f but the damping effect becomes sensitive to the time step when the damping parameter is large.

void b2ParticleSystem::SetDensity ( float32 density )

inline

Change the particle density. Particle density affects the mass of the particles, which in turn affects how the particles interact with b2Bodies. Note that the density does not affect how the particles interact with each other.

void b2ParticleSystem::SetDestructionByAge ( const bool enable )

Enable / disable destruction of particles in CreateParticle() when no more particles can be created due to a prior call to SetMaxParticleCount(). When this is enabled, the oldest particle is destroyed in CreateParticle() favoring the destruction of particles with a finite lifetime over particles with infinite lifetimes. This feature is enabled by default when particle lifetimes are tracked. Explicitly enabling this feature using this function enables particle lifetime tracking.

void b2ParticleSystem::SetFlagsBuffer	(	uint32 *	buffer,
		int32	capacity
	)

Set an external buffer for particle data. Normally, the b2World's block allocator is used for particle data. However, sometimes you may have an OpenGL or Java buffer for particle data. To avoid data duplication, you may supply this external buffer.

Note that, when b2World's block allocator is used, the particle data buffers can grow as required. However, when external buffers are used, the maximum number of particles is clamped to the size of the smallest external buffer.

Parameters

buffer	is a pointer to a block of memory.
size	is the number of values in the block.

void b2ParticleSystem::SetGravityScale ( float32 gravityScale )

inline

Change the particle gravity scale. Adjusts the effect of the global gravity vector on particles.

void b2ParticleSystem::SetMaxParticleCount ( int32 count )

inline

Set the maximum number of particles. A value of 0 means there is no maximum. The particle buffers can continue to grow while b2World's block allocator still has memory. Note: If you try to CreateParticle() with more than this count, b2_invalidParticleIndex is returned unless SetDestructionByAge() is used to enable the destruction of the oldest particles in the system.

void b2ParticleSystem::SetParticleLifetime	(	const int32	index,
		const float32	lifetime
	)

Set the lifetime (in seconds) of a particle relative to the current time. A lifetime of less than or equal to 0.0f results in the particle living forever until it's manually destroyed by the application.

Set the lifetime (in seconds) of a particle relative to the current time.

void b2ParticleSystem::SetPaused ( bool paused )

inline

Pause or unpause the particle system. When paused, b2World::Step() skips over this particle system. All b2ParticleSystem function calls still work.

Parameters

paused is true to pause, false to un-pause.

void b2ParticleSystem::SetRadius ( float32 radius )

inline

Change the particle radius. You should set this only once, on world start. If you change the radius during execution, existing particles may explode, shrink, or behave unexpectedly.

void b2ParticleSystem::SetStaticPressureIterations ( int32 iterations )

inline

Change the number of iterations when calculating the static pressure of particles. By default, 8 iterations. You can reduce the number of iterations down to 1 in some situations, but this may cause instabilities when many particles come together. If you see particles popping away from each other like popcorn, you may have to increase the number of iterations. For a description of static pressure, see http://en.wikipedia.org/wiki/Static_pressure#Static_pressure_in_fluid_dynamics

void b2ParticleSystem::SetStrictContactCheck ( bool enabled )

inline

Set strict Particle/Body contact check. This is an option that will help ensure correct behavior if there are corners in the world model where Particle/Body contact is ambiguous. This option scales at n*log(n) of the number of Particle/Body contacts, so it is best to only enable if it is necessary for your geometry. Enable if you see strange particle behavior around b2Body intersections.

void b2ParticleSystem::SetStuckThreshold ( int32 iterations )

Set an optional threshold for the maximum number of consecutive particle iterations that a particle may contact multiple bodies before it is considered a candidate for being "stuck". Setting to zero or less disables.

void b2ParticleSystem::SplitParticleGroup ( b2ParticleGroup * group )

Split particle group into multiple disconnected groups.

Parameters

the	group to be split.

Warning: This function is locked during callbacks.

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

b2ParticleSystem.h
b2ParticleSystem.cpp

Public Member Functions

Friends

Member Function Documentation