Culling and Performance

Limit diagnostic body geometry without changing the physics simulation.

The renderer can skip off-camera or distant managed rigid-body geometry. This is a rendering optimization, not collision filtering or simulation sleeping.

Example#

// Create event.
jolt_debug_enable(true);
jolt_debug_set(JOLT_DEBUG_SHAPES | JOLT_DEBUG_CENTER_OF_MASS, true);
jolt_debug_set_frustum_culling(true);
if (!jolt_debug_set_max_distance(100)) show_debug_message("Invalid distance");

// Draw End event: activate your 3D camera before this call.
jolt_debug_draw();

Culling uses the active view/projection matrices and conservative body bounds. Its scope is managed rigid-body shape/sensor geometry and centre-of-mass diagnostics; do not assume it clips all contacts, vehicles, constraints or retained query history. Objects skipped visually continue to simulate.

What the renderer already optimizes#

Diagnostic lines and primitives are batched. The body pass obtains one packed body snapshot when SHAPES, SENSORS or CENTER_OF_MASS is requested. Static Mesh/HeightField wireframes use a frozen geometry cache; destroying a body invalidates its cached geometry. Buffers are allocated lazily and released during jolt_stop().

// Diagnose an unexpected missing body outline:
jolt_debug_set_frustum_culling(false);
jolt_debug_set_max_distance(-1);
// Compare, then restore your desired limits.

Verified operation contracts#

These contracts distinguish units, return values, errors and lifetime according to the current implementation. Check results: false, 0 and undefined can mean different things for different methods.