ntv2mediaio.h

Go to the documentation of this file.

 
#pragma once
 
 
#include <promeki/config.h>
#if PROMEKI_ENABLE_NTV2
 
#include <promeki/atomic.h>
#include <promeki/audiobuffer.h>
#include <promeki/audiodesc.h>
#include <promeki/buffer.h>
#include <promeki/clock.h>
#include <promeki/dedicatedthreadmediaio.h>
#include <promeki/frame.h>
#include <promeki/framerate.h>
#include <promeki/imagedesc.h>
#include <promeki/mediadesc.h>
#include <promeki/mediaiofactory.h>
#include <promeki/mediaiostats.h>
#include <promeki/mutex.h>
#include <promeki/namespace.h>
#include <promeki/ntv2routing.h>
#include <promeki/pacinggate.h>
#include <promeki/queue.h>
#include <promeki/sdisignalconfig.h>
#include <promeki/string.h>
#include <promeki/thread.h>
#include <promeki/uncompressedvideopayload.h>
 
PROMEKI_NAMESPACE_BEGIN
 
class Ntv2Device;
 
class Ntv2MediaIO : public DedicatedThreadMediaIO {
                PROMEKI_OBJECT(Ntv2MediaIO, DedicatedThreadMediaIO)
        public:
                static inline const MediaIOStats::ID StatsFramesReceived{"Ntv2FramesReceived"};
                static inline const MediaIOStats::ID StatsFramesDropped{"Ntv2FramesDropped"};
                static inline const MediaIOStats::ID StatsAudioBytesReceived{"Ntv2AudioBytesReceived"};
                static inline const MediaIOStats::ID StatsFramesPlayed{"Ntv2FramesPlayed"};
                static inline const MediaIOStats::ID StatsFramesDroppedSink{"Ntv2FramesDroppedSink"};
                static inline const MediaIOStats::ID StatsAncPacketsReceived{"Ntv2AncPacketsReceived"};
                static inline const MediaIOStats::ID StatsAncPacketsSent{"Ntv2AncPacketsSent"};
                static inline const MediaIOStats::ID StatsSignalLoss{"Ntv2SignalLoss"};
                static inline const MediaIOStats::ID StatsSignalReacquired{"Ntv2SignalReacquired"};
                static inline const MediaIOStats::ID StatsPacingTicksOnTime{"Ntv2PacingTicksOnTime"};
                static inline const MediaIOStats::ID StatsPacingTicksLate{"Ntv2PacingTicksLate"};
                static inline const MediaIOStats::ID StatsPacingTicksSkipped{"Ntv2PacingTicksSkipped"};
                static inline const MediaIOStats::ID StatsPacingReanchors{"Ntv2PacingReanchors"};
                static inline const MediaIOStats::ID StatsDeviceLost{"Ntv2DeviceLost"};
 
                Ntv2MediaIO(ObjectBase *parent = nullptr);
 
                ~Ntv2MediaIO() override;
 
                Error proposeInput(const MediaDesc &offered, MediaDesc *preferred) const override;
 
        protected:
                Error executeCmd(MediaIOCommandOpen &cmd) override;
                Error executeCmd(MediaIOCommandClose &cmd) override;
                Error executeCmd(MediaIOCommandRead &cmd) override;
                Error executeCmd(MediaIOCommandWrite &cmd) override;
                Error executeCmd(MediaIOCommandStats &cmd) override;
                Error executeCmd(MediaIOCommandSetClock &cmd) override;
                void  cancelBlockingWork() override;
 
        private:
                Error openSource(const MediaIO::Config &cfg, const MediaDesc &md);
                void  closeSource();
                void  captureLoop();
 
                Error openSink(const MediaIO::Config &cfg, const MediaDesc &md);
                void  closeSink();
                void  playoutLoop();
 
                // Apply the per-channel SDI signal routing for the
                // resolved link standard.  Single-link, quad-link 2SI,
                // quad-link Squares, and 12G single-link all flow
                // through @ref Ntv2Routing::sdiInputConnections /
                // @ref Ntv2Routing::sdiOutputConnections — the helper
                // applies each crosspoint via @c CNTV2Card::Connect and
                // toggles the TSI / Squares enable bit beforehand when
                // the standard requires it.  Dual-link and SL_24G are
                // not yet implemented; an empty connection list bubbles
                // up as @c Error::NotSupported.
                //
                // The on-board CSC widgets bridge framebuffer-vs-wire
                // colour-family mismatches inside the routing fabric
                // when @c routingCfg.allowOnBoardCsc is @c true and the
                // wire and framebuffer differ in colour family —
                // wired up by the caller from
                // @c MediaConfig::Ntv2DisableOnBoardCsc and the
                // framebuffer / wire colour models.
                Error routeSdiInput(const Ntv2Routing::Config &routingCfg);
                Error routeSdiOutput(const Ntv2Routing::Config &routingCfg);
 
