Initialization

In order to use APEX, the first thing that must be done by the application is to create a single instance of the ApexSDK class:

#include "Apex.h"

    extern PxFoundation*            gFoundation;
extern PxPhysics*           gPhysicsSDK;
extern PxCookingInterface*  gCooking;
extern PxUserOutputStream*  gOutputStream;
ApexSDK*                    gApexSDK;

...

ApexSDKDesc                 apexDesc;
ApexCreateError             errorCode;
apexDesc.outputStream = gOutputStream;
    apexDesc.foundation = gFoundation;
apexDesc.physXSDK = gPhysicsSDK;
apexDesc.cooking = gCooking;
apexDesc.renderResourceManager = new UserRenderResourceManager();

gApexSDK = CreateApexSDK(apexDesc, &errorCode);

The PhysX SDK must have already been initialized, so you that you have a PxPhysics*. Most functionality of APEX is provided directly or indirectly through the ApexSDK class. For example, scene creation and APEX module initialization is performed by calling methods of the ApexSDK class.

Loading Modules

The ApexSDK class provides a single generic public API for loading modules, called createModule(). Providing a single generic API makes it possible for third-parties to develop modules and ship module binaries (libs and DLL’s) that are compatible with a particular version of the APEX SDK and of the PhysX SDK.

The module is identified by its filename, without path and without suffix/extension, which is the first argument to createModule(). The second argument to createModule() is a pointer to an error result. The APEX SDK will ensure that the loaded module matches the APEX and PhysX SDK versions. Module specific parameters, if any, must be passed to the module using a subsequent call to the module’s init() method.

Here is an example:

#include "ApexSDK.h"
#include "ModuleDestructible.h"
#include "NvParamUtils.h"

ModuleDestructible*       gModuleDestructible;

...

ApexCreateError            errorCode;
NvParameterized::Interface* moduleDesc;
#if MODULE_STATIC_LINKED
    instantiateModuleDestructible();
#endif

gModuleDestructible = static_cast<ModuleDestructible*> ( GetApexSDK()->createModule("Destructible", &errorCode) );
PX_ASSERT(gModuleDestructible);

moduleDesc = gModuleDestructible->getDefaultModuleDesc();

NvParameterized::setU16( *moduleDesc, "maxActorCreatesPerFrame", 50 ); // 50 is just a random number for demonstration purposes
gModuleDestructible->init( *moduleDesc );

Creating Scenes

The APEX scene (class Scene) represents a unique physics world in which various types of objects can be instantiated. It mirrors the PhysX SDK PxScene class. An instance of the Scene class should be created for each PxScene in which APEX will be used.

The APEX scene provides a centralized interface for advancing the simulation and accessing the rendering data output from APEX.

The Scene derives from Context, and therefore can contain (or be the context for) APEX actors. In fact, all *asset::create*Actor() methods must take an Scene argument.

The Scene operates in similar fashion to the PhysX SDK scene, however, the APEX scene can exist, and even contain APEX actors, without having an associated PhysX SDK scene. But in order to actually perform simulation in the PhysX SDK, an PhysX scene must be associated with the APEX scene, either by providing a pointer to it in the SceneDesc descriptor structure, or by using the setPhysXScene() method.

Loading Assets

At run-time, asset creation is typically performed by the game engine’s “level loader” using the Named Resource Provider’s user defined ResourceCallback::requestResource() method. The level loader typically processes a set of asset instances that have been placed in the level. At a minimum, the game engine must be capable of storing the following information for each asset instance in the level: name of the asset, the type of the asset, and position and orientation of the instance. For each asset instance found in a level, the level loader should query the NRP to determine whether or not the named asset has been already loaded. It should use the ResourceProvider::getResource() method to do so. If the asset has not been loaded, a callback to ResourceCallback::requestResource() will be immediately triggered to request that the asset be loaded. Either way, getResource() will return a void pointer to the loaded asset that can subsequently be used to create the instance of the asset: the Actor.

Assets use NvParameterized classes to store all of their serialized data. APEX provides a serializer which will serialize and deserialize to either an ASCII XML format or a binary format.

