Manages a simulation scene that steps asynchronously using the SuperDex Physics worker pool. More...

#include <mochi_async_scene.h>

Public Member Functions
virtual void	CancelActorQuery (ActorHandle actor, QueryHandle handle)=0
	Cancel a query previously registered with an actor.
virtual void	CancelCallback (CallbackHandle handle)=0
	Cancel a previously registered callback.
virtual AsyncStepParams	GetAsyncStepParams () const =0
	Get the parameters controlling async stepping behavior.
virtual Context *	GetContext ()=0
	Get the Context that owns this AsyncScene.
virtual bool	IsPaused () const =0
	Check if the simulation is currently paused.
virtual void	Pause (bool shouldPause)=0
	Pause or unpause the simulation.
virtual void	QueueActorCommand (ActorHandle actor, std::function< void(Actor *)> callback)=0
	Queue a command to operate on a specific actor on the simulation thread.
virtual void	QueueCommand (std::function< void(Scene *)> callback)=0
	Queue a command to execute on the simulation thread before the next step.
virtual QueryHandle	RegisterActorQuery (ActorHandle actor, QueryType type, bool forceCompute=false)=0
	Register a query with an actor.
virtual CallbackHandle	RegisterPostStepCallback (std::string_view debugName, std::function< void(StepInfo const &)> callback, int priority=Scene::kDefaultCallbackPriority)=0
	Register a callback to execute after each simulation step.
virtual CallbackHandle	RegisterPreStepCallback (std::string_view debugName, std::function< void(StepInfo const &)> callback, int priority=Scene::kDefaultCallbackPriority)=0
	Register a callback to execute before each simulation step.
virtual void	RequestStepThenPause ()=0
	Advance the simulation by exactly one step, then pause.
virtual void	SetAsyncStepParams (AsyncStepParams const &params, Error &error)=0
	Set the parameters controlling async stepping behavior.
virtual void	WaitForQueuedCommands ()=0
	Block the calling thread until all previously queued commands have executed.

Protected Member Functions
virtual	~AsyncScene ()=default
	Don't delete the AsyncScene pointer. Call Context::DestroyAsyncScene.

Detailed Description

Manages a simulation scene that steps asynchronously using the SuperDex Physics worker pool.

AsyncScene wraps a synchronous Scene and automatically steps it using a long-lived simulation task executed by the SuperDex Physics worker pool, decoupling physics updates from the main thread. This enables real-time interactive simulations where physics rate is independent of rendering rate.

Note: In general, commands to modify the scene are queued and executed before the next simulation step.; Thread-safe as long as the synchronous Scene and Actor APIs are only accessed within callbacks.; Outside of callbacks, store ActorHandle (not Actor*).; The AsyncScene owns its underlying Scene.

Warning: Concurrent access to the underlying Scene outside of callbacks is illegal.

Definition at line 39 of file mochi_async_scene.h.

Constructor & Destructor Documentation

◆ ~AsyncScene()

virtual superdex::AsyncScene::~AsyncScene ( )

protectedvirtualdefault

Don't delete the AsyncScene pointer. Call Context::DestroyAsyncScene.

Member Function Documentation

◆ CancelActorQuery()

virtual void superdex::AsyncScene::CancelActorQuery	(	ActorHandle	actor,
		QueryHandle	handle )

pure virtual

Cancel a query previously registered with an actor.

Parameters

[in]	actor	Handle of the actor.
[in]	handle	QueryHandle from RegisterActorQuery.

See also: RegisterActorQuery, Actor::CancelQuery

◆ CancelCallback()

virtual void superdex::AsyncScene::CancelCallback ( CallbackHandle handle )

pure virtual

Cancel a previously registered callback.

Parameters

[in] handle CallbackHandle from RegisterPreStepCallback or RegisterPostStepCallback.

Note: Can be called from any thread.

See also: RegisterPreStepCallback, RegisterPostStepCallback

◆ GetAsyncStepParams()

virtual AsyncStepParams superdex::AsyncScene::GetAsyncStepParams ( ) const

nodiscardpure virtual

Get the parameters controlling async stepping behavior.

Returns: Current async step parameters.

See also: SetAsyncStepParams, AsyncStepParams

◆ GetContext()

virtual Context * superdex::AsyncScene::GetContext ( )

nodiscardpure virtual

Get the Context that owns this AsyncScene.

Returns: Pointer to the owning Context.

◆ IsPaused()

virtual bool superdex::AsyncScene::IsPaused ( ) const

nodiscardpure virtual

Check if the simulation is currently paused.

Returns: True if paused, false if not paused.

Note: When called from the simulation thread, returns the actual pause state. When called from other threads, returns the most recently requested pause state to present a consistent state to the calling thread.

See also: Pause

◆ Pause()

virtual void superdex::AsyncScene::Pause ( bool shouldPause )

pure virtual

Pause or unpause the simulation.

Parameters

[in] shouldPause True to pause, false to unpause.

Note: When paused, simulation does not step but queued commands will still execute.

See also: IsPaused, RequestStepThenPause

◆ QueueActorCommand()

