Creating Particles

The application specifies an index for each new particle at particle creation time. If the application maintains its own representation of particles, and already tracks active indices, then these indices may be re-used by PhysX. If the application does not have appropriate indices at its disposal, it can use an index pool provided by the PhysX extensions library PxParticleExt::IndexPool as explained here: Index Pool Extension.

PhysX 3 itself has no built-in emitters. Instead, it simply provides an interface to create particles with initial properties. When creating particles, specifying indices and positions is mandatory, while velocities and rest offsets may be specified optionally.

The PhysX particle API uses the PxStrideIterator template class to pass per particle data between the SDK and the application. This allows the particle data layout to be chosen more flexible by supporting interleaved arrays or padded data without forcing extra copies for reformatting. The stride iterator is configured by setting the type of the iterated data and specifying the pointer to the first element.

Example for creating a few particles:

// declare particle descriptor for creating new particles
// based on numNewAppParticles count and newAppParticleIndices,
// newAppParticlePositions arrays and newAppParticleVelocity
PxParticleCreationData particleCreationData;
particleCreationData.numParticles = numNewAppParticles;
particleCreationData.indexBuffer = PxStrideIterator<const PxU32>(newAppParticleIndices);
particleCreationData.positionBuffer = PxStrideIterator<const PxVec3>(newAppParticlePositions);
particleCreationData.velocityBuffer = PxStrideIterator<const PxVec3>(&newAppParticleVelocity, 0);

// create particles in *PxParticleSystem* ps
bool success = ps->createParticles(particleCreationData);

The indices specified for particle creation need to be unique and within the limit of PxParticleBase::getMaxParticles().

In this example the stride iterator is used to set the same velocity for all new particles. This is achieved by setting the stride to zero.

Releasing Particles

Particles can be released by providing indices to the particle system. As opposed to older versions of the PhysX SDK, particles get immediately released.

Example for releasing a few particles:

// declare strided iterator for providing array of indices corresponding to
// particles that should be removed
PxStrideIterator<const PxU32> indexBuffer(appParticleIndices);

// release particles in *PxParticleSystem* ps
ps->releaseParticles(numAppParticleIndices, indexBuffer);

It is a requirement that the indices passed to the release method are unique and correspond to existing particles.

All particles can be released at once by calling:

ps->releaseParticles();

Since only a limited number of particle slots (PxParticleBase::getMaxParticles()) are available it might be appropriate to replace old particles with new ones. This can be achieved for instance by maintaining an application-side particle lifetime. There are other reasons to release particles:

• Drains can be useful to remove particles that go to locations where they are not needed anymore. See Particle Drains.
• The spatial data structure used for particles may overflow. Particles that cannot be covered are marked and should be released. See Particle Grid.

Index Pool Extension

Example for allocating particle indices using the PhysX extensions library:

// create an index pool for a particle system with maximum particle count of maxParticles
PxParticleExt::IndexPool* indexPool = PxParticleExt::createIndexPool(maxParticles);

// use the indexPool for allocating numNewAppParticles indices that can be used
// for particle creation throughout the particle system lifetime. If numAllocated
// is smaller than numNewAppParticles, the maxParticles limit was exceeded
PxU32 numAllocated = indexPool->allocateIndices(numNewAppParticles,
                                                PxStrideIterator<PxU32>(newAppParticleIndices));

// in order to reuse particle slots, the indices should be handed back to the
// indexPool after the particles have been released
indexPool->freeIndices(numAppParticleIndices, PxStrideIterator<PxU32>(appParticleIndices));

// if no further index management is needed, the pool should be released
indexPool->release();

Updating Particles

The following per-particle updates are carried out immediately:

• Position updates: Teleporting particles from one location to another.
• Velocity updates: Directly altering the velocities of particles.
• Rest offset updates: Changes particle rest offsets (only available with PxParticleBaseFlag::ePER_PARTICLE_REST_OFFSET).

Particle updates that are carried out during the next scene simulation step:

• Force updates: Results in a velocity change update according to a vector unit specified by PxForceMode.

Example for force update:

// specify strided iterator to provide update forces
PxStrideIterator<const PxVec3> forceBuffer(appParticleForces);

// specify strided iterator to provide indices of particles that need to be updated
PxStrideIterator<const PxU32> indexBuffer(appParticleForceIndices);

// specify force update on PxParticleSystem ps choosing the "force" unit
ps->addForces(numAppParticleForces, indexBuffer, forceBuffer, PxForceMode::eFORCE);

Reading Particles

The PhysX SDK does not provide to the user all simulated per-particle properties of a particle system by default. The application can specify the data it needs by configuring PxParticleBase::particleReadDataFlags:

