Getting Started

A good place to start is the SimpleDestruction sample application in APEX/samples. This demonstrates asset loading, instancing, fluid debris specification, and very importantly has a sample user renderer implementation (see the APEX Framework documentation).

This section highlights the main points of the SimpleDestruction sample.

An Apex application needs to first initialize PhysX. In what follows, it will be assumed that a PhysX SDK has been created (see the PhysX documentation):

PxPhysics* m_physxSDK;
PxFoundation* m_foundation;
m_foundation = PxCreateFoundation(PX_PHYSICS_VERSION, ...);
m_physxSDK = PxCreatePhysics( ... );
PxInitExtensions(*m_physxSDK);

... and that we have a cooking library:

PxCookingParams params;
PxCooking* m_cooking;
m_cooking = PxCreateCooking(PX_PHYSICS_VERSION, m_physicsSDK->getFoundation(), params);

After initializing the PhysX SDK, an APEX application needs to initialize the Apex SDK. See the APEX Framework documentation.

This is done as follows:

/* Fill out the Apex SDK descriptor */
ApexSDKDesc apexDesc;

/* Apex needs an allocator and error stream.  By default it uses those of the PhysX SDK. */

/* Let Apex know about our PhysX SDK and cooking library */
apexDesc.physXSDK              = m_physxSDK;
apexDesc.cooking               = m_physxCooking;
apexDesc.outputStream          = pxErrorStream;

/* Our custom render resource manager */
apexDesc.renderResourceManager = m_renderResourceManager;

/* Our custom named resource handler */
apexDesc.resourceCallback      = m_resourceCallback;

/* Some debug renderer materials */
apexDesc.wireframeMaterial = "materials/simple_unlit.xml";
apexDesc.solidShadedMaterial = "materials/simple_lit_color.xml";

/* Finally, create the Apex SDK */
m_apexSDK = CreateApexSDK(apexDesc);
PX_ASSERT(m_apexSDK);

In the block above we assume we have a named resource provider m_renderResourceManager. SimpleDestruction is built on top of SampleFramework, which provides a class SampleApexRenderResourceManager for this purpose. It provides a name-to-object look-up for various resources, including destructible assets, apex render mesh assets, and material IDs.

Also, the render resource manager m_resourceCallback is used. This is also provided in SampleFramework. This class allows the user to customize the creation of render resources (such as vertex buffers). If you are using apex in an application that does not render (such as a commandline conversion utility), you may use the APEX-provided class NullRenderResourceManager in shared/external/include/NullRenderer.h.

You must also create an Scene, to hold APEX actors and renderables. This is initialized using the PhysX scene. The PhysX scene is created in the usual manner:

PxScene* m_physxScene;
...
/* Create PhysX scene */
physx::PxSceneDesc sceneDesc(scale);
sceneDesc.gravity = physx::PxVec3(0,-9.8f,0);
...
m_physxScene = m_physxSDK->createScene(sceneDesc);

... and the APEX scene:

/* Create an APEX scene from a PhysX scene */
Scene* m_apexScene;

...

SceneDesc sceneDesc;
sceneDesc.scene = m_physxScene;
m_apexScene = gApexSDK->createScene( sceneDesc );

An Apex application then needs to create the Apex modules it will use. These modules will populate the APEX scene with representations of their objects, and also populate the PhysX scene with corresponding physics objects.

The Destruction Module

This link describles all of the Destruction Module Parameters.

Create the destruction module (class ModuleDestructible) using

ModuleDestructible* m_apexDestructibleModule;

...

m_apexDestructibleModule = static_cast<ModuleDestructible*>(m_apexSDK->createModule("Destructible"));

and then initialize it using its default parameters:

NvParameterized::Interface* params = m_apexDestructibleModule->getDefaultModuleDesc();
m_apexDestructibleModule->init(*params);

Note, if you wish to set some parameters to non-default values, you may do so using the NvParameterized interface.

Destructible actors (DestructibleActor) may use the APEX Particles for particle system debris. This is initialized using the particle, iofx, and emitter modules:

m_apexParticlesModule = static_cast<ModuleParticles*>(m_apexSDK->createModule("BasicIOS"));
NvParameterized::Interface* params = m_apexParticlesModule->getDefaultModuleDesc();
m_apexParticlesModule->init(*params);

