.. APEX Emitter Users Guide

============================
APEX Emitter Users Guide
============================

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


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

The Emitter library allows the artist to control how physical particles are injected into a scene.  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) inside their shape.  The sphere shell emitter emits 
particles within the shell of a specified thickness around a sphere.  The final shape emitter is the explicit emitter outputs 
particles at explicit user defined locations.  The Air / Ground Emitters are special purpose emitters that emit particles 
relative to the ground.  Finally the Weapon Impact Emitter outputs particles in response to a collision or an explosion.

APEX Emitter Authoring Parameters Overview
==========================================

Common Parameters
-----------------
All APEX emitter actors have common parameters that the user may author that control general characteristics of any emitter.  
These parameters control features of the both the particles and the emitter itself.  Most of these parameters are authored 
as a range.  For any particular actor at any one moment the aspect controlled by the parameter can be anywhere within the range
controlled by a random value.  The level of detail (LOD) parameters are also common among all emitters. All of these parameters
are documented further here\:

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

Shape Emitters
--------------

.. TODO  verify the following with the artists

The various shape emitters (box, sphere, sphere shell) emit particles in their shapes.  Box emitters can be used to create effects
such as water dripping from a ceiling or fog or smoke being emitted from a duct.  The sphere emitter and the sphere shell emitter
can be used to create symmetric explosion effects with particles emanating outward from the sphere.  The sphere shell emitter can 
also be used to create implosion effects.  The explicit emitter provides the greatest flexibility of all of the shape emitters 
providing the ability to specify on a point by point basis the locations where particles are emitted.

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>`_


Air / Ground Emitters
---------------------

Air Emitter
###########

Air emitters can be used to produce effects such as leaves falling from trees, or fog.

Ground Emitter
##############
A typical ground emitter emits leaves or debris into an outdoor level. Ground emitter actors can be located at a static location or can
be attached to the player actor as he moves around the level.  The advantage of attaching ground emitter actors to the player is that the
particles will only be emitted around the actor where they can be seen.  Attaching the ground emitter actor to the player makes it unnecessary 
to have a very large actor that emits particles over most or all of a level only to have LOD constantly delete them thus greatly reducing the
overhead.  Ground emitters ray cast against the terrain every frame to find where to place new particles to maintain the authored particle density.
Ground emitters can adapt to the type of terrain that they are in via a callback mechanism.  For instance in a forest leaves could be emitted 
while on a road dust or gravel could be emitted.

The Ground Emitter Parameters are listed and documented here\:

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

Weapon/Impact Emitter
=====================

The APEX Weapon/Impact Emitter is intended to output particles as a reaction to impacts from weapons.  The author may select the typical
particle emitter parameters such as density, lifetime, initial speed range and also select the angle that the particles will be emitted 
at with respect to the weapons impact angle.  The angle impact angle may be authored to be either incident, normal, or a reflection of
the impact angle.

The Weapon/Impact Emitter Parameters are listed and documented here\:

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

APEX Emitter Preview Rendering
==============================

APEX Emitter Preview Rendering consists of a bounding box of the particular emitter and a ray that is used to indicate where the center of the
emitter is located.

- `APEX Emitter Preview Rendering Parameters <../_static/build_params/structEmitterAssetPreviewParameters.html>`_

APEX Emitter Debug Rendering
============================

APEX Emitter Debug Rendering is similar in appearance to the preview rendering for the same type of emitter.  The main item displayed for 
the debug rendering of APEX Emitters is the bounding box of the particular emitter.  Thus for a Box emitter a box is drawn and for a 
sphere emitter a sphere is drawn.

- `APEX Emitter Debug Rendering Parameters <../_static/build_params/structEmitterDebugRenderParams.html>`_