To load APEX assets, the ResourceCallback::requestResource() callback should first create a PxFileBuf data stream using ApexSDK::createStream() for reading the asset from non-volatile storage. In the APEX samples the assets are mapped to a single file and not bundled into packages, though a game engine can interpret an asset name from ::requestResource() however it wishes.

If the APEX default stream implementation is being used (e.g.: the APEX samples), a stream can be created with the ApexSDK::createStream() method:

physx::PxFileBuf* stream = GetApexSDK()->createStream( "asset.xml", physx::PxFileBuf::OPEN_READ_ONLY );

Otherwise, an instance of a user defined stream class (derived from the pure virtual PxFileBuf base class) should be created.

Create the NvParameterized::Serializer, specifying the serialization format (this may or may not be part of the asset name in the callback):

// NvParameterized::Serializer * ApexSDK::createSerializer(NvParameterized::Serializer::SerializeType type)
NvParameterized::Serializer * ser = GetApexSDK()->createSerializer(serType); // serType is either NST_XML or NST_BINARY

You may also specify custom Traits object if you want to change some aspects of serializer behavior (see NvParameterized Guide for more details):

// NvParameterized::Serializer * ApexSDK::createSerializer(NvParameterized::Serializer::SerializeType type, NvParameterized::Traits *traits)
NvParameterized::Serializer * ser = GetApexSDK()->createSerializer(serType, customTraits);

You may determine stream format using ApexSdk::getSerializeType() method:

NvParameterized::Serializer::SerializeType serType = GetApexSDK()->getSerializeType(*stream);
    PX_ASSERT( serType != NvParameterized::SerializeType::NST_LAST );

You may also check target platform for your binary file (e.g. before you do inplace deserialization):

NvParameterized::SerializePlatform platform;
GetApexSDK()->getSerializePlatform(*stream, platform);

if( platform == NvParameterized::SerializePlatform::GetCurrentPlatform() )
    ...

The NvParameterized asset classes must be deserialized using the NvParameterized::Serializer::deserialize() method. The parameters required are the data stream and an instance of the NvParameterized::Serializer::DeserializedData class. All assets which are serialized in the stream will be deserialized and stored as NvParameterized classes which can be accessed through the DeserializedData object.

The NvParameterized class(es) serialized in the PxFileBuf may be accessed from the DeserializedData object and created using the ApexSDK::createAsset(NvParameterized::Interface parameters, const char * name)* method:

const char *assetName; // input parameter in ::requestResource()
Asset *asset;
NvParameterized::Serializer::DeserializedData data;

serializer->deserialize(*stream, data); // assume there is one asset in the stream for this case
NvParameterized::Interface *params = data[0];
asset = GetApexSDK()->createAsset( params, assetName );

The NvParameterized object(s) retrieved from the serializer should not be released or destroyed by the application. The act of creating an asset from an NvParameterized object passes ownership of the object to the asset.

The asset can be released using ApexSDK::releaseAsset() or Asset::release(). If the asset was loaded as a result of manually calling the ResourceCallback::requestResource() callback, then it should be released using ResourceProvider::releaseResource().

AssetAuthoring * ApexSDK::createAssetAuthoring( const char *authorableTypeName );
AssetAuthoring * ApexSDK::createAssetAuthoring( const char *authorableTypeName, const char *name );

// DestructibleAsset.h
#define DESTRUCTIBLE_AUTHORING_TYPE_NAME "DestructibleAsset"

void ApexSDK::releaseAssetAuthoring( AssetAuthoring& );

AssetAuthoring *author; // initialized elsewhere
Asset *asset = GetApexSDK()->createAsset( *author, "uniqueAssetName" );

AssetAuthoring *author; // initialized elsewhere
NvParameterized::Interface* oldInterface = author->releaseAndReturnNvParameterizedInterface();

Asset *asset = GetApexSDK()->createAsset( oldInterface, "uniqueAssetName" );

Asset *asset; // initialized elsewhere
NvParameterized::Interface* oldInterface = asset->getAssetNvParameterized();

// make the copy
NvParameterized::Interface* newInterface = GetApexSDK()->getParameterizedTraits()->createNvParameterized(oldInterface->className());
newInterface->copy( oldInterface );

