Replay

These functions allow you to replay a recorded simulation. More...

Data Structures
struct	b2ReplayInfo
	Static metadata describing a recording, resolved once when the player opens the file. More...
struct	b2ReplayQueryInfo
	A spatial query recorded during a replayed frame, exposed for inspection. More...
struct	b2ReplayQueryHit
	One result of a recorded spatial query. More...

Typedefs
typedef struct b2Replay	b2Replay
	Opaque handle for incremental playback of a recording.

Enumerations
enum	b2ReplayQueryType
	The kind of a recorded spatial query, matching the public query and cast functions.

Functions
bool	b2ValidateRecording (const void *data, int size, int workerCount)
	Replay a recording by re-running the engine and asserting recorded ids and state match.
b2Replay *	b2CreateReplay (const void *data, int size, int workerCount)
	Open a recording for incremental playback and replay up to the first step.
void	b2DestroyReplay (b2Replay *player)
	Close a player and free its replay world and file buffer.
bool	b2Replay_StepFrame (b2Replay *player)
	Advance the replay by one recorded step.
b2WorldId	b2Replay_GetWorldId (const b2Replay *player)
	Get the id of the replayed world.
void	b2Replay_Restart (b2Replay *player)
	Rewind the player to the first step, recreating the replay world from the file.
void	b2Replay_SeekFrame (b2Replay *player, int targetFrame)
	Seek to a recorded step.
int	b2Replay_GetFrame (const b2Replay *player)
	Get the number of steps replayed so far.
b2ReplayInfo	b2Replay_GetInfo (const b2Replay *player)
	Get static metadata for the recording (frame count, recorded tuning, time).
bool	b2Replay_IsAtEnd (const b2Replay *player)
	Returns true once the end of the recording has been reached.
bool	b2Replay_HasDiverged (const b2Replay *player)
	Returns true if a recorded state hash failed to reproduce, meaning replay diverged.
int	b2Replay_GetDivergeFrame (const b2Replay *player)
	Get the first step at which replay diverged, or -1 if it has not diverged.
void	b2Replay_SetKeyframePolicy (b2Replay *player, size_t budgetBytes, int minIntervalFrames)
	Tune the keyframe ring used to speed up backward seeking.
size_t	b2Replay_GetKeyframeBudget (const b2Replay *player)
	Get the keyframe memory budget in bytes.
int	b2Replay_GetKeyframeMinInterval (const b2Replay *player)
	Get the finest keyframe spacing in frames.
int	b2Replay_GetKeyframeInterval (const b2Replay *player)
	Get the current keyframe spacing in frames.
size_t	b2Replay_GetKeyframeBytes (const b2Replay *player)
	Get the memory currently held by keyframe snapshots, in bytes.
void	b2Replay_DrawFrameQueries (b2Replay *player, b2DebugDraw *draw, int queryIndex)
	Draw spatial queries recorded during the most recently replayed frame.
int	b2Replay_GetFrameQueryCount (const b2Replay *player)
	Get the number of spatial queries recorded for the most recently replayed frame.
b2ReplayQueryInfo	b2Replay_GetFrameQuery (const b2Replay *player, int index)
	Get a recorded query from the most recently replayed frame by index.
b2ReplayQueryHit	b2Replay_GetFrameQueryHit (const b2Replay *player, int queryIndex, int hitIndex)
	Get one result of a recorded query from the most recently replayed frame.
int	b2Replay_GetBodyCount (const b2Replay *player)
	Get the number of body slots tracked for the outliner.
b2BodyId	b2Replay_GetBodyId (const b2Replay *player, int index)
	Get a tracked body by creation ordinal.

Detailed Description

These functions allow you to replay a recorded simulation.

This functionality is built to serve the replay viewer in the sample app. It is unlikely that any game or application would use these features, so consider them internal.

---

Data Structure Documentation

b2ReplayInfo

struct b2ReplayInfo

Static metadata describing a recording, resolved once when the player opens the file.

Data Fields
b2AABB	bounds	accumulated world bounds over the recording, zero-extent if unavailable
int	frameCount	total recorded steps
float	lengthScale	length units per meter in effect when recorded
int	subStepCount	recorded sub-steps
float	timeStep	dt of the recorded steps
int	workerCount	worker count used for the replay world

