Debug Visualization

Introduction

With the PhysX Visual Debugger (see PhysX Visual Debugger (PVD)), NVIDIA offers a tool to record information about simulated PhysX scenes and visualize that information in a remote viewer application. However, sometimes it is preferable to integrate visual debug information directly into the application's view. For that purpose, PhysX provides an interface to extract visual debug information as a set of basic rendering primitives, that is, points, lines, triangles and text. These primitives can then be rendered and overlayed with the application render objects.

Usage

To enable debug visualization, the global visualization scale has to be set to a positive value first:

PxScene* scene = ...
scene->setVisualizationParameter(PxVisualizationParameter::eSCALE, 1.0f);

Then the individual properties that should be visualized can be enabled using, again, a positive value:

scene->setVisualizationParameter(PxVisualizationParameter::eACTOR_AXES, 2.0f);

In the example, the actor world axes will be visualized. The scale used for visualization will be the product of the global scale (1.0 in this example) and the property scale (2.0 in this example). Please note that for some properties the scale factor does not apply: shape geometry, for example, will not be scaled since the size is defined by the user application. Furthermore, for some objects, visualization has to be enabled explicitly on the corresponding object instances too (see PxActorFlag::eVISUALIZATION, PxShapeFlag::eVISUALIZATION, ...).

After a simulation step, the visualization primitives can then be extracted as follows:

const PxRenderBuffer& rb = scene->getRenderBuffer();
for(PxU32 i=0; i < rb.getNbLines(); i++)
{
    const PxDebugLine& line = rb.getLines()[i];
    // render the line
}

Note

Do not extract render primitives while the simulation is running.

The amount of debug visualization data might be too vast to create efficiently for large scenes. In cases where only a localized area is of interest, there is the option to use a culling box for debug visualization via PxScene::setVisualizationCullingBox().

Note that simply enabling debug visualization (PxVisualizationParameter::eSCALE) can have a significant performance impact, even when all the other individual visualization flags are disabled. Thus, make sure debug visualization is disabled in your final/release builds.