AssetAuthoring *author = GetApexSDK()->createAssetAuthoring( newInterface, "uniqueAssetAuthoringName" );

Asset *asset; // initialized elsewhere
NvParameterized::Interface* oldInterface = asset->releaseAndReturnNvParameterizedInterface();
AssetAuthoring *author = GetApexSDK()->createAssetAuthoring( oldInterface, "uniqueAssetAuthoringName" );

PxU32 ApexSDK::forceLoadAssets()

Instantiating Actors

Once an asset has been created, de-serialized, and registered with the Named Resource Provider, instantiating it in a scene is done by calling the Asset::createApexActor() method. Additional information, such as its global pose (position and orientation in the scene), that is commonly available to the level loader can be provided in an NvParameterized descriptor data structure that is passed to the createApexActor() method along with a pointer to the APEX Scene:

NvParameterized::Interface * destructibleDesc = asset->getDefaultActorDesc();

/* Set the actor's pose */
NvParameterized::setParamMat44( *destructibleDesc, "globalPose", pose );

/* Create the destructible actor in the APEX scene */
DestructibleActor* actor = asset->createApexActor( *destructibleDesc, *gApexScene );

The Asset classes own the NvParameterized::Interface object that is retrieved from Asset::getDefaultActorDesc(), so there is no need for the application to destroy it.

Named Resource Provider

The Named Resource Provider (NRP) is a public interface class in the APEX Framework (class ApexResourceProvider). It’s purpose is to provide name to address mapping for APEX assets (Asset and derived classes) and for miscellaneous game engine resources that APEX authorable objects refer to by name, such as materials/textures. It also provides a callback interface to allow the application to load the named asset and thus resolve the mapping.

The NRP maintains mappings from a namespace/name pair to a resource pointer. Namespaces and names are both null terminated character strings (char*), and resource pointers are void pointers (void*).

Internally to APEX, a unique integer is associated with every namespace/name pair. This integer is used to efficiently access the current value of a resource pointer, without requiring the NRP to perform string operations everytime the resource pointer is queried.

Every module, when created, creates a new namespace for each type of authorable object (asset) that it implements. The namespace for an authorable object will not be changed, because it is through this name that game developers, as well as other modules, will reference assets of this type.

Whenever any asset is referenced by name (e.g.: when some other asset is loaded), APEX uses the createResource() method to create a mapping from the namespace/name pair to a unique resource identifier. This only needs to be done once, as resource identifiers are permanently (for the lifetime of the APEX SDK) associated with the namespace/name pair. The referencing object should save the assigned resource identifier for subsequent use with the getResource() method to query the current value of the resource pointer. APEX modules must, however, not save the resource pointer for future use. Rather, they must call getResource() every time they need to access the resource pointer. This allows the application to call setResource() at any time to change the value of the resource pointer. When the referencing object is done referencing the resource (e.g.: when the referencing object is deleted), it must call releaseResource(), which will call the ResourceCallback::releaseResource() callback if the number of references is now zero.

The public interface consists of a single method, setResource(), and two callback functions, requestResource() and releaseResource(), that are implemented in a user defined subclass of the pure virtual base class, ResourceCallback. The application may call setResource() at any time, to create a mapping between a namespace/name pair and a resource pointer. This can be safely done before the createNameSpace() or createResource() calls are made by the APEX modules. If the application has not yet called setResource() to create a mapping (for a particular namespace/name pair) when getResource() is called for the first time from within APEX, then the NRP will call the requestResource() callback to request the resource pointer to use for the mapping. The callback must return a value, however, the value may be 0 (NULL). The callback will only be called once for a given namespace/name pair. If the application wants to subsequently change the mapping, it must call setResource(). This may be done as often as the application wishes, and getResource() will always return the correct (most recent) resource pointer. The user class implementing ResourceCallback must be provided in the descriptor when the APEX SDK is initialized, in the call to CreateApexSDK().

#define APEX_COLLISION_GROUP_NAME_SPACE             "NSCollisionGroup"

#define APEX_COLLISION_GROUP_128_NAME_SPACE         "NSCollisionGroup128"

