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

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

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

`#include <pAPIContext.h>`

Inheritance diagram for PContextParticleGroup_t:

## Public Member Functions
void | CopyGroup (const int p_src_group_num, const size_t index, const size_t copy_count)
| Copy particles from the specified group into the current group. More...
void | CurrentGroup (const int p_group_num)
| Change which group is current. More...
void | DeleteParticleGroups (const int p_group_num, const int p_group_count=1)
| Delete one or more consecutive particle groups. More...
int | GenParticleGroups (const int p_group_count=1, const size_t max_particles=0)
| Create particle groups, each with a maximum of max_particles. More...
size_t | GetGroupCount ()
| Returns the number of particles existing in the current group. More...
size_t | GetMaxParticles ()
| Return the maximum number of particles allowed in the current group. More...
size_t | GetParticles (const size_t index, const size_t count, float *position, const bool getAlpha, float *color=NULL, float *vel=NULL, float *size=NULL, float *age=NULL)
| Copy particles from the current group to application memory. More...
size_t | GetParticlePointer (const 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. More...
void | SetMaxParticles (const size_t max_count)
| Change the maximum number of particles in the current group. More...
void | BirthCallback (P_PARTICLE_CALLBACK callback, pdata_t group_data=0)
| Specify a particle creation callback. More...
void | DeathCallback (P_PARTICLE_CALLBACK callback, pdata_t group_data=0)
| Specify a particle death callback. More...
void | SetWorkingSetSize (const int set_size_bytes)
| Set the number of particles that fit in the CPU's cache. More...

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

## Protected Attributes
std::shared_ptr< 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

## ◆ BirthCallback()

void BirthCallback | ( | P_PARTICLE_CALLBACK | callback,
|  | pdata_t | 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 32-bit value that could be a handle to arbitrary data of your own, which is returned to your callback.

The Particle_t struct is passed back to your callback function, so your application will have to include "Particle/pParticle.h".

Parameters

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

## ◆ CopyGroup()

void CopyGroup | ( | const int | p_src_group_num,
|  | const size_t | index,
|  | const size_t | copy_count
| ) |  |

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. The current 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

## ◆ CurrentGroup()

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.

## ◆ DeathCallback()

void DeathCallback | ( | P_PARTICLE_CALLBACK | callback,
|  | pdata_t | 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 Particle_t struct is passed back to your callback function, so your application will have to include "Particle/pParticle.h".

Parameters

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

## ◆ DeleteParticleGroups()

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

## ◆ GenParticleGroups()

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

## ◆ GetGroupCount()

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.

## ◆ GetMaxParticles()

size_t GetMaxParticles | ( |  | ) |

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

This can be changed with SetMaxParticles().

## ◆ GetParticlePointer()

size_t GetParticlePointer | ( | const 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 32-bit integer

## ◆ GetParticles()

size_t GetParticles | ( | const size_t | index,
|  | const size_t | count,
|  | float * | position,
|  | const bool | getAlpha,
|  | 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
  getAlpha | true to get a float4 color with alpha; false to get a float3 color
  color | location to store 3 or 4 floats per particle for color and optionally 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

## ◆ InternalSetup()

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

## ◆ SetMaxParticles()

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.

## ◆ SetWorkingSetSize()

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.

## Member Data Documentation

## ◆ PS

std::shared_ptr<PInternalState_t> PS
| protected

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

- pAPIContext.h