PContextParticleGroup_t Class Reference

This class contains the API calls that operate on particle groups. More...

#include <pAPI.h>

Inheritance diagram for PContextParticleGroup_t:

List of all members.

Public Member Functions
void	CopyGroup (const int p_src_group_num, const size_t index=0, const size_t copy_count=P_MAXINT)
	Copy particles from the specified group into the current group.
void	CurrentGroup (const int p_group_num)
	Change which group is current.
void	DeleteParticleGroups (const int p_group_num, const int p_group_count=1)
	Delete one or more consecutive particle groups.
int	GenParticleGroups (const int p_group_count=1, const size_t max_particles=0)
	Create particle groups, each with a maximum of max_particles.
size_t	GetGroupCount ()
	Returns the number of particles existing in the current group.
size_t	GetMaxParticles ()
	Return the maximum number of particles allowed in the current group.
size_t	GetParticles (const size_t index, const size_t count, float *position=NULL, float *color=NULL, float *vel=NULL, float *size=NULL, float *age=NULL)
	Copy particles from the current group to application memory.
size_t	GetParticlePointer (float *&ptr, size_t &stride, size_t &pos3Ofs, size_t &posB3Ofs, size_t &size3Ofs, size_t &vel3Ofs, size_t &velB3Ofs, size_t &color3Ofs, size_t &alpha1Ofs, size_t &age1Ofs, size_t &up3Ofs, size_t &rvel3Ofs, size_t &upB3Ofs, size_t &mass1Ofs, size_t &data1Ofs)
	Return a pointer to particle data stored in API memory.
void	SetMaxParticles (const size_t max_count)
	Change the maximum number of particles in the current group.
void	BirthCallback (P_PARTICLE_CALLBACK callback, puint64 group_data=0)
	Specify a particle creation callback.
void	DeathCallback (P_PARTICLE_CALLBACK callback, puint64 group_data=0)
	Specify a particle death callback.
void	SetWorkingSetSize (const int set_size_bytes)
	Set the number of particles that fit in the CPU's cache.
Protected Member Functions
void	InternalSetup (PInternalState_t *Sr)
Protected Attributes
PInternalState_t *	PS

---

Detailed Description

This class contains the API calls that operate on particle groups.

A particle group is first created using GenParticleGroups(), which will create a sequentially-numbered set of particle groups and return the identifying number of the first generated particle group. You specify which group is current using CurrentGroup(). Unless otherwise stated, all other commands operate on the current particle group. The maximum number of particles in the group is specified using SetMaxParticles(). The particle group is then acted upon using the Actions.

After the actions have been applied, the particles are rendered. This is done at the same stage of the application's execution as drawing other geometry. To draw a particle group in OpenGL, the application calls GetParticles() or GetParticlePointer() functions to get the vertex data, then sends it to OpenGL. When a particle group is no longer needed, it is deleted using DeleteParticleGroups().

---

Member Function Documentation

void BirthCallback	(	P_PARTICLE_CALLBACK	callback,
		puint64	group_data = 0
	)

Specify a particle creation callback.

Specify a callback function within your code that should be called every time a particle is created. The callback is associated only with the particle group that is current at the time you make the BirthCallback() call. You can optionally pass a pointer to arbitrary data of your own, which is returned to your callback.

The API's internal Particle_t struct is passed back to your callback function, so your application will have to include "ParticleLib/Particle.h", which it normally should not do.

Parameters:

	callback	Pointer to function of yours to call
	group_data	Arbitrary per-group data of yours to pass into your function

void CopyGroup	(	const int	p_src_group_num,
		const size_t	index = 0,
		const size_t	copy_count = P_MAXINT
	)

Copy particles from the specified group into the current group.

Copy particles from the specified particle group, p_src_group_num, to the current particle group. Only copy_count particles, starting with number index are copied. Of course, the number of particles actually copied is bounded by the available space in the current particle group, and the number of particles actually in the source particle group. The particles are added, in sequential order, to the end of the current group. index is the index of the first particle in the source particle group to be copied. The group's BirthCallback(), if any, is called for each particle added to the list.

Parameters:

	p_src_group_num	group number of the source particle group
	index	index of the first particle in the source list to copy
	copy_count	copy at most this many particles

void CurrentGroup

(

const int

p_group_num

)

Change which group is current.

Makes p_group_num be the current particle group to which all actions and commands apply.

void DeathCallback	(	P_PARTICLE_CALLBACK	callback,
		puint64	group_data = 0
	)

Specify a particle death callback.

Specify a callback function within your code that should be called every time a particle is killed. The callback is associated only with the particle group that is current at the time you make the DeathCallback() call. You can optionally pass a pointer to arbitrary data of your own, which is returned to your callback.

The API's internal Particle_t struct is passed back to your callback function, so your application will have to include "ParticleLib/Particle.h", which it normally should not do.

Parameters:

	callback	Pointer to function of yours to call
	group_data	Arbitrary per-group data of yours to pass into your function

void DeleteParticleGroups	(	const int	p_group_num,
		const int	p_group_count = 1
	)

Delete one or more consecutive particle groups.

Deletes p_group_count particle groups, with p_group_num being the particle group number of the first one. The groups must be numbered sequentially, and must all exist. This removes the specified particle groups from existence (and all their particles). It does not merely change the number of existing particles or the maximum size of the group.

