.. APEX Particles Module Programmers Guide Introduction

====================================================
APEX Particles Module Programmers Guide Introduction
====================================================

.. image:: images/ParticlesIcon.JPG
    :height: 150
    :width: 150

Introduction
============

The APEX Particles module is a particle (object) pipeline that is designed to produce a wide range
of scalable effects in games.  Each stage of the pipeline is an APEX actor derived from an APEX
asset whose parameters are authored.  The particle pipelines consists of a particle emitter, an
Instanced Object Simulation (IOS) that computes the physical movement and life remaining of each
particle, and an Instanced Object Effects (IOFX) actor that based on the particles physical
characteristics determines how the particles (objects) in the pipeline are rendered.  A game level
editor can create multiple emitter actors in a game level.  They can be of the same type or of
different types.  The emitter actors can reference any number of IOS or IOFX actors.  The IOS and
IOFX actors are created automatically by APEX.

.. figure:: images/Apex_psys_pipeline.jpg
    :height: 150
    :width: 600
    :alt: APEX Particle Pipeline
    
    APEX Particle Pipeline

APEX particle emitter actors emit particles at the start of the particle pipeline.  Presently there
are three basic types of Emitter Authorable Objects.  They are the Simple Shape Emitter, Air /
Ground Emitter, and the Weapon Impact Emitter.  The current shape emitters are the box emitter, the
sphere emitter, the sphere shell emitter, and the explicit emitter.  The box and sphere emitters
emit particles (objects) in their shape.  The sphere shell emitter emits particles within the shell
of a specified thickness around a sphere.  Finally the explicit emitter outputs particles at
explicit user defined locations.  The parameters that control the behavior of each of these emitters
is documented here:

- `APEX Emitter Common Parameters <../_static/build_params/structApexEmitterAssetParameters.html>`_

Presently two IOSes have been implemented.  They are the BasicIos and the PxParticleIos (Particles
Library).  The BasicIos provides parameters that control the basics of a stream of particles, such
as the resting density, the particle radius and the maximum number of particles.  The BasicIos does
not interact with PhysX SDK force fields. PxParticleIos is a wrapper for PhysX particle simulation.

There are multiple IOFX modifiers that each provide unique capabilities.  Multiple IOFX modifiers
can be used by a particle pipeline.  Within the IOFX library the modifiers act as elements in the
particle pipeline passing the output of one modifier to the input of the next.  The following
diagram illustrates the internal IOFX pipeline.

.. figure:: images/APEX_psys_iofx.jpg
    :height: 300
    :width: 600
    :alt: APEX IOFX Pipeline
    
    APEX IOFX Pipeline

The IOFX Asset Parameters are documented here\:

- `APEX IOFX Asset Parameters <../_static/build_params/structIofxAssetParameters.html>`_

- `APEX Mesh IOFX Continuous Modifier Parameters <../_static/build_params/unionMeshIofxParameters_1_1ContinuousModifierList.html>`_

- `APEX Sprite IOFX Continuous Modifier Parameters <../_static/build_params/unionSpriteIofxParameters_1_1ContinuousModifierList.html>`_

- `APEX Mesh IOFX Spawn Modifier Parameters <../_static/build_params/unionMeshIofxParameters_1_1SpawnModifierList.html>`_

- `APEX Sprite IOFX Spawn Modifier Parameters <../_static/build_params/unionSpriteIofxParameters_1_1SpawnModifierList.html>`_

All of the currently implemented modifiers are data driven (as opposed to procedural). In the long
term, it will be possible to implement a procedural modifier that will allow game developers to
write their own modifier subroutines (similar to GPU shader programs). Modifiers will be initially
implemented on the CPU, however, the architecture supports an alternative CUDA version for use when
running on CUDA enabled GPU's.  On CUDA enabled systems, particle data will be able to be passed
from CUDA compatible IOS'es to CUDA compatible IOFX Modifiers while
remaining entirely in GPU memory. When support for CUDA/DirectX Interoperability is enabled, data
will be able to be passed from CUDA IOFX Modifiers to the game's rendering engine (through the
Render Resources API), while remaining entirely in GPU memory. 

Performance Considerations
==========================

Particle system run-time performance is primarily linear with the resource budget given to the IOS
modules.  However, the largest source of overhead is in the number of active fluid simulations.  To
achieve optimal performance for a given particle budget, you should use the fewest number of IOS
actors as possible.  The number of emitters and IOFX assets that share an IOS have a relatively
small effect on performance.

To limit the number of IOS actors, one can simply limit the number of IOS assets.  Also be aware
that an IOS actor must operate as either a mesh simulation or a sprite simulation, so if two
emitters use an IOS asset with both sprite and mesh IOFX assets, APEX will generate two IOS actors -
one for each simulation type.

Per-IOS Actor Resources:

* particle simulation buffers
* IOFX modifier state buffers
* CUDA IOFX modifiers are batched to run on an entire IOS at once
* double or triple instanced output buffers
* single sprite or instance render resource
* one writeBuffer() call per simulation step, when interop is not used

Per-IOFX Actor Resources:

* one UserRenderResource holding a particle range in its IOS sprite/instance buffer
* one dispatch (draw call) per render frame
* CPU IOFX modifiers run in parallel in the APEX thread pool

Per-Emitter Actor Resources:

* Computation time to emit particles
* Storage for particles until they are injected into the simulation

PhysX SDK Compatibility
=======================

APEX Particles is compatible with all PhysX SDKs that support APEX.