                // Sink VPID stamping (Phase 6.4): resolves
                // transfer / colorimetry / luminance / RGB range
                // from the open-time @ref ImageDesc colour model +
                // any @c MediaConfig::Ntv2Vpid*Override + per-frame
                // @c Metadata::Video* keys when present, then writes
                // the AJA per-channel VPID overrides via
                // @c CNTV2Card::SetSDIOutVPID*.  Called from
                // @ref openSink with @p md = the resolved sink
                // ImageDesc; the per-frame nudge path is currently
                // not wired (HDR signalling is generally a session-
                // level decision — switching mid-stream wants a
                // device-wide re-init).  Quietly skips when
                // @c Ntv2VpidEnable is false.
                Error applySinkVpid(const MediaIO::Config &cfg, const ImageDesc &md);
 
                // Source VPID detection (Phase 6.4): reads the
                // incoming SDI VPID via @c CNTV2Card::ReadSDIInVPID
                // for the channel's primary input port, parses byte
                // 4 (transfer / colorimetry / RGB range), and
                // updates @ref _vpidLast* state.  Called at open
                // time (so the first captured Frame already carries
                // the wire's colour claim) and during the periodic
                // signal-loss poll (so mid-stream HDR transitions
                // are picked up).  No-op when @c Ntv2VpidEnable is
                // false or the channel has no SDI input port.
                void  pollSourceVpid();
 
                // Worker thread classes — capture and playout each have
                // their own @ref Thread subclass so the library's
                // OS-name / TID-tracking / clean-join machinery wraps
                // them instead of bare @c std::thread.  The bodies
                // delegate straight back to captureLoop / playoutLoop
                // on the owning MediaIO.
                class CaptureWorker : public Thread {
                                public:
                                        CaptureWorker(Ntv2MediaIO *owner) : _owner(owner) {}
 
                                protected:
                                        void run() override { _owner->captureLoop(); }
 
                                private:
                                        Ntv2MediaIO *_owner;
                };
 
                class PlayoutWorker : public Thread {
                                public:
                                        PlayoutWorker(Ntv2MediaIO *owner) : _owner(owner) {}
 
                                protected:
                                        void run() override { _owner->playoutLoop(); }
 
                                private:
                                        Ntv2MediaIO *_owner;
                };
 
                // Device handle owned by the registry; non-null between
                // openSource / openSink and the matching close.
                // Released on close.
                Ntv2Device *_device = nullptr;
 
                // 1-based logical channel index — matches the SDK's
                // NTV2_CHANNEL1..  numbering minus one for the enum
                // cast.
                int _channel = 0;
 
                // 1-based audio system index, or 0 when audio is
                // disabled for this channel.
                int _audioSystem = 0;
 
                // Direction flag set at openSource / openSink so the
                // common close path can route to the right teardown.
                bool _sinkMode = false;
 
                // Per-port reservation list captured at open so the
                // close path can hand it back to the device.
                List<VideoPortRef> _reservedPorts;
 
                // Capture pipeline state.  The queue carries fully-
                // built Frames (video + optional ANC) so the capture
                // thread keeps ownership of payload assembly and the
                // strand's executeCmd(Read) is a pure drain.
                CaptureWorker        _captureWorker{this};
                Atomic<bool>         _stopFlag{false};
                Atomic<bool>         _readCancelled{false};
                static constexpr int VideoQueueDepth = 2;
                Queue<Frame>         _videoQueue;
 
                // Playout pipeline state.  The strand pushes onto
                // @ref _writeQueue inside executeCmd(Write); the
                // playout thread drains and submits via AutoCirculate.
                // Queue depth is chosen larger than the card's pre-
                // buffer (3 frames) so steady-state writers don't
                // immediately back-pressure during the initial fill.
                // Like the capture path, the queue carries full Frames
                // so the playout thread can find any ANC payloads
                // attached alongside the video.
                PlayoutWorker        _playoutWorker{this};
                static constexpr int WriteQueueDepth = 4;
                Queue<Frame>         _writeQueue;
 
                // ANC capture / insertion state.  Buffers stay
                // resident for the lifetime of the open so we don't
                // pay an allocator round-trip on every frame.  Empty
                // when ANC is disabled (Ntv2WithAnc=false or card
                // missing the custom-ANC engine).
                bool   _ancEnabled = false;
                Buffer _ancF1Buf;
                Buffer _ancF2Buf;
                // Cached f2 start-line for interlaced playout — set
                // at open from the resolved video standard.
                uint16_t _f2StartLine = 0;
 
