Runner.h

//
//  Runner.h
//  avara3d
//
//  Created by Morgan Davis on 7/10/26.
//  Copyright © 2026 Morgan K Davis. All rights reserved.
//
 
#ifndef AVARA3D_RUNNER_H
#define AVARA3D_RUNNER_H
 
#include <chrono>
#include <cstdint>
#include <functional>
 
#include "a3d/SimulationConfig.h"
#include "a3d/profile/FrameStatsHistory.h"
#include "a3d/profile/Profiler.h"
 
#include "a3d/TestAccessFwd.h"
 
namespace a3d {
 
    struct FrameStats;
 
    class Scene;
 
    class Runner {
 
    public:
        // [Public Types]
 
        enum class State {
            Idle,    
            Running, 
            Stopped  
        };
 
        struct UpdateInfo {
 
            std::uint64_t updateIndex {0};
 
            double        elapsedTime {0.0};
 
            double        deltaTime {0.0};
        };
 
        using UpdateCallback = std::function<void(Runner& runner, const UpdateInfo& info)>;
 
        // [Public Lifecycle Functions]
 
        explicit Runner(Scene& scene, SimulationConfig config = {});
 
        Runner(const Runner&)            = delete;
        Runner& operator=(const Runner&) = delete;
 
        Runner(Runner&&)            = delete;
        Runner& operator=(Runner&&) = delete;
 
        ~Runner();
 
        // [Public Member Functions]
 
        void           start();
 
        bool           update();
 
        void           stop();
 
        bool           simulationPaused() const;
 
        void           simulationPaused(bool paused);
 
        void           requestSimulationStep();
 
        void           resetSimulation();
 
        UpdateCallback updateCallback() const;
 
        void           updateCallback(UpdateCallback callback);
 
        double         timeStep() const;
 
        void           timeStep(double value);
 
        std::uint32_t  maxCatchUpSteps() const;
 
        void           maxCatchUpSteps(std::uint32_t value);
 
        double         timeScale() const;
 
        void           timeScale(double value);
 
        double         simulationTime() const;
 
        std::uint64_t  simulationStepCount() const;
 
        State          state() const;
 
        Scene&         scene();
 
        const Scene&   scene() const;
 
        // [Internal Member Functions]
 
        bool           simulationClockSuspended() const;
        void           simulationClockSuspended(bool suspended);
 
    private:
        // [Private Types]
 
        using Clock     = std::chrono::steady_clock;
        using TimePoint = Clock::time_point;
 
        // [Private Member Functions]
 
        void              start(TimePoint now);
        bool              update(TimePoint now);
 
        void              advanceSimulation(const UpdateInfo& info, FrameStats& stats);
        void              executePendingSimulationSteps(FrameStats& stats);
        void              executeSimulationStep();
 
        bool              renderFrame(const UpdateInfo& info, FrameStats& stats);
 
        // [Private Member Variables]
 
        Scene&            _scene;
        State             _state;
        SimulationConfig  _config;
        double            _timeStep;
        std::uint32_t     _maxCatchUpSteps;
        double            _timeScale;
        double            _simulationTimeAccumulator;
        double            _simulationTime;
        std::uint64_t     _simulationStepCount;
        double            _totalDiscardedSimulationTime;
        bool              _simulationPaused;
        std::uint64_t     _pendingSimulationSteps;
        bool              _skipNextUpdateDelta;
        bool              _simulationClockSuspended;
        TimePoint         _startTime;
        TimePoint         _prevUpdateTime;
        std::uint64_t     _updateCount;
        UpdateCallback    _updateCallback;
        std::uint64_t     _renderedFrameCount;
        Profiler          _profiler;
        FrameStatsHistory _frameStatsHistory;
 
        // [Test Access]
 
        friend class testing::RunnerTestAccess;
    };
 
}
 
#endif // AVARA3D_RUNNER_H