m_apexIofxModule = static_cast<ModuleIofx*>(m_apexSDK->createModule("IOFX"));
NvParameterized::Interface* params = m_apexIofxModule->getDefaultModuleDesc();
m_apexIofxModule->init(*params);

m_apexEmitterModule = static_cast<ModuleEmitter*>(m_apexSDK->createModule("Emitter"));
NvParameterized::Interface* params = m_apexEmitterModule->getDefaultModuleDesc();
m_apexEmitterModule->init(*params);

With that, the Apex Destruction is ready to use.

Destructible Assets

This link describles all of the Destructible asset parameters.

To create a destructible, first a destructible asset (DestructibleAsset) needs to be created or loaded. PhysXLab provides an easy way to create DestructibleAssets. These can then be saved in either a binary or an ASCII (XML) format. The asset type may be determined by peeking into the file stream, so the file extension does not matter. The current file name convention is that the .apb extension is used for binary format, and .apx for the ASCII format.

In this example we will load an DestructibleAsset from the file “Wall.apb”. To load APEX assets, create an PxFileBuf using the ApexSDK::createStream method. Assuming we have our working directory set up so that “fullpath” is the path to our asset directory,

physx::PxFileBuf* stream = m_apexSDK->createStream( "fullpath/Wall.apb", physx::PxFileBuf::OPEN_READ_ONLY );

... creates the necessary stream. This function returns NULL if the stream cannot be created. To determine the format from the stream, peek into it using:

char peekData[32];
stream->peek(peekData, 32);
NvParameterized::Serializer::SerializeType iSerType = m_apexSDK->getSerializeType(peekData, 32);

Then create a serializer for the serialization type iSerType:

NvParameterized::Serializer* ser = m_apexSDK->createSerializer(iSerType);

And load the asset using the deserialize method:

NvParameterized::Serializer::DeserializedData data;
NvParameterized::Serializer::ErrorType serError = ser->deserialize(*stream, data);

The data structure now contains pointers to one or more APEX assets, depending on how many were in the stream. Assuming there is only one in the stream, use

NvParameterized::Interface *params = data[0];
Asset* asset = m_apexSDK->createAsset( params, "Asset Name" );

The second parameter a name you can used to refer to the asset later. To use the destructible asset api for this asset, cast the pointer to an DestructibleAsset:

DestructibleAsset* destructibleAsset = static_cast<DestructibleAsset*>( asset );

Destructible Actors

This link describles all of the Destructible actor parameters.

Creating a destructible actor from a destructible asset is very simple if you use the default parameters (class DestructibleParameters) that are stored with the destructible asset.

One piece of additional information that you’re almost certainly going to want to change is the initial global pose for the destructible, which we’ll assume we have in the PxMat44 pose.

First, get the default actor description parameters from the asset:

NvParameterized::Interface* descParams = destructibleAsset->getDefaultActorDesc();

To modify the global pose, use

NvParameterized::setParamMat44( *descParams, "globalPose", pose );

Then simply use the descriptor, along with the APEX scene, to create an DestructibleActor instance of the DestructibleAsset:

Actor* actor = asset->createApexActor( *descParams, apexScene );

Again, to use the DestructibleActor API, typecast actor:

DestructibleActor* destructibleActor = static_cast<DestructibleActor*>( actor );

In general, you’ll need to set more fields of the Destructible actor parameters. Notably,

• dynamic (BOOL) determines if the destructible starts off life as dynamic (in which case it cannot take part in any support structure). Default is false, giving a static destructible.
• scale (PxVec3) scales the DestructibleActor instance, possibly non-uniformly. Default is PxVec3(1,1,1), the identity scaling. You’ll probably want to have all scales that the application will use set in the DestructibleAsset’s precached cooking scales before the asset is serialized to file or stream. The Destruction authoring tool can set these scales for you. If you don’t precache the cooking scales, destruction will still work, but the cooking for the collision hulls will happen during run time.

Finally, there are many parameters you may set in destructibleParameters. These set how much damage it takes to fracture a destructible, whether or not damage can come from impact, and many more things. A full description is given in the PhysXLab documentation.

const NvParameterized::Interface* stateParams = actor->getNvParameterized( DestructibleParameterizedType::State );