#define APEX_COLLISION_GROUP_MASK_NAME_SPACE        "NSCollisionGroupMask"

#define APEX_MATERIALS_NAME_SPACE                   "ApexMaterials"

#define APEX_PHYSICS_MATERIAL_NAME_SPACE            "NSPhysicalMaterial"

#define APEX_CUSTOM_VB_NAME_SPACE                   "NSCustomVBNames"

Render Mesh Asset

The RenderMeshAsset class, and the associated RenderMeshAssetAuthoring and RenderMeshActor classes, implement a general purpose triangle mesh asset. These classes are provided by the APEX Framework, and can be used, by named reference, or by inclusion by assets in other modules.

The RenderMeshAsset stores a vertex buffer accessible through an VertexBuffer interface. This vertex buffer supports a wide variety of attributes: position, normal, tangent, binormal, color, bone indices, bone weights, and up to 4 sets of [U,V] coordinates. It also supports a variety of formats for each attribute. See Render Mesh Asset Interfaces.

The mesh can be subdivided in two orthogonal ways: by “part” and by “sub-mesh”. Furthermore, each vertex of the mesh can be associated with one or more “bones” (transformation matrices).

Each “part” is a unique subset of the triangles of the mesh for which rendering can be individually enabled or disabled. This is called “visibility”, and is controlled, per instance, using the RenderMeshActor::setVisibility(..) method. A part can span several sub-meshes (see below), such that it can use different materials for different triangles.

Each “sub-mesh” is a unique subset of the vertices and triangles of the mesh that is assigned a particular material name. At run-time, the material name is mapped to a user-defined pointer, using the Named Resource Provider. This pointer is subsequently passed to the rendering engine through the Render Resources Interface. A sub-mesh can contain triangles from many different parts.

Each “bone” is a transform matrix (position, rotation, and scale) that can be used at run-time to transform the position of the vertices of the mesh. Each vertex can be associated with one or more bones using the “bone index” vertex semantic. If a vertex is associated with more than one bone, the “bone weight” semantic is also used to provide a weighting factor that determines the proportion in which the vertex position is transformed by each bone. If all the vertices of a part are associated with a single common bone, the part will be rigid. If they are associated with different bones, the part will be “skinned”.

Render Resources Interface

The APEX Framework provides a standard interface for modules to interface with the game’s rendering engine. The purpose of the interface is to pass data (e.g.: vertex buffers, index buffers, transform buffers) from APEX to the rendering engine for rendering. APEX does not directly render anything (i.e.: no calls to D3D or OpenGL), nor does specify or control how or when things are rendered. It simply seeks to pass data that it generates or updates to the game’s rendering engine in a flexible yet efficient manner.

class Renderable
{
public:
    const PxBounds3& getBounds() const;
    void updateRenderResources();
    void dispatchRenderResources( UserRenderer &renderer, PxReal lod );
}

class UserRenderResourceManager
{
public:
    virtual UserRenderVertexBuffer*   createVertexBuffer( const UserRenderVertexBufferDesc& desc );
    virtual void                        releaseVertexBuffer( UserRenderVertexBuffer& buffer );

    virtual UserRenderIndexBuffer*    createIndexBuffer( const UserRenderIndexBufferDesc& desc );
    virtual void                        releaseIndexBuffer( UserRenderIndexBuffer& buffer );

    virtual UserRenderBoneBuffer*     createBoneBuffer( const UserRenderBoneBufferDesc& desc );
    virtual void                        releaseBoneBuffer( UserRenderBoneBuffer& buffer );

    virtual UserRenderInstanceBuffer* createInstanceBuffer( const UserRenderInstanceBufferDesc& desc );
    virtual void                        releaseInstanceBuffer( UserRenderInstanceBuffer& buffer );

    virtual UserRenderSpriteBuffer*   createSpriteBuffer( const UserRenderSpriteBufferDesc& desc );
    virtual void                        releaseSpriteBuffer( UserRenderSpriteBuffer& buffer );

    virtual UserRenderSurfaceBuffer*  createSurfaceBuffer( const UserRenderSurfaceBufferDesc& desc );
    virtual void                        releaseSurfaceBuffer( UserRenderSurfaceBuffer& buffer );