virtual void superdex::AsyncScene::QueueActorCommand	(	ActorHandle	actor,
		std::function< void(Actor *)>	callback )

pure virtual

Queue a command to operate on a specific actor on the simulation thread.

Parameters

[in]	actor	Handle of the actor to operate on.
[in]	callback	Function to execute. Receives Actor* when executed.

Note: Callback only fires if the actor still exists when processed.; Provides direct access to the synchronous Actor API.

See also: QueueCommand, WaitForQueuedCommands

◆ QueueCommand()

virtual void superdex::AsyncScene::QueueCommand ( std::function< void(Scene *)> callback )

pure virtual

Queue a command to execute on the simulation thread before the next step.

Parameters

[in] callback Function to execute. Receives Scene* when executed.

Note: Executed before the next simulation step when Scene access is safe.; When using lambdas, capture by value or use WaitForQueuedCommands to ensure object lifespan.

See also: WaitForQueuedCommands, QueueActorCommand

◆ RegisterActorQuery()

virtual QueryHandle superdex::AsyncScene::RegisterActorQuery	(	ActorHandle	actor,
		QueryType	type,
		bool	forceCompute = false )

pure virtual

Register a query with an actor.

Parameters

[in]	actor	Handle of the actor to register the query with.
[in]	type	Type of query to register.
[in]	forceCompute	If true, compute the query result immediately on the simulation thread upon registration, rather than waiting for the next simulation step. Useful when the actor does not simulate (e.g., a static actor or a paused scene).

Returns: QueryHandle for the registered query, or an invalid handle if actor is invalid.

Note: Can be called from any thread.; May be more convenient than calling QueueActorCommand because it returns the QueryHandle synchronously.

See also: CancelActorQuery, Actor::RegisterQuery, Actor::RegisterQueryAndCompute

◆ RegisterPostStepCallback()

virtual CallbackHandle superdex::AsyncScene::RegisterPostStepCallback	(	std::string_view	debugName,
		std::function< void(StepInfo const &)>	callback,
		int	priority = Scene::kDefaultCallbackPriority )

nodiscardpure virtual

Register a callback to execute after each simulation step.

Parameters

[in]	debugName	Descriptive name for debugging and profiling.
[in]	callback	Callback function to execute.
[in]	priority	Execution order. Lower values execute first (higher priority).

Returns: CallbackHandle for the registered callback.

Note: Callbacks run sequentially on the simulation thread, in increasing priority order (lower values first).; Can be called from any thread.

See also: CancelCallback, RegisterPreStepCallback

◆ RegisterPreStepCallback()

virtual CallbackHandle superdex::AsyncScene::RegisterPreStepCallback	(	std::string_view	debugName,
		std::function< void(StepInfo const &)>	callback,
		int	priority = Scene::kDefaultCallbackPriority )

nodiscardpure virtual

Register a callback to execute before each simulation step.

Parameters

[in]	debugName	Descriptive name for debugging and profiling.
[in]	callback	Callback function to execute.
[in]	priority	Execution order. Lower values execute first (higher priority).

Returns: CallbackHandle for the registered callback.

Note: Callbacks run sequentially on the simulation thread, in increasing priority order (lower values first).; Can be called from any thread.

See also: CancelCallback, RegisterPostStepCallback

◆ RequestStepThenPause()

virtual void superdex::AsyncScene::RequestStepThenPause ( )

pure virtual

Advance the simulation by exactly one step, then pause.

Note: Works even if the simulation is already paused.; Uses AsyncStepParams::fixedTimeStepSeconds even when dynamic-time-step mode is configured. If AsyncStepParams::timeStepCallback is set and returns a non-negative value, the callback's value is used instead.; Useful for debugging frame-by-frame.

See also: Pause, AsyncStepParams::fixedTimeStepSeconds, AsyncStepParams::timeStepCallback

◆ SetAsyncStepParams()

virtual void superdex::AsyncScene::SetAsyncStepParams	(	AsyncStepParams const &	params,
		Error &	error )

pure virtual

Set the parameters controlling async stepping behavior.

Parameters

[in]	params	Async step parameters to set.
[in,out]	error	Error status. Check Error::IsOK for success.

Note: Changes take effect on the next simulation step.

See also: GetAsyncStepParams, AsyncStepParams

◆ WaitForQueuedCommands()

virtual void superdex::AsyncScene::WaitForQueuedCommands ( )

pure virtual

Block the calling thread until all previously queued commands have executed.

Warning: It is illegal to call from the simulation thread.

See also: QueueCommand, QueueActorCommand

The documentation for this class was generated from the following files:

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~AsyncScene()

Member Function Documentation

◆ CancelActorQuery()

◆ CancelCallback()

◆ GetAsyncStepParams()

◆ GetContext()

◆ IsPaused()

◆ Pause()

◆ QueueActorCommand()

◆ QueueCommand()

◆ RegisterActorQuery()

◆ RegisterPostStepCallback()

◆ RegisterPreStepCallback()

◆ RequestStepThenPause()

◆ SetAsyncStepParams()

◆ WaitForQueuedCommands()