• PxParticleReadDataFlag::ePOSITION_BUFFER: On by default.
• PxParticleReadDataFlag::eFLAGS_BUFFER: On by default.
• PxParticleReadDataFlag::eVELOCITY_BUFFER: Off by default.
• PxParticleReadDataFlag::eREST_OFFSET_BUFFER: Off by default. May only be enabled if the particle system was created with per particle rest offset support. See Creating Particle Systems.
• PxParticleReadDataFlag::eCOLLISION_NORMAL_BUFFER: Off by default.
• PxParticleReadDataFlag::eDENSITY_BUFFER: Only available for particle fluids and off by default.

Particle flags provide more information on individual particles:

• PxParticleFlag::eVALID: If set, the particle was created beforehand and not yet released. If not set, the particle slot does not contain a valid particle. All other properties are invalid in this case and should be ignored.
• PxParticleFlag::eCOLLISION_WITH_STATIC: Shows whether a particle collided with a rigid static during the last simulation step.
• PxParticleFlag::eCOLLISION_WITH_DYNAMIC: Shows whether a particle collided with a dynamic rigid body during the last simulation step.
• PxParticleFlag::eCOLLISION_WITH_DRAIN: Shows whether a particle collided with a rigid actor shape that was marked as a drain (Particle Drains).
• PxParticleFlag::eSPATIAL_DATA_STRUCTURE_OVERFLOW: Shows whether a particle had to be omitted when building the SDK internal spatial data structure (Particle Grid).

Particle collision normals represent contact normals between particles and rigid actor surfaces. A non-colliding particle has a zero collision normal. Collision normals are useful e.g. for orienting the particle visualization according to their contact with rigid actors.

Particle densities provided by particle fluids can be used for rendering. A particle density has a value of zero for a particle that is completely isolated. It has a value of one for a particle that has a particle neighborhood with a mean spacing corresponding to PxParticleFluid::getRestParticleDistance().

Particle data can only be read while the scene simulation is not executing. In order to get access to the SDK buffers a PxParticleReadData instance needs to be acquired from the SDK. It has the following properties:

• numValidParticles: Total number of valid particles for the corresponding particle system.
• validParticleRange: The index range of valid particles in the particle buffers.
• validParticleBitmap: Bitmap of valid particle locations.
• positionBuffer, positionBuffer, velocityBuffer, restOffsetBuffer, flagsBuffer, collisionNormalBuffer: Strided iterators for particle properties.

Additionally particle fluids provide PxParticleFluidReadData with

• densityBuffer: Strided iterator for particle densities.

Figure 3: PxParticleReadData and PxParticleFluidReadData

Example of how to access particle data:

// lock SDK buffers of *PxParticleSystem* ps for reading
PxParticleReadData* rd = ps->lockParticleReadData();

// access particle data from PxParticleReadData
if (rd)
{
    PxStrideIterator<const PxParticleFlags> flagsIt(rd->flagsBuffer);
    PxStrideIterator<const PxVec3> positionIt(rd->positionBuffer);

    for (unsigned i = 0; i < rd->validParticleRange; ++i, ++flagsIt, ++positionIt)
    {
        if (*flagsIt & PxParticleFlag::eVALID)
        {
            // access particle position
            const PxVec3& position = *positionIt;
        }
    }

    // return ownership of the buffers back to the SDK
    rd->unlock();
}

Example of how to use the valid particle bitmap to access particle data (without showing the locking and unlocking):

if (rd->validParticleRange > 0)
{
    // iterate over valid particle bitmap
    for (PxU32 w = 0; w <= (rd->validParticleRange-1) >> 5; w++)
    {
        for (PxU32 b = rd->validParticleBitmap[w]; b; b &= b-1)
        {
            PxU32 index = (w << 5 | Ps::lowestSetBit(b));

            // access particle position
            const PxVec3& position = rd->positionBuffer[index];
        }
    }
}

Particle Dynamics

externalAcceleration:

Acceleration applied to each particle at each time step. The scene gravity which is added to the external acceleration by default can be disabled using PxActorFlag::eDISABLE_GRAVITY.

maxMotionDistance:

The maximum distance a particle can travel during one simulation step. High values may hurt performance, while low values may restrict the particle velocity too much. In order to improve performance it's advisable to set this to a low value and then increase it until particles can move fast enough to achieve the target effect. Parameter can only be changed while particle system is not part of a scene.

damping:

Velocity damping constant, which is globally applied to each particle. This is particularly useful when using particles for smoke to prevent ballistic behavior of individual particles which can look odd.

particleMass:

Mass used for two way interaction with rigid bodies (PxParticleBaseFlag::eCOLLISION_TWOWAY) and different force modes in the context of PxParticleBase::addForces. This mass property doesn't have any impact on the fluid dynamics simulation.

PxParticleBaseFlag::ePROJECT_TO_PLANE, projectionPlaneNormal, projectionPlaneDistance:

Parameter to configure the projection mode which confines particles to a plane. If projection is enabled particles can only move in a plane. This can be a useful option in the context of a 2D-Game.

Collision with Rigid Actors

restOffset:

Defines the minimum distance between particles and the surface of rigid actors that is maintained by the collision system. Parameter can only be changed while particle system is not part of a scene.