    virtual UserRenderResource*       createResource( const UserRenderResourceDesc& desc );
    virtual void                        releaseResource( UserRenderResource& resource );
};

// new implementation so the renderer receives all semantics at once
void writeBuffer(const RenderVertexBufferData &data, physx::PxU32 firstVertex, physx::PxU32 numVertices)

class UserRenderer
{
public:
    virtual void renderResource( const RenderContext &context ) = 0;
};

class RenderContext
{
public:
    UserRenderResource   *renderResource;
    PxMat44                 local2world;
    PxMat44                 world2local;
};

MyCachedRenderer renderer;
RenderableIterator *iter = gApexScene->createRenderableIterator();
for( Renderable *r = iter->getFirst() ; r ; r = iter->getNext() )
{
    if( earlyCullCheck( r->getBounds() ) )
        continue;
    r->updateRenderResources();
    r->dispatchRenderResources( renderer, 0 );
}
iter->release();

renderer.render_pass_1();
renderer.render_pass_2();

Renderable *r = getApexRenderable( gameActor );
MyCachedRenderer gRenderer;
r->lockRenderResources();
if ( !earlyCullCheck( r->getBounds() ) )
{
    r->updateRenderResources();
    r->dispatchRenderResources( gRenderer, 0 );
}
r->unlockRenderResources();

Materials

APEX does not “know” anything about render materials. The details of materials and shaders vary so much one renderer to the next, as well as from one game engine to the next. It would be very difficult, if not impossible, to abstract material handling in an useful way.

However, APEX must know something about materials, to the extent that it groups render vertices according to different materials, and informs the application as to which material is to be used with a vertex buffer when render resources are dispatched (see Render Resources Interface). It accomplishes this via the Named Resource Provider, allowing the application to register all materials (as void* pointers or integer handles) by their names. APEX render mesh assets (RenderMeshAsset) group vertices by material, and refer to the materials by name. Before the rendering resources are dispatched to the user for a draw call, those material names are matched to the user’s material handles (void* or integer) using the Named Resource Provider. In this way APEX has an efficient and meaningful way to refer to the material at runtime.

This would be the end of the section on materials, except that APEX has cases where it is its “own customer,” that is, with applications that need to render. One case is for authoring tools, another is for sample or demo applications.

Asynchronous Simulation Interface

Simulation is controlled by the APEX scene. The Scene class implements simulate(), checkResults(), and fetchResults() methods that operate in similar fashion to the corresponding methods of the PhysX SDK PxScene class.

Just as with scene creation, these three simulation methods automatically call the corresponding PhysX SDK methods, eliminating the need for the game to make duplicate calls. Taking control of stepping the PhysX SDK simulations allows APEX modules to perform tasks before, during, and after the PhysX SDK simulation.

In order to do all this, each Scene spawns a new simulation thread, the “APEX scene thread”.

When the game thread calls Scene::simulate(), a signal is sent which unblocks the APEX scene thread. The APEX scene thread then passes through three phases. In each phase, each APEX ModuleScene (see above) is allowed to perform any asynchronous processing that it desires. Furthermore, during the second phase, the PhysX SDK simulation is allowed to proceed, by means of a call to PxScene::simulate(), followed by a call to PxScene::checkResults( block=true ).

The APEX scene in turns passes the execution context to each module in turn.

Buffered API

Changes to the simulation state (calls to “set” methods of the API) must be made before the call to the simulate() method for the timestep(s) in which the changes are to be effective. Changes that are made after the call to simulate() are buffered until simulation completes (i.e.: until fetchResults()). Changes are applied in the order in which the API calls were originally made. This functionality is similar to what is provided by the PxD wrapper for the PhysX SDK, except that the functionality is built-in to APEX rather than being implemented as a wrapper.

Deletion of scenes is also buffered. Deleting a scene during simulation will not take effect until the simulation completes. Even though the deletion is buffered, the application must not make any more API calls that reference the scene, e.g.: don’t call fetchResults().

Calling fetchResults() before a corresponding simulate() call is allowed but does nothing. This avoids the need for the application to do a first-time check when calling fetchResults() for the previous frame immediately before simulate() for the next frame.