NvParameterized::Serializer* ser = m_apexSDK->createSerializer( NvParameterized::SerializeType::NST_BINARY );
...
physx::PxFileBuf* outStream      = m_apexSDK->createStream( "fullpath/ActorSavedState.apb", physx::PxFileBuf::OPEN_WRITE_ONLY );
...
NvParameterized::Serializer::ErrorType serError = ser->serialize( *outStream, stateParams, 1 );

NvParameterized::Serializer* ser = m_apexSDK->createSerializer( NvParameterized::SerializeType::NST_BINARY );
...
physx::PxFileBuf* inStream       = m_apexSDK->createStream( "fullpath/ActorSavedState.apb", physx::PxFileBuf::OPEN_READ_ONLY );

NvParameterized::Serializer::DeserializedData data;
NvParameterized::Serializer::ErrorType serError = ser->deserialize( *inStream, data );
...
NvParameterized::Interface* stateParams = data[0];
Actor* actor = asset->createApexActor( *stateParams, apexScene );
...
stateParams->destroy();

Actor* actor = asset->createDestructibleActor( stateParams, apexScene );

actor->setNvParameterized( stateParams );

/* Set the shapes' groupsMask */
NvParameterized::setParamU32( *descParams, "p3ShapeDescTemplate.simulationFilterData.word0", 2 );
NvParameterized::setParamU32( *descParams, "p3ShapeDescTemplate.simulationFilterData.word0", ~0 );

/* Set the shapes' density */
NvParameterized::setParamF32( *descParams, "p3BodyDescTemplate.density", 10.0f );

Destructible Synchronization

For the purpose of allowing synchronization of the destructed state of actors across different processes in real-time, APEX Destruction presents a scaled-down alternative to full actor state serialization and deserialization. This method exposes only enough data to synchronize between actors at a customizable combination of detail.

module->setSyncParams( userDamageEventHandler, userFractureEventHandler, userChunkMotionHandler );

callbackFoo->onWriteBegin( bufferStart, bufferSize );
callbackFoo->onWriteDone( headerCount );

callbackFoo->onPreProcessReadBegin( bufferStart, bufferSize, continuePointerSwizzling );
callbackFoo->onPreProcessReadDone( headerCount );

callbackFoo->onReadBegin( bufferStart );
callbackFoo->onReadDone( debugMessage );

actor->setSyncParams( userActorID, actorSyncFlags, actorSyncState, chunkSyncState)

actor->setHitChunkTrackingParams( flushHistory, startTracking, trackingDepth );
actor->getHitChunkHistory( hitChunkContainer, hitChunkCount );
actor->forceChunkHits( hitChunkContainer, hitChunkCount , removeChunks );
actor->setDeleteFracturedChunks( inDeleteChunkMode );

actor->setHitChunkTrackingParams( flushHistory, startTracking, trackingDepth );

actor->getHitChunkHistory( hitChunkContainer, hitChunkCount );

actor->forceChunkHits( hitChunkContainer, hitChunkCount , removeChunks );

actor->setDeleteFracturedChunks( inDeleteChunkMode );

actor->setSyncParams( userActorID, actorSyncFlags, actorSyncState, chunkSyncState);

actorSyncFlags |= CopyDamageEvents;
actorSyncState = new DestructibleActorSyncState;
actorSyncState->damageEventFilterDepth = 2;

actor->setSyncParams( userActorID, actorSyncFlags, actorSyncState, chunkSyncState);

actorSyncFlags |= ReadDamageEvents;

Runtime Fracturing

In APEX 1.3 and later, the destruction module includes an option for runtime fracturing. That is, fracturing is performed on the fly, with no precalculation of the fractured pieces. To enable runtime fracturing, set both the CRUMBLE_SMALLEST_CHUNKS and CRUMBLE_VIA_RUNTIME_FRACTURE flags in the destructible parameters. With these flags set, the deepest-level prefractured chunks (those with no children) will continue to be fractured using the runtime system.

