.. APEX Particles Module Users Guide Introduction

==============================================
APEX Particles Module Users 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


The new unified Particles module for APEX 1.3
=============================================

APEX 1.3 introduces a new module called 'Particles'.  This new singular 'Particles' module, which
is delivered as a DLL under the Windows platform, now combines all particle related modules (IOFX,
Emitter, IOS, etc.) into a single binary.  It does not include the Turbulence module due to how the
source code for this component is licensed.

The primary reason for this change is to simplify the process of managing these modules as well as
to make it easier to create binary distributions.  Now, instead of an application loading the IOFX
modules, Emitter module, etc. separately, the application simply loads the single 'Particles' module.
The application now needs only to load the 'Particles' module on startup, release it on exit,
and when it comes to deployment distribute only this single binary DLL.  If the application needs
access to the various sub-component modules, such as IOFX, Emitter, etc. they still exist but are now
accessed via the 'ModuleParticles' class using the method 'getModule'.

Relatively modest changes are required to existing source code developed against a previous version
of the APEX SDK; changes which primarily involve deleting source which used to have to deal with the
granular module loading mechanism.  In short, it essentially cleans up your startup and shutdown code.

Another feature introduced with the new unified 'Particles' module is the 'EffectPackageActor' and
'EffectPackageAsset'.  The 'effect package' system combines a collection of particle related actors
into a single instantiation which can be manipulated as whole unit.  Imagine you have an 'effect' which
involves multiple emitters, a turbulence grid, a heat source, and some jet field samplers.  Rather than
having to instantiate and manage five or six separate APEX actors you can now instantiate them all as a
single 'effect' and manage it as a unit.  The newly introduced 'Particle Effect Tool' (PET) now allows a
designer/artist to author 'effects' which can be managed in this way.  This feature is optional and is not
required to work with APEX particles.  You can still instantiate and manage APEX particle related actors manually and
even use individual assets authored via the ParticleEffectTool as well.  One of the additional features afforded by using
'effect packages' is a mechanism to perform level of detail operations using artist/designer 'per effect' settings.


Emitters
========

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 in the following links.

The Simple Shape Emitter Parameters\:

- `APEX Box Emitter Parameters <../_static/build_params/structEmitterGeomBoxParams.html>`_

- `APEX Cylinder Emitter Parameters <../_static/build_params/structEmitterGeomCylinderParams.html>`_

- `APEX Sphere Emitter Parameters <../_static/build_params/structEmitterGeomSphereParams.html>`_

- `APEX Sphere Shell Emitter Parameters <../_static/build_params/structEmitterGeomSphereShellParams.html>`_

The Explicit Particle Position (available in the simple shape emitter) Parameters\:

- `APEX Explicit Emitter Parameters <../_static/build_params/structEmitterGeomExplicitParams.html>`_

The Air/Ground Emitter Parameters\:

- `APEX Air/Ground Emitter Parameters <../_static/build_params/structGroundEmitterAssetParameters.html>`_

The Weapon/Impact Emitter Parameters\:

- `APEX Weapon Emitter Parameters <../_static/build_params/structImpactEmitterAssetParameters.html>`_

IOSes
=====

.. only:: SDKver3X

	Two IOSes exist, the Basic IOS and the PxParticle IOS.  The Basic IOS is implemented within APEX
	as either a CPU or GPU simulation and its purpose is to be a very high performance simulation
	with very high particle counts for Turbulence.  It supports collision with PhysX
	static and dynamic shapes, but these are
	proxied from the PhysX scene and not a native component of the simulation.  The PxParticle IOS
	uses the PhysX 3 particle simulation; either PxParticleSystem or PxParticleFluid, depending on
	the parameters specified in the asset.  If the intent is to have lots of dynamic and static
	collision between the particles, actors, and the environment then this IOS is intended to be used.

IOFX
====

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 in :ref:`iofx-users-guide-label`

Effect Packages
===============

.. only:: SDKver3X

The EffectPackageActor is only available with the PhysX 3.3 SDK and above.  An EffectPacakgeAsset is
authored using the new ParticleEffectTool (PET).  This asset represents a collection of one or more
particle related assets bound into a single easy to use unit.  A single 'EffectPackage' might contain
three emitters, each with different properties, a turbulence grid, and other field samplers such as
jets or attractors.  It could include heat sources and force fields as well.  Each of these sub-elements
can have different timing values controlling when they are created and whether or not they loop, for
how long, and how many times.  Finally an EffectPackage can have artist defined level of detail properties
to control how to control the effect based on distance from the camera and even using screen space culling
as well.