View Matrix and the Projection Matrix

The APEX framework provides the following interfaces to allocate, set and get the View Matrix and the Projection Matrix. Setting the View Matrix and the Projection Matrix is manditory since various APEX features such as the Level of Detail and Debug rendering require the data. This interface has been designed to support multiple sets of matrices in order to provide future APEX capabilities for multi-frame games on consoles. The following API are in the APEX scene and may be found in Scene.h.:

// first space must be allocated for the View Matrix and the Projection Matrix
// These calls must be made one time only.
const physx::PxU32 allocViewMatrix(ViewMatrixType::Enum);
const physx::PxU32 allocProjMatrix(ProjMatrixType::Enum);

// Next the transforms must be updated every time their values change
void               setViewMatrix(const physx::PxMat44 & viewTransform, const physx::PxU32 viewID = 0);
void               setProjMatrix(const physx::PxMat44 & projTransform, const physx::PxU32 projID = 0);

// If the View Matrix type is USER_CUSTOMIZED the following call must be made every time the View Matrix is set.
void               setViewParams(const physx::PxVec3 & eyePosition, const physx::PxVec3 & eyeDirection,
                                 const physx::PxVec3 & worldUpDirection = PxVec3(0,1,0),
                                 const physx::PxU32 viewID = 0);
// SetProjParams must be called every time the Projection Matrix is updated.
void               setProjParams(physx::PxF32 nearPlaneDistance, physx::PxF32 farPlaneDistance,
                                 physx::PxF32 fieldOfViewDegree, physx::PxU32 viewportWidth,
                                 physx::PxU32 viewportHeight, const physx::PxU32 projID = 0)

// setUseViewProjMatrix must be called once.  Presently since only one of each matrix is supported
// this function only needs to be called once.
    void               setUseViewProjMatrix(const physx::PxU32 viewID = 0, const physx::PxU32 projID = 0)

NOTE: Presently only one View Matrix and one Projection matrix may be set in each APEX scene. Consequently the projID values for both of the above calls must presently be set to 0 which is the only handle that the alloc functions will return.

When a view matrix is alocated the type must be specified. It may be one of the following:

struct ViewMatrixType
{
    enum Enum
    {
        USER_CUSTOMIZED = 0,
        LOOK_AT_RH,
        LOOK_AT_LH,
    };
};

struct ProjMatrixType
{
    enum Enum
    {
        USER_CUSTOMIZED = 0,
    };
};

If the matrix type is set to LOOK_AT_RH or LOOK_AT_LH the eye position, direction, and world up direction are automatically computed based on a left handed or right handed world. If the type is set to USER_CUSTOMIZED then the eye position must be set using the setProjMatrix API.

If the above calls are not made or are made incorrectly the following error messages will be output to the error stream.

Level of Detail

APEX Modules will frequently implement Level of Detail (LoD) systems. LoD systems are simply algorithms that determine the best way to distribute limited resources over a set of objects in a scene. They typically use criteria such as distance the object from the camera, size of the object, age of the object, or relevance to game-play, to determine the optimal distribution of resources.

APEX LOD defines resources roughly as computational load required to accomplish a task to achieve a certain level of benefit. A high fidelity APEX asset that is near the eye position has greater benefit than one that is located far from the eye position. The APEX modules that participate in the LOD resource distribution calculate sum of the benefits of all of their actors. The LOD system distributes the available resources to the various APEX module scenes based on each modules total benefits and a user supplied weighting for each of the modules. The module weighting feature is provided to allow the LOD system to be tuned based upon the priority that the game developer places on the benefit of the actors that the various modules provide.

The following APIs allows the total resource budget to be set and provides a query to determine the actual resources consumed in the last simulation frame. These functions are in APEX scene and can be found in Scene.h.:

void setLODResourceBudget(physx::PxF32 totalResource);
physx::PxF32 getLODResourceConsumed()