If you want the entire destructible to runtime fractured, simple create a destructible asset from a mesh, with no prefracturing, and set the aforementioned flags. One thing to note, however, is that the runtime fracture system is activated exactly when crumbles would be, that is, only when a deepest-level chunk takes enough damage to be fractured further. When there is only one chunk, this means the chunk would need to first take enough damage to break free (if it’s static), then enough to fracture further to crumbles or runtime fracture. This essentially doubles the damage it needs to take to fracture. To prevent this, you may set the minimumFractureDepth (in the destructible parameters) to one more than the deepest depth, meaning fracturing will begin with crumbles or runtime fracture. So, if you import a single-chunk destructible for runtime fracture, set minimumFractureDepth to 1 (since there is only a depth-0 chunk).

This fracture mode also comes in two types: full and partial. Since a fracture pattern is a decomposition of all of space, when applied to a mesh it will cut the entire mesh into pieces. Partial fracture means that beyond a given radius, the pieces are sewn back together, so that the only fragments seen are the ones within the given radius. We have merged this into the prefracture system by using the radius obtained from applyRadiusDamage. This radius is used for the partial fracture mode in realtime fracturing of chunks.

Scene 9 in SimpleDestruction demonstrates runtime fracture on a thin sheet, with a glass fracture pattern.

Fracture Callbacks

Sometimes it is useful to have information about chunks which are fractured loose, or destroyed completely. For example the user may wish to generate sound or particle effects associated with the fracture event. APEX Destruction facilitates this with the UserChunkReport. The user must derive their own class from this virtual base class and implement the onDamageNotify function. After doing this, pass an instance of the derived class to the destruction module using the ModuleDestructible method

virtual void         setChunkReport(UserChunkReport* chunkReport) = 0;

Once a frame, if fractures occurred since the last frame, then the onDamageNotify function will be called with information stored in an DamageEventReportData structure. (See DamageEventReportData.) This gives general information about the chunks which broke free or were destroyed, as well as a detailed list of chunks if the chunks’ hierarchical depth is at or below a maximum depth set by the ModuleDestructible method

virtual void         setChunkReportMaxFractureEventDepth(physx::PxU32 chunkReportMaxFractureEventDepth) = 0;

Chunks contribute to the DamageEventReportData for various reasons, enumerated in the ChunkFlag::Enum enum. This not only allows the user to respond to the fracture event based upon the reason (the ChunkFlag is in the ChunkData for each explicitly-listed chunk), but it also allows for filtering of the chunks which contribute to the report. By setting a flag mask using the ModuleDestructible method

virtual void         setChunkReportSendChunkStateEvents(bool chunkReportSendChunkStateEvents) = 0;

If enabled, once a frame during simulate, the onStateChangeNotify callback is called with a list of chunks that have changed their visibility state, including their current state. This allows for event based updates of the chunk representation in the application.

virtual void         setChunkReportBitMask(physx::PxU32 chunkReportBitMask) = 0;

only fracture events with ChunkFlag flags that overlap (boolean ‘and’) the given mask will contribute.

Automatic LOD - Destructible Benefit and Cost Functions

See the APEX Framework documentation section “APEX Automatic LOD” for the general introduction to APEX LOD.

The destruction module uses two factors to determine an DestructibleActor’s benefit: angular size, and age. Unlike the “solid angle” importance function described in the LOD section of the framework documentation, the angular size calculation only takes into account a linear arc size subtended by the actor from the point of view of the camera location. In this way the importance falls off linearly with distance, not with the square of the distance as with the solid angle, and therefore the benefit does not fall off as quickly.

The age benefit is calculated using the linear ramp-down described in the framework LOD section.

The LOD parameters are set through the DestructibleActor function

virtual void setLODWeights(PxF32 maxDistance, PxF32 distanceWeight, PxF32 maxAge, PxF32 ageWeight, PxF32 bias)

The parameters are described below.

• maxDistance: beyond this distance, the distance importance function D(r) is zero. D(r) is clamped for decreasing r so that it never grows above 1.
• distanceWeight: the coefficient in front of the distance importance function D(r).
• maxAge: beyond this time, the distance importance function A(t) is zero. A(t) is clamped so that A(t) = 1.
• ageWeight: the coefficient in front of the age importance function A(t).
• bias: a constant bias to increase or decrease an actor’s benefit.

The total benefit for an actor is calculated using:

B(r,t) = distanceWeight*D(r) + ageWeight*A(t) + bias.

The weights should total 1, and the bias should be kept in the unit [0,1] range. This keeps the benefit function B(r,t) “normalized,” so that it’s on the order of one or less.

