Debug Visualization

Introduction

With the OmniPVD (see Omniverse Visual Debugger), 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.getNbPoints(); i++)
{
    const PxDebugPoint& point = rb.getPoints()[i];
    // render the point
}

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

// etc ...

Note

Do not extract render primitives while the simulation is running.
Visualization primitives associated with dynamic actors might seem delayed by one frame when the current step’s primitives are rendered together with the updated actor transforms. This perceived delay results from the computation of debug visualization primitives using the actor transforms at the beginning of the simulation step. The pre-simulation-step transforms ensure the accurate alignment of collision shapes and contact points in the debug visualization, since contacts are generated based on the pre-simulation-step actor transforms.

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.