Draw distance slider (#44)

Helps render performance on integrated GPUs.
Added render culling for baked compounds.
This commit is contained in:
Erin Catto 2026-07-03 20:26:19 -07:00 • committed by GitHub
commit 1bec63c9ee
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 200 additions and 8 deletions

View file

@ -160,7 +160,8 @@ void* MyEnqueueTask(b3TaskCallback* task, void* taskContext,
MyTask* t = AllocTask();
t->task = task;
t->taskContext = taskContext;
SubmitToThreadPool(t);
Scheduler* myScheduler = (Scheduler*)userContact;
SubmitToThreadPool(myScheduler, t);
return t;
}
@ -175,6 +176,7 @@ void MyFinishTask(void* userTask, void* userContext)
b3WorldDef worldDef = b3DefaultWorldDef();
worldDef.enqueueTask = MyEnqueueTask;
worldDef.finishTask = MyFinishTask;
worldDef.userTaskContext = myScheduler;
worldDef.workerCount = GetMyWorkerCount();
```

View file

@ -139,6 +139,7 @@ the first time of impact (TOI). Second, speculative collision is used to create
contact constraints between bodies before they touch.
### events
World simulation leads to the creation of events that are available at the end
of the time step:
@ -150,6 +151,7 @@ of the time step:
These events allow your application to react to changes in the simulation.
## Modules
Box3D's primary purpose is to provide rigid body simulation. However,
there are math and collision features that may be useful apart from the
rigid body simulation. These are provided in the `include` directory. Anything
@ -162,6 +164,7 @@ study the code and ask questions. I'm happy to share all the details of how
Box3D works internally.
## Units
Box3D works with floating point numbers and tolerances have to be used
to make Box3D perform well. These tolerances have been tuned to work
well with meters-kilogram-second (MKS) units. In particular, Box3D has
@ -194,6 +197,7 @@ the full 3D rotation is tracked continuously.
> Box3D uses radians, not degrees.
## Changing the length units
Advanced users may change the length unit by calling `b3SetLengthUnitsPerMeter()`
at application startup. If you keep Box3D in a shared library, you will need
to call this if the shared library is reloaded.
@ -204,6 +208,7 @@ One of the benefits of using MKS units for physics simulation is that you can
use real world values to get reasonable results.
## Ids and Definitions
Fast memory management plays a central role in the design of the Box3D
interface. When you create a world, body, shape or joint, you will receive
a handle called an *id*. These ids are opaque and are passed to various functions

View file

@ -19,6 +19,7 @@
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#define BOX3D_USER_SHAPE_CAPACITY 65536
#define BOX3D_FREELIST_END ( -1 )
@ -79,9 +80,15 @@ typedef struct
DebugSphere sphere;
DebugCapsule capsule;
DebugMesh geom;
// firstChild walks every child. To draw only the visible ones the
// compound tree is queried by child index, so keep the source data
// and a childIndex to pool slot map alongside the list head.
struct
{
int firstChild;
const b3CompoundData* data;
int* childMap;
int childMapCount;
} compound;
};
} DebugShape;
@ -115,6 +122,14 @@ typedef struct
b3DebugDraw guiDraw;
bool transparentDynamic;
// View box for compound child culling, world space, refreshed once per frame.
b3AABB viewBounds;
bool hasViewBounds;
// Compound children appended vs total this frame. Diagnostic readout.
int lastCompoundAppended;
int lastCompoundTotal;
} AdapterState;
static AdapterState s_adapter;
@ -145,6 +160,10 @@ void InitAdapter( void )
s_adapter.selectedShapeId = b3_nullShapeId;
s_adapter.transparentDynamic = false;
s_adapter.hasViewBounds = false;
s_adapter.lastCompoundAppended = 0;
s_adapter.lastCompoundTotal = 0;
s_adapter.guiDraw = b3DefaultDebugDraw();
s_adapter.guiDraw.drawShapes = true;
}
@ -161,6 +180,13 @@ void ResetAdapterPool( void )
{
ReleaseMeshReference( us->geom.handle );
}
else if ( us->kind == Box3DUS_Compound )
{
// A scene switch can sweep the pool before the destroy callback fires,
// so free the child map here too.
free( us->compound.childMap );
us->compound.childMap = NULL;
}
us->kind = Box3DUS_Free;
us->nextFree = ( i + 1 < BOX3D_USER_SHAPE_CAPACITY ) ? ( i + 1 ) : BOX3D_FREELIST_END;
}
@ -172,6 +198,10 @@ void ResetAdapterPool( void )
s_adapter.selectedBodyId = b3_nullBodyId;
s_adapter.selectedShapeId = b3_nullShapeId;
s_adapter.transparentDynamic = false;
s_adapter.hasViewBounds = false;
s_adapter.lastCompoundAppended = 0;
s_adapter.lastCompoundTotal = 0;
}
b3DebugDraw* GetGuiDraw( void )
@ -210,6 +240,25 @@ bool GetTransparentDynamic( void )
return s_adapter.transparentDynamic;
}
void SetViewBounds( b3AABB bounds )
{
s_adapter.viewBounds = bounds;
s_adapter.hasViewBounds = true;
// Called once per frame ahead of the draw walk, so clear the child tally here.
s_adapter.lastCompoundAppended = 0;
s_adapter.lastCompoundTotal = 0;
}
int GetLastCompoundDrawStats( int* outTotal )
{
if ( outTotal != NULL )
{
*outTotal = s_adapter.lastCompoundTotal;
}
return s_adapter.lastCompoundAppended;
}
void SetGroundShape( b3ShapeId shapeId )
{
s_adapter.groundShapeId = shapeId;
@ -595,12 +644,26 @@ static void* AdapterCreateDebugShape( const b3DebugShape* debugShape, void* cont
DebugShape* us = &s_adapter.pool[index];
us->kind = Box3DUS_Compound;
PopulateCommonFields( us, debugShape );
us->compound.firstChild = -1;
// Flatten the children once. The fixed pool never relocates, so the
// parent pointer stays valid while children are allocated.
const b3CompoundData* compound = debugShape->compound;
const int total = compound->capsuleCount + compound->hullCount + compound->meshCount + compound->sphereCount;
// Keep the source data for the cull query and map each tree child index to
// its pool slot. A NULL map falls back to walking every child.
us->compound.firstChild = -1;
us->compound.data = compound;
us->compound.childMapCount = total;
us->compound.childMap = ( total > 0 ) ? (int*)malloc( (size_t)total * sizeof( int ) ) : NULL;
if ( us->compound.childMap != NULL )
{
for ( int i = 0; i < total; ++i )
{
us->compound.childMap[i] = -1;
}
}
int prev = -1;
for ( int i = 0; i < total; ++i )
{
@ -610,6 +673,10 @@ static void* AdapterCreateDebugShape( const b3DebugShape* debugShape, void* cont
{
continue; // skip a child we couldn't register, keep the rest
}
if ( us->compound.childMap != NULL )
{
us->compound.childMap[i] = childIndex;
}
if ( prev < 0 )
{
us->compound.firstChild = childIndex;
@ -650,6 +717,8 @@ static void DestroyDebugShape( void* userShape, void* context )
FreeDebugShape( ci );
ci = next;
}
free( us->compound.childMap );
us->compound.childMap = NULL;
}
else if ( us->kind == Box3DUS_Hull || us->kind == Box3DUS_Mesh || us->kind == Box3DUS_HeightField )
{
@ -703,6 +772,44 @@ static void AppendResolvedShape( const DebugShape* us, b3Transform baseTransform
}
}
// Context for the compound cull query. Carries the resolved material and the
// body relative transform so each visited child appends exactly as the full
// walk would.
typedef struct
{
const DebugShape* parent;
b3Transform shapeRelative;
Vec4 color;
float metallic;
float roughness;
TransparentShadowCast shadowCast;
HighlightKind hk;
int appended;
} CompoundCullContext;
// The compound tree stores child indices. Remap to the pool slot the flatten
// pass assigned, then append the child under the body transform.
static bool CompoundCullCallback( int proxyId, uint64_t userData, void* context )
{
(void)proxyId;
CompoundCullContext* ctx = (CompoundCullContext*)context;
const int childIndex = (int)userData;
if ( childIndex < 0 || childIndex >= ctx->parent->compound.childMapCount )
{
return true;
}
const int slot = ctx->parent->compound.childMap[childIndex];
if ( slot < 0 )
{
return true; // child could not be registered at create
}
const DebugShape* child = &s_adapter.pool[slot];
b3Transform base = b3MulTransforms( ctx->shapeRelative, child->childTransform );
AppendResolvedShape( child, base, ctx->color, ctx->metallic, ctx->roughness, ctx->shadowCast, ctx->hk );
ctx->appended += 1;
return true;
}
static bool DrawShape( void* userShape, b3WorldTransform shapeTransform, b3HexColor color, void* context )
{
(void)context;
@ -760,10 +867,45 @@ static bool DrawShape( void* userShape, b3WorldTransform shapeTransform, b3HexCo
if ( us->kind == Box3DUS_Compound )
{
for ( int ci = us->compound.firstChild; ci != -1; ci = s_adapter.pool[ci].nextChild )
bool cull = s_adapter.hasViewBounds && us->compound.data != NULL && us->compound.childMap != NULL;
b3AABB viewRel = s_adapter.viewBounds;
if ( cull )
{
b3Transform base = b3MulTransforms( shapeRelative, s_adapter.pool[ci].childTransform );
AppendResolvedShape( &s_adapter.pool[ci], base, c, metallic, roughness, shadowCast, hk );
// Shift the view box into the draw origin frame the primitives render in.
b3Pos origin = GetDrawOrigin();
viewRel.lowerBound = b3SubPos( b3ToPos( s_adapter.viewBounds.lowerBound ), origin );
viewRel.upperBound = b3SubPos( b3ToPos( s_adapter.viewBounds.upperBound ), origin );
// If the whole compound sits inside the view the query returns every child,
// so walking the list is cheaper. Both boxes are in the draw origin frame.
b3AABB rootRel = b3AABB_Transform( shapeRelative, b3DynamicTree_GetRootBounds( &us->compound.data->tree ) );
if ( b3AABB_Contains( viewRel, rootRel ) )
{
cull = false;
}
}
if ( cull )
{
// Rotate the view box into compound local space to query the child tree.
b3AABB localCull = b3AABB_Transform( b3InvertTransform( shapeRelative ), viewRel );
CompoundCullContext ctx = { us, shapeRelative, c, metallic, roughness, shadowCast, hk, 0 };
b3DynamicTree_Query( &us->compound.data->tree, localCull, ~0ull, false, CompoundCullCallback, &ctx );
s_adapter.lastCompoundAppended += ctx.appended;
s_adapter.lastCompoundTotal += us->compound.childMapCount;
}
else
{
for ( int ci = us->compound.firstChild; ci != -1; ci = s_adapter.pool[ci].nextChild )
{
b3Transform base = b3MulTransforms( shapeRelative, s_adapter.pool[ci].childTransform );
AppendResolvedShape( &s_adapter.pool[ci], base, c, metallic, roughness, shadowCast, hk );
}
s_adapter.lastCompoundAppended += us->compound.childMapCount;
s_adapter.lastCompoundTotal += us->compound.childMapCount;
}
}
else

View file

@ -37,6 +37,14 @@ void SetShapeMaterial( b3ShapeId shapeId, Vec4 color, float metallic, float roug
void SetTransparentDynamic( bool enabled );
bool GetTransparentDynamic( void );
// View box for compound child culling, world space. Set once per frame before
// b3World_Draw. A compound then submits only the children overlapping this box
// instead of walking its entire child set.
void SetViewBounds( b3AABB bounds );
// Children appended in the last draw, and the total across drawn compounds.
int GetLastCompoundDrawStats( int* outTotal );
void SetSelectedBody( b3BodyId bodyId );
void SetSelectedShape( b3ShapeId shapeId );
void ClearSelection( void );

View file

@ -78,6 +78,7 @@ Camera::Camera()
, m_fov( 60.0f * DEG_TO_RAD )
, m_near( 0.1f )
, m_far( kViewDistance )
, m_drawDistance( kViewDistance )
, m_speed( 10.0f )
, m_width( 0 )
, m_height( 0 )

View file

@ -133,6 +133,12 @@ public:
m_far = far;
}
// Draw/cull box half extent around the eye, in meters. Drives DrawBounds.
void SetDrawDistance( float meters )
{
m_drawDistance = meters;
}
// Recomputes the projection. Call after any SetFov / SetClip change, or
// when the target framebuffer aspect changes outside Update().
void RebuildProj( float aspect );
@ -164,11 +170,11 @@ public:
}
// Cull box for b3World_Draw, in simulation space (length units): a cube of the
// view distance centered on the simulation eye, so the draw set matches the far
// plane reach. The broad phase is queried in length units, hence the scale.
// draw distance centered on the simulation eye. The broad phase is queried in
// length units, hence the scale.
b3AABB DrawBounds() const
{
float h = kViewDistance * m_lengthUnitsPerMeter;
float h = m_drawDistance * m_lengthUnitsPerMeter;
b3Vec3 r = { h, h, h };
return b3OffsetAABB( { b3Neg( r ), r }, DrawOrigin() );
}
@ -182,6 +188,10 @@ public:
float m_near;
float m_far;
// Half extent of the draw/cull box around the eye (meters). Independent of the
// far plane, so it shrinks the draw set without touching the projection.
float m_drawDistance;
// Fly-mode translation speed, m/s. Scroll-tunable while right-mouse held.
float m_speed;

View file

@ -373,6 +373,7 @@ static void OnFrame( void )
// frame tracks load/unload without extra wiring. Live samples sit at 1 unit per
// meter, leaving the transform identity.
camera.SetRenderTransform( b3GetLengthUnitsPerMeter(), s_context.viewZUp );
camera.SetDrawDistance( s_context.drawDistance );
// Sync the draw origin to the camera eye once per frame, before any drawing. This must hold even
// for samples that drive their own Step without calling Sample::Step. Render re-syncs after Step

View file

@ -102,6 +102,7 @@ void SampleContext::Save()
fprintf( file, " \"exposure\": %g,\n", GetExposure() );
fprintf( file, " \"sunStrength\": %g,\n", GetSun().strength );
fprintf( file, " \"debugView\": %d,\n", debugView );
fprintf( file, " \"drawDistance\": %g,\n", drawDistance );
fprintf( file, " \"showHullEdges\": %s,\n", GetEdgeOverlayParams().showHulls ? "true" : "false" );
fprintf( file, " \"showEdgeConvexity\": %s,\n", GetEdgeOverlayParams().showEdgeConvexity ? "true" : "false" );
fprintf( file, " \"replayKeyframeBudgetMB\": %d,\n", replayKeyframeBudgetMB );
@ -237,6 +238,15 @@ void SampleContext::Load()
buffer[count] = 0;
debugView = b3ClampInt( (int)strtol( buffer, nullptr, 10 ), 0, 4 );
}
else if ( jsoneq( data, &tokens[i], "drawDistance" ) == 0 )
{
int count = tokens[i + 1].end - tokens[i + 1].start;
assert( count < 32 );
const char* s = data + tokens[i + 1].start;
strncpy( buffer, s, count );
buffer[count] = 0;
drawDistance = b3ClampFloat( strtof( buffer, nullptr ), 1.0f, Camera::kViewDistance );
}
else if ( jsoneq( data, &tokens[i], "showHullEdges" ) == 0 )
{
const char* s = data + tokens[i + 1].start;
@ -491,6 +501,9 @@ void Sample::Step()
// around the simulation eye, matching the broad-phase tree and the far plane.
debugDraw.drawingBounds = m_camera->DrawBounds();
// Same view box drives compound child culling in the adapter.
SetViewBounds( debugDraw.drawingBounds );
ApplyGuiFlags( &debugDraw );
b3World_Draw( m_worldId, &debugDraw, B3_DEFAULT_MASK_BITS );
@ -1643,6 +1656,9 @@ static void DrawMenuBar( SampleContext* context )
}
ImGui::Separator();
ImGui::MenuItem( "Diagnostics", "M", &context->showMetrics );
ImGui::PushItemWidth( 8.0f * fontSize );
ImGui::SliderFloat( "Draw Distance", &context->drawDistance, 10.0f, Camera::kViewDistance, "%.0f m" );
ImGui::PopItemWidth();
ImGui::Separator();
if ( ImGui::BeginMenu( "Scale" ) )
{

View file

@ -56,6 +56,7 @@ struct SampleContext
float hertz = 60.0f;
float recycleDistance = 0.05f;
float drawDistance = 100.0f; // meters, view/cull box half extent, persisted
int subStepCount = 4;
int workerCount = 1;
bool transparentDynamic = false;

View file

@ -1,6 +1,7 @@
// SPDX-FileCopyrightText: 2025 Erin Catto
// SPDX-License-Identifier: MIT
#include "gfx/debug_adapter.h"
#include "gfx/draw.h"
#include "human.h"
#include "mesh_loader.h"
@ -696,6 +697,10 @@ public:
int treeBytes = b3DynamicTree_GetByteCount( &m_compound->tree );
int height = b3DynamicTree_GetHeight( &m_compound->tree );
DrawTextLine( "compound tree byte count = %d, height = %d", treeBytes, height );
int total = 0;
int drawn = GetLastCompoundDrawStats( &total );
DrawTextLine( "compound children drawn = %d / %d", drawn, total );
}
void Step() override

View file

@ -571,6 +571,7 @@ public:
MakeDebugDraw( &debugDraw );
ApplyGuiFlags( &debugDraw );
debugDraw.drawingBounds = m_camera->DrawBounds(); // view-distance box in length units around the eye
SetViewBounds( debugDraw.drawingBounds );
// Drive the shared outline highlight from the selection. A shape selection outlines that
// shape alone, a body selection outlines the whole body. Set before the draw so the mask