b2ReplayQueryInfo

struct b2ReplayQueryInfo

A spatial query recorded during a replayed frame, exposed for inspection.

Data Fields
b2AABB	aabb	overlap AABB, relative to origin
b2QueryFilter	filter	zeroed for the shape local query types
int	hitCount	number of recorded results
b2Pos	origin	query origin
b2ShapeId	shapeId	target shape for the shape local query types
b2Vec2	translation	ray and cast translation
b2ReplayQueryType	type	the query type

b2ReplayQueryHit

struct b2ReplayQueryHit

One result of a recorded spatial query.

Data Fields
float	fraction	the query translation fraction
b2Vec2	normal	the unit normal vector at the hit point
b2Pos	point	the hit point on the shape surface
b2ShapeId	shapeId	the shape hit

Function Documentation

b2CreateReplay()

b2Replay * b2CreateReplay	(	const void *	data,
		int	size,
		int	workerCount )

Open a recording for incremental playback and replay up to the first step.

The player copies the bytes, so you may free or destroy the source buffer immediately after this call.

Parameters

data	Recorded bytes
size	Number of recorded bytes
workerCount	Worker count for the replay world. 0 uses the serial single-worker fallback.

Returns

A player handle, or NULL if the recording is malformed

b2Replay_DrawFrameQueries()

void b2Replay_DrawFrameQueries	(	b2Replay *	player,
		b2DebugDraw *	draw,
		int	queryIndex )

Draw spatial queries recorded during the most recently replayed frame.

Call after b2World_Draw so queries are layered on top of the world.

Parameters

player	A valid player handle
draw	Debug draw callbacks. NULL draw function pointers are skipped.
queryIndex	Index into the frame's queries to draw, or -1 to draw all of them.

b2Replay_GetBodyCount()

int b2Replay_GetBodyCount

(

const b2Replay *

player

)

Get the number of body slots tracked for the outliner.

This is the creation-order span and includes holes for destroyed bodies, so it only grows as the replay advances.

b2Replay_GetBodyId()

b2BodyId b2Replay_GetBodyId	(	const b2Replay *	player,
		int	index )

Get a tracked body by creation ordinal.

Returns b2_nullBodyId for a destroyed slot, an ordinal not yet reached at the current frame, or an out-of-range index. Validate with b2Body_IsValid.

b2Replay_GetKeyframeInterval()

int b2Replay_GetKeyframeInterval

(

const b2Replay *

player

)

Get the current keyframe spacing in frames.

Starts at the min interval and doubles as the ring evicts to stay under budget, so it reflects the effective backward-seek granularity right now.

b2Replay_SeekFrame()

void b2Replay_SeekFrame	(	b2Replay *	player,
		int	targetFrame )

Seek to a recorded step.

Seeking backward rewinds and re-runs from the nearest keyframe. Clamps to the recording bounds.

b2Replay_SetKeyframePolicy()

void b2Replay_SetKeyframePolicy	(	b2Replay *	player,
		size_t	budgetBytes,
		int	minIntervalFrames )

Tune the keyframe ring used to speed up backward seeking.

A keyframe is a periodic snapshot the player restores from instead of replaying from the start, trading memory for seek speed.

Parameters

player	the recording player
budgetBytes	Memory cap for the kept snapshots. The spacing widens to stay under it.
minIntervalFrames	Finest spacing between keyframes, in frames.

b2Replay_StepFrame()

bool b2Replay_StepFrame

(

b2Replay *

player

)

Advance the replay by one recorded step.

Returns

true if a step executed, false once the end of the recording is reached

b2ValidateRecording()

bool b2ValidateRecording	(	const void *	data,
		int	size,
		int	workerCount )

Replay a recording by re-running the engine and asserting recorded ids and state match.

Parameters

data	Recorded bytes.
size	Number of recorded bytes
workerCount	Worker count to use for replay. 0 uses the serial single-worker fallback.

Returns

true if replay completed without divergence, false on any mismatch