PxParticleBaseFlag::ePER_PARTICLE_REST_OFFSET:

Enables/disables per-particle rest offsets. Memory can be saved by turning per particle rest offsets off. Per-particle rest offsets should only be enabled if the particles represent objects of significantly varying size, for example in the context of debris effects. See Per-particle Rest Offsets. Can only be set on particle system creation.

contactOffset:

Defines the distance at which contacts between particles and rigid actors are created. The contacts are internally used to avoid jitter and sticking. It needs to be larger than restOffset. A good value to start with is about twice the size of the rest offset. Parameter can only be changed while particle system is not part of a scene.

restitution:

Restitution used for particle collision. This parameter defines how strongly particles bounce of rigid actors.

dynamicFriction:

Dynamic friction used for particle collision. This parameter defines how easily particles slide over rigid actor surfaces. The lower the value is to 0, the easier particles slide. One is the maximal value supported.

staticFriction:

Static friction used for particle collision. This parameter is similar to dynamic friction but defines how easily particles start to slide over a surface. Values larger than one are supported.

simulationFilterData:

Filter data used to filter collisions between particles and rigid bodies. See Collision Filtering.

PxParticleBaseFlag::eCOLLISION_TWOWAY:

The collision two-way flag allows enabling/disabling two-way interaction between rigid bodies and particles. The particle mass parameter defines the strength of the interaction. The flag can only be changed while the particle system is not part of a scene.

Fluid (PxParticleFluid)

The SPH simulation can be tricky to tweak for good results. As this simulation technique (see References) uses an explicit integration scheme it only provides stable results within a certain parameter sub-space. A good set of parameter values depend on the time step size of the simulation and the external forces applied (such as gravity). The suggested starting points for parameter values below assume a time step size of about 1/60 [s] and a gravity around 10 [m/s^2]. Using a damping value larger than zero allows for a larger parameter sub-space, for example useful when implementing a smoke effect.

restParticleDistance:

Defines the resolution of the particle fluid. It defines the approximate distance that neighboring particles will adopt within a fluid volume at rest. For the parameter tweaking assumption mentioned above, the particle rest distance should not be smaller than 0.05 [m]. Parameter can only be changed while particle system is not part of a scene.

stiffness:

The stiffness (or gas constant) influences the calculation of the pressure force field. Low values of stiffness make the fluid more compressible (i.e., springy), while high values make it less compressible. The stiffness value has a significant impact on the numerical stability of the simulation; setting very high values will result in instability. Reasonable values are usually between 1 and 200.

viscosity:

Viscosity controls a fluid's thickness. For example, a fluid with a high viscosity will behave like treacle, while a fluid with low viscosity will be more like water. The viscosity value scales the force to reduce the relative velocity of particles within the fluid. Both, too high and too low values will typically result in instabilities. Reasonable values are usually between 5 and 300.

Collision Filtering

Filtering particle versus rigid body collisions can be useful to avoid unnecessary performance overhead or simply to avoid undesired collisions.

For the following examples filtering is useful:

• Avoid particles colliding with trigger shapes (this is already the behavior of PxDefaultSimulationFilterShader)
• Configure a drain shape to exclusively collide with particles
• Have particles collide with a proxy shape as opposed to the shape used for rigid body collisions

Filter information for particles can be specified by calling PxParticleBase::setSimulationFilterData(). Instructions for how to setup filter shaders can be found here: Collision Filtering.

Per-particle Rest Offsets

It is also possible to set a rest offset per-particle, using PxParticleBase::setRestOffsets(). In order to provide per-particle rest offsets PxParticleBaseFlag::ePER_PARTICLE_REST_OFFSET needs to be set and the rest offsets must be smaller than the per-system value given by PxParticleBase.getRestOffset().

Particle Drains

Using drains is a good method for keeping the particle count and spread under control. Placing drains around the area of interest in which a particle system is used helps to maintain good performance of the particle simulation. The area of interest could, for example, also be moved with the player.

Example of how to flag a PxShape rbShape as a drain:

rbShape->setFlag(PxShapeFlag::ePARTICLE_DRAIN, true);

Particles that collide with a drain are marked with PxParticleFlag::eCOLLISION_WITH_DRAIN and may be released.

Particle Grid and Spatial Data Structure Overflow

The PhysX SDK uses a grid to subdivide the particles of a particle system into spatial groups. This is done to accelerate proximity queries and for parallelization purposes. The grid size parameter needs to be experimentally adjusted with PxParticleBase::setGridSize() for best performance. When doing this it is helpful to visualize the grid using PxVisualizationParameter::ePARTICLE_SYSTEM_GRID. Small grid size values might result in spatial data structure overflow, since the number of grid cells is limited to about 1000. Large grid size values on the other hand might result in poor performance due to ineffective spatial queries or lack of parallelization opportunities.

In case of overflow, some particles will stop colliding with rigid actors in the scene. These particles are marked with PxParticleFlag::eSPATIAL_DATA_STRUCTURE_OVERFLOW and should be released.