The DeathCallback is NOT called for the particles in the deleted groups. Should I change this?

Parameters:

	p_group_num	handle of the first particle group to delete
	p_group_count	delete this many groups

int GenParticleGroups	(	const int	p_group_count = 1,
		const size_t	max_particles = 0
	)

Create particle groups, each with a maximum of max_particles.

Generates p_group_count new particle groups and returns the particle group number of the first one. The groups are numbered sequentially, beginning with the number returned. Each particle group is set to have at most max_particles particles. Call SetMaxParticles() to change this. Particle group numbers of groups that have been deleted (using DeleteParticleGroups()) might be reused by GenParticleGroups().

Parameters:

	p_group_count	generate this many groups
	max_particles	each created group can have this many particles

size_t GetGroupCount

(

)

Returns the number of particles existing in the current group.

The number returned is less than or equal to the group's max_particles.

size_t GetMaxParticles

(

)

Return the maximum number of particles allowed in the current group.

This can be changed with SetMaxParticles().

size_t GetParticlePointer	(	float *&	ptr,
		size_t &	stride,
		size_t &	pos3Ofs,
		size_t &	posB3Ofs,
		size_t &	size3Ofs,
		size_t &	vel3Ofs,
		size_t &	velB3Ofs,
		size_t &	color3Ofs,
		size_t &	alpha1Ofs,
		size_t &	age1Ofs,
		size_t &	up3Ofs,
		size_t &	rvel3Ofs,
		size_t &	upB3Ofs,
		size_t &	mass1Ofs,
		size_t &	data1Ofs
	)

Return a pointer to particle data stored in API memory.

This function exposes the internal storage of the particle data to the application. It provides a much higher performance way to render particles because it avoids copying. In fact, the returned pointers can typically be passed directly to OpenGL or D3D without the application ever owning a copy of the data.

Writing to the returned memory is obviously unsafe. There may be auxiliary data that depend on the current values of the particle data. You can try it if you want to, but your code may break against future API versions.

Parameters:

	ptr	the returned pointer to the particle data
	stride	the number of floats from one particle's value to the next particle's value
	pos3Ofs	the number of floats from returned ptr to the first particle's position parameter
	posB3Ofs	the number of floats from returned ptr to the first particle's positionB parameter
	size3Ofs	the number of floats from returned ptr to the first particle's size parameter
	vel3Ofs	the number of floats from returned ptr to the first particle's velocity parameter
	velB3Ofs	the number of floats from returned ptr to the first particle's velocityB parameter
	color3Ofs	the number of floats from returned ptr to the first particle's color parameter
	alpha1Ofs	the number of floats from returned ptr to the first particle's alpha parameter
	age1Ofs	the number of floats from returned ptr to the first particle's age parameter
	up3Ofs	the number of floats from returned ptr to the first particle's up parameter
	rvel3Ofs	the number of floats from returned ptr to the first particle's rvel parameter
	upB3Ofs	the number of floats from returned ptr to the first particle's upB parameter
	mass1Ofs	the number of floats from returned ptr to the first particle's mass parameter
	data1Ofs	the number of floats from returned ptr to the first particle's data parameter, which is a 64-bit integer, not a float

size_t GetParticles	(	const size_t	index,
		const size_t	count,
		float *	position = NULL,
		float *	color = NULL,
		float *	vel = NULL,
		float *	size = NULL,
		float *	age = NULL
	)

Copy particles from the current group to application memory.

Copies at most count particles beginning with the index-th particle in the current particle group into memory already allocated by the application. Three floats are returned for the position of each particle, representing its x,y,z location. Four floats are returned for the color of each particle, representing its R,G,B,A color. Three floats are returned for the velocity of each particle, representing its dx,dy,dz direction vector. Three floats are returned for the size of each particle, representing whatever the application wants them to. One float is returned for the age of each particle.

GetParticles() returns the number of particles copied to application memory. Of course, the number of particles actually returned is bounded by count and by the number of particles actually in the particle group minus index. If verts, color, vel, size or age is NULL then the respective field will not be returned. index and count must be at least 0 and less than the number of particles. index + count must be less than the number of particles. As with all arrays in C, the index of the first particle is zero.

The following code gets the position of all particles:

int cnt = GetGroupCount(); float *ppos = new float[cnt * 3]; int num_ret = GetParticles(0, cnt, ppos);

Parameters:

	index	index of the first particle to return
	count	max number of particles to return
	position	location to store 3 floats per particle for position
	color	location to store 4 floats per particle for color and alpha
	vel	location to store 3 floats per particle for velocity
	size	location to store 3 floats per particle for size
	age	location to store 1 float per particle for age

void SetMaxParticles

(

const size_t

max_count

)

Change the maximum number of particles in the current group.

If necessary, this will delete particles from the end of the particle group, but no other particles will be deleted. The DeathCallback() of deleted particles WILL be called. Call SetMaxParticles(0) to empty the group.

void SetWorkingSetSize

(

const int

set_size_bytes

)

Set the number of particles that fit in the CPU's cache.

You probably don't need to call this function. It is the number of bytes in the working set. Most action lists apply several actions to the working set of particles, then load the next working set of particles and apply the same actions to them. This allows particles to stay resident in the CPU's cache for a longer period of time, potentially increasing performance dramatically.

You specify the working set size in bytes. The default is 768KB.