- Generated by
1.9.4
|
Avara3D 0.2.0
C++ API reference
|
Drives host updates, fixed-step simulation, and rendering for a Scene. More...
#include <a3d/Runner.h>
Classes | |
| struct | UpdateInfo |
| Timing information supplied to each host update callback. More... | |
Public Types | |
| enum class | State { Idle , Running , Stopped } |
| Runner lifecycle states. More... | |
| using | UpdateCallback = std::function< void(Runner &runner, const UpdateInfo &info)> |
| Callback invoked near the beginning of each host update. More... | |
Public Member Functions | |
| Runner (Scene &scene, SimulationConfig config={}) | |
Creates an idle Runner for scene. More... | |
| void | start () |
| Starts the Runner using the current monotonic time. More... | |
| bool | update () |
| Performs one host update using the current monotonic time. More... | |
| void | stop () |
| Permanently stops the Runner and clears pending requested steps. More... | |
| bool | simulationPaused () const |
| Returns true when automatic simulation stepping is paused. More... | |
| void | simulationPaused (bool paused) |
| Pauses or resumes automatic simulation stepping. More... | |
| void | requestSimulationStep () |
| Queues one fixed-duration simulation step while paused. More... | |
| void | resetSimulation () |
| Resets simulation progression without changing scheduling settings. More... | |
| UpdateCallback | updateCallback () const |
| Returns the currently installed host update callback. More... | |
| void | updateCallback (UpdateCallback callback) |
| Replaces the host update callback; an empty callback disables it. More... | |
| double | timeStep () const |
| Returns the fixed simulation step duration in seconds. More... | |
| void | timeStep (double value) |
| Changes the fixed simulation step duration. More... | |
| std::uint32_t | maxCatchUpSteps () const |
| Returns the maximum number of automatic catch-up steps permitted per host update. More... | |
| void | maxCatchUpSteps (std::uint32_t value) |
| Changes the maximum number of automatic catch-up steps per host update. More... | |
| double | timeScale () const |
| Returns the scale applied to elapsed host time for automatic simulation stepping. More... | |
| void | timeScale (double value) |
| Changes the scale applied to elapsed host time for automatic simulation stepping. More... | |
| double | simulationTime () const |
| Returns total simulated time in seconds completed by fixed simulation steps. More... | |
| std::uint64_t | simulationStepCount () const |
| Returns the total number of completed fixed simulation steps. More... | |
| State | state () const |
| Returns the current Runner lifecycle state. More... | |
| Scene & | scene () |
| Returns the Scene driven by this Runner. More... | |
| const Scene & | scene () const |
| Returns the Scene driven by this Runner. More... | |
Drives host updates, fixed-step simulation, and rendering for a Scene.
A Runner converts elapsed host time into zero or more constant-duration simulation steps according to SimulationConfig. Catch-up work is bounded by maxCatchUpSteps(); excess accumulated simulation time is discarded while the fractional remainder is retained.
Automatic simulation stepping may be paused while host updates, input processing, host-update and input callbacks, and rendering continue. While paused, fixed-duration simulation steps may be requested explicitly.
A Runner begins in State::Idle. start() may be called once; stop() places the Runner in the terminal State::Stopped state.
| using a3d::Runner::UpdateCallback = std::function<void(Runner& runner, const UpdateInfo& info)> |
|
strong |
|
explicit |
Creates an idle Runner for scene.
The Runner retains scene by reference; the Scene must outlive the Runner. The supplied configuration is copied and validated when start() is called.
| scene | Scene whose input, simulation, and rendering are driven. |
| config | initial simulation scheduling configuration. |
| std::uint32_t a3d::Runner::maxCatchUpSteps | ( | ) | const |
Returns the maximum number of automatic catch-up steps permitted per host update.
| void a3d::Runner::maxCatchUpSteps | ( | std::uint32_t | value | ) |
Changes the maximum number of automatic catch-up steps per host update.
| std::invalid_argument | if value is zero. |
| void a3d::Runner::requestSimulationStep | ( | ) |
Queues one fixed-duration simulation step while paused.
Requested steps use timeStep() and are not scaled by timeScale(). Multiple calls queue multiple steps for the next eligible host update.
| std::logic_error | if the Runner is not running or the simulation is not paused. |
| std::overflow_error | if the pending-step counter overflows. |
| void a3d::Runner::resetSimulation | ( | ) |
Resets simulation progression without changing scheduling settings.
Simulation time, completed step count, accumulated/discarded time, and pending requested steps are reset. The current time step, maximum catch-up count, time scale, and pause state are preserved.
When automatic stepping is active, the next host-time delta is discarded.
| std::logic_error | if the Runner is not running. |
| bool a3d::Runner::simulationPaused | ( | ) | const |
Returns true when automatic simulation stepping is paused.
| void a3d::Runner::simulationPaused | ( | bool | paused | ) |
Pauses or resumes automatic simulation stepping.
Host updates, input processing, host-update and input callbacks, and rendering continue while paused. Scene simulation-step callbacks run only when explicitly requested steps are executed. Pausing clears accumulated automatic simulation time. Resuming clears pending requested steps and discards the next host-time delta so time spent paused does not become catch-up work.
| paused | true to pause automatic simulation stepping; false to resume it. |
| std::logic_error | if the Runner is not running. |
| std::uint64_t a3d::Runner::simulationStepCount | ( | ) | const |
Returns the total number of completed fixed simulation steps.
| double a3d::Runner::simulationTime | ( | ) | const |
Returns total simulated time in seconds completed by fixed simulation steps.
| void a3d::Runner::start | ( | ) |
| void a3d::Runner::stop | ( | ) |
| double a3d::Runner::timeScale | ( | ) | const |
Returns the scale applied to elapsed host time for automatic simulation stepping.
| void a3d::Runner::timeScale | ( | double | value | ) |
Changes the scale applied to elapsed host time for automatic simulation stepping.
Requested steps are not affected by this value.
| std::invalid_argument | if value is less than or equal to zero. |
| double a3d::Runner::timeStep | ( | ) | const |
Returns the fixed simulation step duration in seconds.
| void a3d::Runner::timeStep | ( | double | value | ) |
Changes the fixed simulation step duration.
Existing accumulated simulation time is preserved in seconds.
| std::invalid_argument | if value is less than or equal to zero. |
| bool a3d::Runner::update | ( | ) |
Performs one host update using the current monotonic time.
A running update invokes the host callback, polls events, updates input, advances or explicitly steps the simulation as appropriate, and renders when the Scene has a VisualWorld.
| UpdateCallback a3d::Runner::updateCallback | ( | ) | const |
Returns the currently installed host update callback.
| void a3d::Runner::updateCallback | ( | UpdateCallback | callback | ) |
Replaces the host update callback; an empty callback disables it.
1.9.4