                // Per-frame VBI poll timeout used by both worker loops'
                // WaitForInputVerticalInterrupt /
                // WaitForOutputVerticalInterrupt call.  Configurable
                // via MediaConfig::Ntv2VbiTimeoutMs.
                int _vbiTimeoutMs = 50;
 
                // Input-signal poll cadence (in VBIs) used by the
                // capture worker — every Nth VBI the worker re-queries
                // GetInputVideoFormat to catch a signal-loss or
                // re-acquire event.  Zero disables the poll.  Set from
                // @c MediaConfig::Ntv2SignalPollIntervalVbi at open.
                int _signalPollIntervalVbi = 15;
 
                // Latched signal-presence state.  The capture worker
                // toggles this and emits @c errorOccurredSignal +
                // increments @c _signalLossCount on every transition
                // from "present" to "absent"; on the inverse
                // transition it logs a re-acquire info line +
                // increments @c _signalReacquiredCount.  Treat as
                // strictly thread-confined to the capture worker —
                // the stats getters read the counters via @ref Atomic.
                bool _signalPresent = true;
 
                // VPID (SMPTE ST 352) state.  When @c _vpidEnabled is
                // true the sink open path writes byte-4 overrides for
                // transfer / colorimetry / luminance / RGB range, and
                // the source open path reads input VPID and stamps
                // the detected colour description on captured Frames.
                // _vpidLast{Transfer,Colorimetry,Range} are the most
                // recent decoded values from the source side and are
                // re-stamped on every captured frame so consumers see
                // the wire's claim — thread-confined to the capture
                // worker (they're read/written only there).
                bool _vpidEnabled = true;
                int  _vpidLastTransfer    = 0; // NTV2VPIDTransferCharacteristics
                int  _vpidLastColorimetry = 0; // NTV2VPIDColorimetry
                int  _vpidLastRange       = 0; // NTV2VPIDRGBRange
                bool _vpidLastValid       = false;
 
                // Resolved descriptors / rate populated at open time.
                ImageDesc _imageDesc;
                FrameRate _frameRate;
                AudioDesc _audioDesc;
 
                // Device sample clock bound to the port group — kept
                // alive past close in case downstream consumers still
                // hold a Clock::Ptr to it.
                Clock::Ptr _sourceClock;
 
                // Sink-side external pacing (Phase 6).  When a non-
                // null Clock::Ptr is bound through executeCmd(SetClock)
                // the playout worker waits on @ref _paceGate before
                // submitting each frame to AutoCirculate.  Without an
                // external clock the gate stays unbound and the
                // playout worker falls through to the card's self-
                // pacing (which is the Phase-2 default).
                PacingGate _paceGate;
                // Read by the playout worker on every loop iteration
                // to decide whether to wait on @ref _paceGate.  Flipped
                // by executeCmd(SetClock).  Atomic so the playout
                // thread reads the latest bind state without a mutex.
                Atomic<bool> _paceClockExternal{false};
 
                // Telemetry.
                Atomic<int64_t> _framesReceived{0};
                Atomic<int64_t> _framesDropped{0};
                Atomic<int64_t> _audioBytesReceived{0};
                Atomic<int64_t> _framesPlayed{0};
                Atomic<int64_t> _framesDroppedSink{0};
                Atomic<int64_t> _ancPacketsReceived{0};
                Atomic<int64_t> _ancPacketsSent{0};
                Atomic<int64_t> _signalLossCount{0};
                Atomic<int64_t> _signalReacquiredCount{0};
                Atomic<int64_t> _deviceLostCount{0};
 
                // Set by either worker on the periodic signal-poll
                // branch when @c CNTV2Card::IsOpen reports the
                // device handle has gone away (driver unloaded /
                // module reload / device hot-unplug).  Read by both
                // worker loops on every iteration so they exit cleanly
                // instead of looping forever on a dead device handle.
                // The MediaIO surfaces the event via
                // @c errorOccurredSignal(Error::DeviceError) exactly
                // once per loss.
                Atomic<bool> _deviceLost{false};
};
 
class Ntv2Factory : public MediaIOFactory {
        public:
                Ntv2Factory() = default;
 
                String name() const override { return String("Ntv2"); }
                String displayName() const override { return String("AJA NTV2"); }
                String description() const override {
                        return String("AJA NTV2 SDI / HDMI capture and playout via libajantv2");
                }
 
                bool canBeSource() const override { return true; }
                bool canBeSink() const override { return true; }
 
                StringList schemes() const override { return {String("ntv2")}; }
                bool       canHandlePath(const String &path) const override;
                StringList enumerate() const override;
                Error      urlToConfig(const Url &url, Config *outConfig) const override;
 
                Config::SpecMap configSpecs() const override;
 
                MediaIO *create(const Config &config, ObjectBase *parent = nullptr) const override;
};
 
PROMEKI_NAMESPACE_END
 
#endif // PROMEKI_ENABLE_NTV2