Rendering Considerations

virtual DestructibleRenderable* acquireRenderableReference()

switch(renderer->getDriverType())
{
case SampleRenderer::Renderer::DRIVER_DIRECT3D9:
case SampleRenderer::Renderer::DRIVER_DIRECT3D11:
        renderer->setEnableVTF(true);
}

Debug Visualization

All APEX modules come with debug visualization rendering, to help understand what is happening in an APEX scene. When you hit the V key in SimpleDestruction, default APEX visualization rendering is turned on, as well as default PhysX SDK visualization. In addition to the default settings, APEX Destruction LOD benefits and support visualization are shown.

Click here for a list of the Destructible debug visualization parameters

For general information on how to use debug visualization within APEX, please see Debug Visualization.

Starting SimpleDestruction and repeatedly hitting ‘V’ (for visualization) and ‘G’ (to hide meshes) will show a subset of the debug visualization options for APEX render meshes and destructible actors. The sample may look slightly different in its current form, but the debug visualization walk-through offered here is still valuable.

Here you see the PhysX collision representation of the scene, as well as the destructible’s support structure. The white circles on the ground represent the collision plane, while the orange box represents the collision volume of the wall. It is a single volume since the wall is not yet damaged. The blue boxes on the ground outline the support chunks in the wall. The support depth for this asset is set at depth = 2, and the outlined chunks are the depth-2 chunks that touch a static actor (the ground plane) in the PhysX scene. Since “World overlap” support is selected in the asset, these chunks become support chunks. All chunks touching them, and chunks touching those chunks, and so on, are supported. This is represented by the network of blue lines, drawn between the centers of each chunk that gains support from a supported neighbor, and that supported neighbor’s center.

Once we apply some damage to the wall, freeing chunks at depth 2 or deeper, those chunks cease to be supported, and this modifies the support network:

Once enough chunks have been removed from the support network to form an island of chunks that don’t contain a supported chunk, that island becomes free, and breaks off whole:

Level of Detail (LOD) benefit and cost are also displayed. The green squares represent the benefit of a chunk island. The benefit is proportional to the area. If the square is large enough, the benefit value is shown in the square. Braking off some chunks you can see the benefits changing as the chunk islands age, and as they fill different areas of the screen:

Chunk island benefit is a function of both the age of chunk and the screen area percentage it fills. Both have adjustable prefactors, as well as an exponential decay factor for the age. Therefore each new chunk island that forms starts with a certain benefit which decays over time, settling on a benefit that only depends on screen area percentage.

In LOD calculations the benefit of each chunk is weighed against its cost. The cost is simply the calculated as the number of chunks times a factor which can be set by the user. This cost is compared with a total budget given to the destruction module. That budget and the total cost of the chunks in the scene are plotted in the bar on the bottom. The bar is scaled so that half the width of the screen represents the total budget. Chunk costs are summed up (stacked) on that bar. The cost of all “essential” chunks is shown as a blue bar. These are the chunks that are not deeper than the “essential depth” set for the destructible asset. Essential chunks will never be removed from the scene from LOD considerations. For example, game play logic or experience may require this.

On top of the essential chunk cost is a yellow bar representing the non-essential chunk cost. If the total cost is less than the budget, the remainder of the budget bar is plotted in white. If the total cost exceeds the budget, the overrun is plotted in red and will extend to the right-half of the screen. Budget overrun can occur if the essential chunk cost exceeds the budget. Also, miscalculations (due to approximations in budget prediction) may cause a temporary budget overrun, which will be corrected in subsequent frames.

If the budget is exceeded by non-essential chunks, or is predicted to be (due to a new fracture event), then the destruction LOD system goes to work and either reduces the detail of fracturing from the fracture event, or removes low-benefit chunks. This is done in order of increasing benefit/cost, until the budget is satisfied or all chunks are essential.

When a chunks is removed to satisfy resource budget, a red square with an “X” across it is displayed temporarily in its place, to show where the removal occurred.

Other visualization options are available. For example, you can view the chunk island poses (local coordinate systems), if you set the VISUALIZE_DESTRUCTIBLE_FRAGMENT_POSE visualizer flag. An example of this is shown here:

Errors and Warnings

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