Pull model task API (#228)

Port the pull model task API from Box2D.

https://github.com/erincatto/box2d/pull/1133

Addresses discussion #150
This commit is contained in:
Erin Catto 2026-11-17 16:42:52 -08:00 • committed by GitHub
commit 1767150df4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
24 changed files with 2048 additions and 406 deletions

View file

@ -56,6 +56,13 @@ B3_API bool b3World_IsValid( b3WorldId id );
/// accuracy. Usually 4.
B3_API void b3World_Step( b3WorldId worldId, float timeStep, int subStepCount );
/// The pull model for tasking. Instead of getting task callbacks from b3World_Step you can call
/// this to kick off a step and get an array of tasks to execute.
B3_API b3TaskBatch b3World_BeginStep( b3WorldId worldId, float timeStep, int subStepCount );
/// Call this after executing each task batch. The step is done when the batch is empty.
B3_API b3TaskBatch b3World_ContinueStep( b3WorldId worldId );
/// Call this to draw shapes and other debug draw data
B3_API void b3World_Draw( b3WorldId worldId, b3DebugDraw* draw, uint64_t maskBits );

View file

@ -37,11 +37,6 @@ B3_API float b3GetLengthUnitsPerMeter( void );
/// The compound barrel benchmark has minor overflow with 24 colors
#define B3_GRAPH_COLOR_COUNT 24
/// The maximum number of contact manifolds between shape pairs. Excess manifolds are dropped using heuristics until
/// this number is reached. Culling can lead to contact dither across time steps. Contact recycling mitigates the
/// dithering.
#define B3_MAX_MANIFOLDS 8
/// A small length used as a collision and constraint tolerance. Usually it is
/// chosen to be numerically significant, but visually insignificant. In meters.
/// @warning modifying this can have a significant impact on stability
@ -103,6 +98,11 @@ B3_API float b3GetLengthUnitsPerMeter( void );
/// The maximum number of restitution iterations. Needed to avoid a solver overflow.
#define B3_MAX_RESTITUTION_ITERATIONS 63
/// The maximum number of contact manifolds between shape pairs. Excess manifolds are dropped using heuristics until
/// this number is reached. Culling can lead to contact dither across time steps. Contact recycling mitigates the
/// dithering.
#define B3_MAX_MANIFOLDS 8
/// The maximum number of contact points between two touching shapes.
/// The default and minimum is 4 and this case uses a fast approximate hull to reduce the
/// point count. A larger value builds a 2D convex hull of the candidate points and then

View file

@ -14,6 +14,24 @@
#define B3_DEFAULT_CATEGORY_BITS UINT64_MAX
#define B3_DEFAULT_MASK_BITS UINT64_MAX
/// The task type for the pull model.
/// @ingroup world
typedef enum b3TaskType
{
b3_taskPairs, ///< Finding pairs of potentially colliding shapes. The broad-phase.
b3_taskCollide, ///< Computing contact manifolds. The narrow-phase.
b3_taskTreeRebuild, ///< Rebuilding the bounding volume hierarchy. A long running side task.
b3_taskIslandSplit, ///< Splitting an island in order to let an island sleep.
b3_taskSolver, ///< Solving constraints.
b3_taskFinalize, ///< Updating body transforms and shape bounding boxes.
b3_taskContinuous, ///< Continuous collision detection.
b3_taskSensors, ///< Sensor overlaps and events.
b3_taskTypeCount ///< The type count.
} b3TaskType;
/// Helper to get a string for a task type.
B3_API const char* b3GetTaskTypeName( b3TaskType type );
/// Task interface
/// This is the prototype for a Box3D task. Your task system is expected to run this callback on a
/// worker thread, exactly once per enqueue, passing back the same taskContext pointer supplied to
@ -29,9 +47,9 @@ typedef void b3TaskCallback( void* taskContext );
/// @param task the Box3D task to be called by the scheduler
/// @param taskContext the Box3D context object that the scheduler must pass to the task
/// @param userContext the scheduler context object that is opaque to Box3D
/// @param taskName the Box3D task name that the scheduler can use for diagnostics
/// @param taskType the task type that the scheduler can use for diagnostics
/// @ingroup world
typedef void* b3EnqueueTaskCallback( b3TaskCallback* task, void* taskContext, void* userContext, const char* taskName );
typedef void* b3EnqueueTaskCallback( b3TaskCallback* task, void* taskContext, void* userContext, b3TaskType taskType );
/// Finishes a user task object that wraps a Box3D task. This must block until the task has
/// completed. The step blocks here on the tasks it spawned, so b3World_Step holds its stack across
@ -40,9 +58,48 @@ typedef void* b3EnqueueTaskCallback( b3TaskCallback* task, void* taskContext, vo
/// do not call b3World_Step from inside a job: a job that blocks on its own sub-jobs without
/// yielding its thread can deadlock. The in-tree scheduler instead runs other pending tasks on the
/// waiting thread.
/// This callback is optional. Without it b3World_Step waits on an internal semaphore that the last
/// task of each phase signals, which suits task systems that can launch work but cannot wait on a
/// single task.
/// @ingroup world
typedef void b3FinishTaskCallback( void* userTask, void* userContext );
/// A task in the pull model.
/// @ingroup world
typedef struct b3Task
{
/// The task function.
b3TaskCallback* fcn;
/// The context that must be passed to the task function.
void* context;
/// The task type. Informational.
b3TaskType type;
/// Is this task deferred? This indicates that this task must be joined
/// at a later stage instead of immediately before the next stage.
/// @see b3TaskBatch::joinTasks
bool deferred;
} b3Task;
/// A batch of tasks for the pull model.
/// @ingroup world
typedef struct b3TaskBatch
{
/// The regular tasks that must be executed in this stage.
const b3Task* tasks;
/// The task count.
int count;
/// Earlier tasks that must now be joined before the next stage.
const b3Task* joinTasks;
/// The join task count.
int joinCount;
} b3TaskBatch;
typedef struct b3DebugShape b3DebugShape;
/// The user needs to be able to create debug draw shapes for multi-pass rendering to work
@ -209,7 +266,7 @@ typedef struct b3WorldDef
/// function to spawn task
b3EnqueueTaskCallback* enqueueTask;
/// function to finish a task
/// function to finish a task. Blocks and helps make progress.
b3FinishTaskCallback* finishTask;
/// User context that is provided to enqueueTask and finishTask
@ -615,6 +672,7 @@ typedef struct b3Counters
int satCallCount; ///<
int satCacheHitCount; ///<
int taskCount; ///<
int enqueueCount; ///<
int colorCounts[24]; ///<
int manifoldCounts[B3_MAX_MANIFOLDS]; ///<