sdlaudioclock.h

Go to the documentation of this file.

 
#pragma once
 
#include <promeki/namespace.h>
#include <promeki/clock.h>
#include <promeki/objectbase.h>
#include <promeki/periodiccallback.h>
#include <promeki/atomic.h>
#include <promeki/string.h>
 
#include <cstdint>
#include <climits>
 
PROMEKI_NAMESPACE_BEGIN
 
class SDLAudioOutput;
 
class SDLAudioClock : public Clock {
        public:
                struct Stats {
                                int64_t updateCount = 0;
                                int64_t checkpointResyncs = 0;
                                int64_t forwardSnaps = 0;
                                int64_t backDates = 0;
                                int64_t clampedRegressions = 0;
                                int64_t maxStepNs = 0;
                                int64_t maxBackDateNs = 0;
                                int64_t maxCallbackGapNs = 0;
                };
 
                explicit SDLAudioClock(SDLAudioOutput *output);
 
                int64_t     resolutionNs() const override;
                ClockJitter jitter() const override;
                double      rateRatio() const override;
 
                Stats stats() const { return _stats; }
 
                void resetStats();
 
        protected:
                Result<int64_t> raw() const override;
                Error           sleepUntilNs(int64_t targetNs) const override;
                Error           onPause(bool paused) override;
 
        private:
                // Core interpolation math shared between the normal
                // raw() path and the pause-snapshot path in @ref
                // onPause.  Updates checkpoint state and logs stats.
                int64_t computeRawNs() const;
 
                void updateRateEstimate() const;
                void reportMonitor() const;
 
                // When @c _devicePaused is true, @ref raw returns
                // @c _rawAtPause unchanged so wall time advancing
                // through the paused interval does not drag the
                // clock forward.  Rate estimation and interpolation
                // checkpoints are reset in @ref onPause on resume.
                mutable Atomic<bool>    _devicePaused{false};
                mutable Atomic<int64_t> _rawAtPause{0};
 
                ObjectBasePtr<SDLAudioOutput> _output;
                double                        _bytesPerSec;
                int64_t                       _resolutionNs;
 
                // Rate-estimate state.  Kept mutable so the update
                // can run inside nowNs().  Caller is expected to use
                // the clock from a single thread (the pacer or
                // FrameSync worker).
                mutable bool    _rateBaselineValid = false;
                mutable bool    _rateEstimateStable = false;
                mutable int64_t _rateBaselineWallNs = 0;
                mutable int64_t _rateBaselineConsumed = 0;
                mutable int64_t _lastRateUpdateWallNs = 0;
                mutable double  _filteredRateRatio = 1.0;
 
                // Slowly-ramped, externally-visible ratio.  Starts at
                // 1.0 and drifts toward the internal LPF over a long
                // time constant so that consumers (e.g. an audio
                // resampler) can't detect the moment measurement
                // stabilises as an audible pitch step.
                mutable double _publishedRateRatio = 1.0;
 
                // Smooth-nowNs interpolation state.  Each advance
                // of @c consumed (an SDL audio callback) is treated
                // as a phase checkpoint; between checkpoints the
                // clock extrapolates forward at the fast-tracking
                // filtered rate.  When a checkpoint lands behind
                // the extrapolated value the wall anchor is
                // back-dated rather than snapped, keeping the
                // reported time monotonic while the rate filter
                // converges on the true consumption rate.
                mutable int64_t _checkpointConsumed = -1;
                mutable int64_t _checkpointConsumedNs = 0;
                mutable int64_t _checkpointWallNs = 0;
 
                // Rate snapshot at the moment the checkpoint was
                // anchored.  Interpolation between checkpoints
                // uses this value rather than the live rate
                // filter output so that rate-filter updates
                // mid-interval cannot pull the extrapolated
                // position backward and stall the clock on the
                // monotonicity clamp.  The live filter still
                // drives @ref rateRatio and still takes effect at
                // the next checkpoint update.
                mutable double _checkpointRate = 1.0;
 
                // Last value returned from @ref nowNs.  Used as a
                // final clamp to defend the monotonicity contract
                // against sub-nanosecond floating-point rounding
                // in the back-date arithmetic.
                mutable int64_t _lastReportedNs = INT64_MIN;
 
                // Latches true the first time SDL reports a non-
                // zero @c consumed.  Gates the silent-startup
                // path: before audio has started, @ref nowNs holds
                // at zero rather than extrapolating wall time
                // forward (which would lie to A/V sync and force
                // an enormous back-date when the first real chunk
                // finally lands).  Once latched, transient drops
                // of @c consumed back to zero are treated as noise
                // and routed through the normal back-date path so
                // monotonicity is preserved.
                mutable bool _audioStarted = false;
 
                // Monitoring state.  @c _stats accumulates runtime
                // counters; @c _lastCallbackWallNs is used to
                // compute callback-gap maxima; @c _monitor fires
                // once per second from inside @ref nowNs and
                // publishes an error/debug summary through the
                // logger; @c _monitorSnapshot holds the previous
                // tick's counters so the monitor can report deltas.
                // @c _prevRateStable latches the previous rate-
                // filter stable flag so the maxes can be reset once
                // at the warmup→stable transition — startup
                // transients dominate those maxes and would mask
                // later, real misbehavior if left in place.
                mutable Stats            _stats;
                mutable int64_t          _lastCallbackWallNs = 0;
                mutable PeriodicCallback _monitor;
                mutable Stats            _monitorSnapshot;
                mutable bool             _prevRateStable = false;
};
 
PROMEKI_NAMESPACE_END