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

Motivation
----------

The NVIDIA APEX SDK is designed to address three important issues facing game physics:

1.	Significant programmer involvement is required.
2.	Game physics content typically gets designed to the game's "min-spec" system.
3.	Game engine performance limitations. 

The first problem arises because the traditional interface to
middleware physics is an API. It's designed for programmers. These
APIs need to be "general purpose", so they expose a very "low-level"
interface: rigid bodies, shapes, joints, particles, impulses, and
collisions. They are basically, a "toolbox" of all the primitive
components of a physics simulation. This gives the game programmer
a lot of control, but in return, it requires a lot of non-trivial
work. This work requires broad physics programming experience, and
is often not budgeted by game developers. This is similar, in many
ways, to the specialized work of writing an efficient rendering
engine on top of D3D. With graphics, artists don't directly create
vertex buffer objects in the editor, but for physics that's what
physics engine integration requires. Even when authoring tools (like
plug-ins for Max/Maya) are made available to attempt to reduce the
programmer involvement that's required, it's the same "low-level
toolbox" that is exposed to the artists. If the artists want to
create content at a higher level of abstraction - not using these
primitive building blocks - then you're back to requiring a lot of
programmer involvement again.

The second problem arises because there are huge performance
differences between the consoles, and between different generations
of PC CPUs, and GPUs. So, if game developers want their game to
take advantage of higher end hardware, when it's available, to
improve the quality, or scale of their game physics, custom authoring
is required for each platform or hardware configuration. The result
of this is that, in practice, only the "lowest common denominator"
content gets created, and users don't benefit from better hardware.

The third problem arises because many game engines make the assumption
that the world is largely static: that there are many static objects,
but few dynamic objects Therefore, they tend to use very "heavy
weight" data structures for their moving objects: For example: Using
an "Actor" class for each and every crate, barrel, or piece of
debris flying around the level. So even though the physics system
might be able to handle very complex simulations, the overhead of
the game engine (the scene graph, the AI, the rendering) makes it
impossible, in practice, to use more than a few dozen objects in
the level.


The NVIDIA APEX Solution
------------------------

APEX addresses each of the above problems as follows:

1.  **Significant programmer involvement is required to take a
    relatively abstract PhysX-SDK and create a lot of meaningful
    content.**

    APEX provides a high-level interface to artists and content developers.
    This reduces the need for programmer time, adds automatic physics
    behavior to familiar objects, and leverages multiple low-level
    PhysX-SDK features with a single easy-to-use authoring interface.

2.  **Game physics content typically gets designed to the game's
    "min-spec" system.**

    APEX requires each functional module to provide one or more ways
    to "scale the content" when running on better-than-min-spec systems,
    and to do this without requiring a lot of extra work from the game
    developer (artist or programmer, but especially programmer).

3.  **Game engine performance limitations.**

    APEX avoids many of the game engine bottlenecks by allowing the
    designer to identify the physics that is important to the game
    logic, and what can be sent directly to the renderer, bypassing the
    fully generic path through the game engine. It also allows the game
    engine to treat an APEX asset as a single game object, even though
    it may actually comprise many hundreds or even thousands of low-level
    physics components.

The APEX SDK comprises a set of C++ header files that define the
SDK public API, a set of binary libraries that implement the
functionality, as well as documentation of the API and of the
functionality provided. Source code to the libraries may be provided
to certain developers, according to business considerations. The
APEX SDK also includes a set of tools (binary executables and DCC
plugins) for content creation.

The APEX architecture is a modular one. Modules implement intuitive,
specific purpose, high-level physics technology at a level of
abstraction that is appropriate for content creators (artists and
level designers). Modules typically manage multiple physics primitive
elements (e.g.: rigid bodies, shapes, joints, etc..), and may manage
multiple simulation types (e.g.: rigid body, fluid, cloth, soft-body).


Definitions
-----------

**Scalable Content**
    In the context of APEX, content is said to be scalable whenever
    it can adapt to running on a variety of systems with various
    degrees of physics simulation capability (e.g.: CPU, CPU+PPU,
    CPU+GPU, PS3, Xbox360), and demonstrate benefit from running
    on systems with increased physics simulation capability.

**APEX Asset**
    An APEX asset is a data structure that is created at game
    authoring time, can be serialized to non-volatile storage,
    loaded by the APEX run-time, and used to create instances (called
    actors) in the scene.

**APEX Authorable Object**
    An authorable object is a definition of an asset data structure,
    the specification of how it will be authored, the specification
    of the runtime functionality, and the software that implements
    all this. This software includes, at a minimum, an Asset Authoring
    class, an Asset class, and an Actor (or instance) class.

**APEX Module**
    An APEX module is software component, consisting of a group of
    related APEX Authorable Objects. It includes a run-time component
    and an authoring component. The run-time component for each
    APEX Module is shipped as a separate library or DLL. The authoring
    component may be provided by multiple tools, and/or may be
    combined in a single tool with other authoring functionality.

**APEX Framework**
    The APEX Framework comprises all parts of APEX that are not
    Modules. The Framework may contain Authorable Objects.

**APEX Feature**
    An APEX Feature is a group of inter-related APEX Authorable
    Objects that provide functionality to the game developer to
    facilitate the creation of a particular type of scalable content.
    An APEX Feature may span multiple Modules, and may include
    subsets of Modules.

**Scalability**
    The degree to which an APEX Feature enables content created for
    it to adapt to running on a variety of systems with various
    degrees of physics simulation capability, and to demonstrate
    benefit from running on systems with increased physics simulation
    capability.

**Scalable Parameter**
    A member of an APEX asset that is authored as a range of values,
    rather than as a unique value, in order to provide scalability.
    At run-time, a value in the authored range is selected based
    on the capabilities of the system.


Directory Structure
-------------------

The APEX top level directory contains:

:framework:         Everything that's not a module
:module:            APEX module specific code
:shared:            Example source code that may be useful to the developer
:externals:         SDKs used to build the samples applications
:bin:               Platform and SDK version specific DLLs, sample and tool executables
:lib:               Platform and SDK version specific libs
:docs:              Documentation
:samples:           Sample applications
:media:             APEX and rendering assets used for the samples
:NvParameterized:   NvParameterized API
:public:            Foundation and PxTask headers

At the lowest level of the directory hierarchy, the following naming conventions are used:

:.../public:    This is the set of public (external) interface classes which hide underlying implementation. They can be used by any application, by tools, or internal APEX code.
:.../include:   Non-public header files, including classes that implement public interface classes.
:.../src:       Source code.

An APEX binary distribution consists of a set of DLL's (Windows)
and libraries (all platforms) as well as the header files of the
Public API (APEX/framework/public and APEX/module/xx/public). It
will also include tools (executables) and samples (source &
executables).

Each APEX Module and the APEX Framework is in a separate library
(and Windows DLL). An application can thus link (or load) only the
APEX Modules that the application will be using in order to conserve
code space. A further benefit of separate libraries is that it is
easy for NVIDIA or third-party developers to create new APEX Modules
that can be easily used in an existing APEX application.

Version Numbers
---------------

The APEX Framework and all APEX Modules are independently versioned
using a 2-part version number, consisting of a major number and a
minor number, in the format "major.minor", for example: "1.3".

Asset definitions within a module may change from version to version
of the module, but new versions of the AssetAuthoring and
Asset derived classes will support deserializing all old
versions of the asset.