The LOD resource budget should be adjusted based on the system that on which the game is running. On platforms such as Microsoft Windows that support a wide range of CPU and GPU computational capabilities the budget could be set using a slider in a configuration window or perhaps by a benchmark. Since the computational capabilities of any one console type is the same the game developer could set the budget to a fixed value to achieve the desired balance between the fidelity of the simulation and frame rate.

Every APEX module that participates in the APEX LOD resource distribution system computes the benefit of its actors in a module specific way. Setting the module weights both sets the priority and normalizes the benefits. It should be noted that resources and benefit are unique quantities. The resources required to implent an actor at a certain level of fidelity is the same no matter where the actor is located relative to the eye position. However the benefit of the actor will be much higher if it is located directly in front of the user than if the actor was far away and not visible. The resource weight can also be normalized between APEX modules using the same API call. The following APIs allows the benefit and resource weights of a module to be set and retrieved and are defined in Module.h.:

// Sets scaling factors that determine how the units of benefit and resource used by
// this module relate to those of other modules.
void setLODWeights(physx::PxF32 benefitWeight, physx::PxF32 resourceWeight);
// Retrieves the currently used LOD Weights.
void getLODWeights(physx::PxF32 & benefitWeight, physx::PxF32 & resourceWeight);

Further details of how the various APEX modules implement LOD is included in the documentation for each module. Clothing LOD is described here Clothing Physical LOD, and here Clothing Actor Benefit. Destruction LOD features are described in Destruction LOD Scalable Parameters, and Destruction Debug Visualization LOD Features. APEX Particles LOD is documented in APEX Particles LOD.

Scalable Parameters

Each APEX feature has one or more Scalable Parameters. Due to the hierarchical relationship of many Authorable Objects not all Authorable Objects implement a scalable parameter. A Scalable Parameter is the specification of a range of values that is authored and saved in asset. Scalable Parameters may be found in any kind of asset, including those that are only instantiated once per-module or per-module-scene. In other words, a module may define Scalable Parameters that are “global” to the module, or that are authored on a per-scene basis.

Scalable Parameters do not inherently have anything to do with Level of Detail(LoD), but they can be used to configure various LoD settings. For example, a simple LoD system might simulate the N most important widgets in the scene, while leaving the remaining widgets static. In such a scenario N is a Scalable Parameter.

Ownership of PhysX SDK Objects

The APEX SDK provides a mechanism for the application to make queries about PhysX SDK objects, such as Actors, that have been created by APEX. For example:

void myOnContactNotify(ContactPair & pair, PxU32 events)
{
    const PhysXObjectDesc *desc0 = GetApexSDK()->getPhysXObjectInfo(pair[0]);
    const PhysXObjectDesc *desc1 = GetApexSDK()->getPhysXObjectInfo(pair[1]);

    if (desc0)
    {
        if (desc0->getActor()->getOwner()->getObjectTypeID() == gModuleDestructible->getModuleID())
        {
            DestructibleActor *da = static_cast<DestructibleActor*> (desc0->getActor());
            //...
        }
    }
}

Serialization

Serialization is the process by which APEX assets are saved (serialized) by an authoring tool and loaded (de-serialized) by the APEX run-time.

Every APEX Authorable Object defines a set of data that makes up the serialized asset in an NvParameterized class. The NvParameterized::Serializer class serializes and deserializes using the PxFileBuf interface for I/O. APEX provides both a file and memory buffer based implementation of PxFileBuf, retrieved with ApexSDK::createStream() and ApexSDK::createMemory[Read, Write]Stream(), respectively.

The NvParameterized::Serializer can output XML formatted assets, which are useful for smaller assets where a user might want to do hand editing or tweaking. The serializer can also output platform-specific binary assets, which are significantly smaller and deserialize much more quickly. Binary assets can be serialized for any platform and deserialized on any platform, but if the target platform matches the current platform, the Serializer::deserializeInplace() method may be used to perform in-place deserialization, which is significantly faster than the traditional method of processing an asset one parameter at a time.

Asset Preview

Before creating an asset preview, the NvParameterized preview descriptors have to be set. Specific details on descriptor parameters can be found in their respective module’s programmers guides. The following code illustrates the general steps in creating an asset preview.

Errors and Warnings

The APEX Framework outputs the following error and warning messages using the standard APEX error stream.