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:
parent
8f3b2e12eb
commit
1767150df4
24 changed files with 2048 additions and 406 deletions
|
|
@ -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 );
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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]; ///<
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue