diff --git a/docs/foundation.md b/docs/foundation.md index f8a9b58..316fcf5 100644 --- a/docs/foundation.md +++ b/docs/foundation.md @@ -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(); ``` diff --git a/docs/overview.md b/docs/overview.md index dd488e9..7e14fc2 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -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 diff --git a/samples/gfx/debug_adapter.c b/samples/gfx/debug_adapter.c index 04d4430..1be0198 100644 --- a/samples/gfx/debug_adapter.c +++ b/samples/gfx/debug_adapter.c @@ -19,6 +19,7 @@ #include #include #include +#include #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 diff --git a/samples/gfx/debug_adapter.h b/samples/gfx/debug_adapter.h index e421150..cf28f3e 100644 --- a/samples/gfx/debug_adapter.h +++ b/samples/gfx/debug_adapter.h @@ -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 ); diff --git a/samples/host/camera.cpp b/samples/host/camera.cpp index fdb32f2..47cdfd8 100644 --- a/samples/host/camera.cpp +++ b/samples/host/camera.cpp @@ -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 ) diff --git a/samples/host/camera.h b/samples/host/camera.h index 4ece431..dd91efc 100644 --- a/samples/host/camera.h +++ b/samples/host/camera.h @@ -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; diff --git a/samples/main.cpp b/samples/main.cpp index c97cd8b..1ccb5a6 100644 --- a/samples/main.cpp +++ b/samples/main.cpp @@ -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 diff --git a/samples/sample.cpp b/samples/sample.cpp index bd2f815..6ef0bc2 100644 --- a/samples/sample.cpp +++ b/samples/sample.cpp @@ -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" ) ) { diff --git a/samples/sample.h b/samples/sample.h index 3281fd3..cce7f29 100644 --- a/samples/sample.h +++ b/samples/sample.h @@ -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; diff --git a/samples/sample_compound.cpp b/samples/sample_compound.cpp index 126c3d1..a994797 100644 --- a/samples/sample_compound.cpp +++ b/samples/sample_compound.cpp @@ -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 diff --git a/samples/sample_replay.cpp b/samples/sample_replay.cpp index 30e1b3b..42671de 100644 --- a/samples/sample_replay.cpp +++ b/samples/sample_replay.cpp @@ -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