ntv2clock.h

Go to the documentation of this file.

 
#pragma once
 
 
#include <promeki/config.h>
#if PROMEKI_ENABLE_NTV2
 
#include <promeki/atomic.h>
#include <promeki/clock.h>
#include <promeki/clockdomain.h>
#include <promeki/framerate.h>
#include <promeki/mediatimestamp.h>
#include <promeki/mutex.h>
#include <promeki/namespace.h>
#include <promeki/timestamp.h>
 
PROMEKI_NAMESPACE_BEGIN
 
class Ntv2Device;
 
class Ntv2DeviceClock : public Clock {
        public:
                static const ClockDomain &domainFor(const Ntv2Device &device);
 
                Ntv2DeviceClock(Ntv2Device *device, bool vbiFallback);
 
                ~Ntv2DeviceClock() override;
 
                static Ntv2DeviceClock *createForTest(const String &testDomainName, bool vbiFallback);
 
                int64_t     resolutionNs() const override;
                ClockJitter jitter() const override;
 
                double      rateRatio() const override;
 
                void noteVbi(const TimeStamp &now);
 
                void setSampleRate(float sampleRateHz);
 
                MediaTimeStamp mediaTimeStampFromSamples(uint64_t samples) const;
 
                void setFrameRate(const FrameRate &frameRate);
 
                // ---- Test seam ----
 
                void setCounterSourceForTest(bool (*fn)(uint32_t *out, void *ctx), void *ctx);
 
                void setWallTimeSourceForTest(int64_t (*fn)(void *ctx), void *ctx);
 
                static constexpr int64_t kRateBaselineMinWindowNs = 5'000'000'000LL;
 
                static constexpr int64_t kRateUpdateIntervalNs = 1'000'000'000LL;
 
                static constexpr int _kRateLpfAlphaPer1000 = 100;
 
        protected:
                Result<int64_t> raw() const override;
                Error           sleepUntilNs(int64_t targetNs) const override;
 
        private:
                // Test-only constructor — takes the ClockDomain directly so
                // we can build a clock without an Ntv2Device handle.
                Ntv2DeviceClock(const ClockDomain &domain, bool vbiFallback);
 
                int64_t sampleTicksToNs(uint64_t ticks) const;
 
                Ntv2Device *_device       = nullptr;
                bool        _vbiFallback  = false;
 
                // Sample rate in Hz; used to convert counter → ns.
                // Mutated via setSampleRate which takes _mutex.
                float _sampleRateHz = 48000.0f;
 
                // 32 → 64 wrap shadow.  _highBits and _lastLow are
                // updated under _mutex on every raw() read.
                mutable Mutex        _mutex;
                mutable uint32_t     _lastLow  = 0;
                mutable uint64_t     _highBits = 0;
                mutable bool         _hasShadow = false;
 
                // VBI-fallback last-wake tick (host monotonic ns).
                mutable Atomic<int64_t> _lastVbiNs{0};
 
                // Jitter sizing in VBI mode.
                FrameRate _frameRate;
 
                // Optional test counter source (set via
                // setCounterSourceForTest).  Always nullptr in
                // production — production reads CNTV2Card::GetRawAudioTimer.
                bool (*_testCounterFn)(uint32_t *, void *) = nullptr;
                void *_testCounterCtx                       = nullptr;
 
                // Optional test wall-time source (set via
                // setWallTimeSourceForTest).  Production reads
                // TimeStamp::now().nanoseconds() inside the drift
                // estimator.
                int64_t (*_testWallFn)(void *) = nullptr;
                void *_testWallCtx              = nullptr;
 
                // Drift estimator state.  All mutated from raw()
                // under _mutex; rateRatio() reads _ratePpb lock-free
                // via Atomic.  PPB = parts per billion; 1e9 ≡ 1.0.
                mutable Atomic<int64_t> _ratePpb{1'000'000'000};
                mutable bool            _rateBaselineValid     = false;
                mutable int64_t         _rateBaselineWallNs    = 0;
                mutable int64_t         _rateBaselineCounterNs = 0;
                mutable int64_t         _lastRateUpdateWallNs  = 0;
};
 
PROMEKI_NAMESPACE_END
 
#endif // PROMEKI_ENABLE_NTV2