v4l2mediaio.h

Go to the documentation of this file.

 
#pragma once
 
 
#include <promeki/config.h>
#if PROMEKI_ENABLE_V4L2
#include <promeki/namespace.h>
#include <promeki/atomic.h>
#include <promeki/audiobuffer.h>
#include <promeki/basicthread.h>
#include <promeki/audiodesc.h>
#include <promeki/dedicatedthreadmediaio.h>
#include <promeki/framerate.h>
#include <promeki/imagedesc.h>
#include <promeki/list.h>
#include <promeki/mediaiofactory.h>
#include <promeki/mediaiostats.h>
#include <promeki/mutex.h>
#include <promeki/periodiccallback.h>
#include <promeki/pixelformat.h>
#include <promeki/queue.h>
#include <promeki/sharedptr.h>
#include <promeki/videopayload.h>
 
struct _snd_pcm;
typedef struct _snd_pcm snd_pcm_t;
 
PROMEKI_NAMESPACE_BEGIN
 
// Shared re-queue gate for the dma-buf zero-copy capture path; defined
// in v4l2mediaio.cpp.  Held by SharedPtr so it can outlive the
// V4l2MediaIO while in-flight frames still reference exported buffers.
struct V4l2RequeueGate;
 
class V4l2MediaIO : public DedicatedThreadMediaIO {
                PROMEKI_OBJECT(V4l2MediaIO, DedicatedThreadMediaIO)
        public:
                static inline const MediaIOStats::ID StatsCaptured{"V4l2Captured"};
                static inline const MediaIOStats::ID StatsAlsaOverruns{"V4l2AlsaOverruns"};
 
                V4l2MediaIO(ObjectBase *parent = nullptr);
 
                ~V4l2MediaIO() override;
 
                int instanceID() const { return _instanceId; }
 
                static PixelFormat::ID v4l2ToPixelFormat(uint32_t v4l2fmt);
 
                static uint32_t pixelFormatToV4l2(PixelFormat::ID pd);
 
                static bool captureFormatAllowsZeroCopy(const PixelFormat &pd) { return !pd.isCompressed(); }
 
        protected:
                Error executeCmd(MediaIOCommandOpen &cmd) override;
                Error executeCmd(MediaIOCommandClose &cmd) override;
                Error executeCmd(MediaIOCommandRead &cmd) override;
                Error executeCmd(MediaIOCommandStats &cmd) override;
 
                // Wakes the executeCmd(Read) pop-loop so close() can
                // proceed past an in-flight blocked read.  Sets the
                // _readCancelled flag — the loop polls it on each
                // short-timeout pop wakeup.
                void cancelBlockingWork() override;
 
        private:
 
                // describe() / proposeOutput overrides intentionally
                // omitted for v1: the V4L2 device-mode enumeration
                // path lives in v4l2QueryDevice and is already exposed
                // through @ref MediaIOFactory::queryDevice (used by
                // @c mediaplay @c --probe).  A future revision will
                // surface it here so the planner can pick a device
                // mode without paying the cost of opening the
                // capture pipeline.  Today the planner's
                // open()/close() fallback handles V4L2 sources
                // correctly — at the cost of one ALSA + V4L2 open
                // cycle during planning.
 
                // -- V4L2 helpers --
                Error openVideo(const MediaIO::Config &cfg);
                Error startStreaming();
                void  stopStreaming();
                void  closeVideo();
 
                // -- ALSA helpers --
                Error openAudio(const MediaIO::Config &cfg);
                void  closeAudio();
 
                // -- Capture threads --
                void stopThreads();
                void videoCaptureLoop();
                void audioCaptureLoop();
 
                // -- V4L2 state --
                //
                // One entry per V4L2 capture (vb2) buffer.  In the MMAP
                // path @c start / @c length describe the host mapping; in
                // the dma-buf zero-copy path @c dmabufFd holds the
                // device-lifetime fd exported once via VIDIOC_EXPBUF
                // (@c start stays null), bounding open fds to pool depth.
                struct MmapBuffer {
                                void  *start    = nullptr;
                                size_t length   = 0;
                                int    dmabufFd = -1;
                };
                int              _fd = -1;
                List<MmapBuffer> _buffers;
                bool             _streaming = false;
                ImageDesc        _imageDesc;
 
                // -- dma-buf zero-copy path --
                //
                // _zeroCopy is set when the EXPBUF probe in openVideo
                // succeeds; _bufLength is the per-buffer allocation size
                // (the dma-buf plane size); _requeueGate decouples the
                // per-frame re-queue callbacks from this object's
                // lifetime (callbacks may fire on a downstream thread
                // after close).
                bool                          _zeroCopy = false;
                size_t                        _bufLength = 0;
                SharedPtr<V4l2RequeueGate>    _requeueGate;
 
                // -- ALSA state --
                snd_pcm_t *_pcm = nullptr;
                AudioDesc  _audioDesc;
                bool       _audioEnabled = false;
 
                // -- Capture threads --
                Atomic<bool>      _stopFlag{false};
                Atomic<int>     _deviceError{0}; // errno from device failure (ENODEV etc.)
                // Set by cancelBlockingWork() when MediaIO::close()
                // wants to unwind an in-flight Read whose strand
                // worker is parked in _videoQueue.pop().  The pop
                // uses a short timeout so the loop notices this
                // flag (and _deviceError) within one tick of being
                // raised.  Reset at the start of every Open so a
                // closed-then-reopened MediaIO doesn't carry the
                // previous instance's cancellation forward.
                Atomic<bool>      _readCancelled{false};
                BasicThread       _videoThread;
                BasicThread       _audioThread;
                int               _instanceId = 0; 
 
                // -- Video frame queue (video thread → read command) --
                static constexpr int     VideoQueueDepth = 2;
                Queue<VideoPayload::Ptr> _videoQueue;
 
                // -- Audio ring buffer (audio thread → read command) --
                //
                // Each ALSA capture batch is pushed with a wall-clock
                // MediaTimeStamp anchor; the ring's anchor queue
                // recovers the PTS of the first popped sample on
                // drain, so downstream drift correction sees real
                // ALSA delivery rate via samples / ts_delta.
                AudioBuffer _audioRing;
 
                // -- Telemetry (updated atomically by capture threads) --
                Atomic<int64_t>     _framesCaptured{0};
                Atomic<int64_t>     _alsaOverruns{0};
 
                // -- Debug reporting --
                PeriodicCallback _debugReport;
                int64_t          _ringAccum = 0;         // sum of ring levels sampled each frame
                int64_t          _ringAccumFrames = 0;   // frames sampled since last report
                double           _ringAvgBaseline = 0.0; // first report's average
                TimeStamp        _ringBaselineTime;      // V4L2 timestamp at first report
                bool             _ringBaselineSet = false;
 
                // -- Capture timestamp tracking (from V4L2 DQBUF) --
                TimeStamp _lastCaptureTime;        // most recent frame's V4L2 timestamp
                TimeStamp _firstCaptureTime;       // first frame's V4L2 timestamp
                int64_t   _firstCaptureFrame = -1; // frame index of first timestamp
                double    _frameDeltaSum = 0.0;    // sum of inter-frame intervals (sec) this period
                double    _frameDeltaSqSum = 0.0;  // sum of squared deltas for jitter
                int64_t   _frameDeltaCount = 0;    // deltas accumulated this period
                double    _prevPeriodFps = 0.0;    // previous period's measured fps
 
                // -- Stall-overflow protection --
                bool _ringOverflowWarned = false;
 
                // -- Capture-thread instrumentation --
                //
                // Populated by the V4L2 capture thread and drained
                // each period by the debug report on the strand.  All
                // fields reset to zero at the end of each report so
                // averages reflect a single 1s window.
                //
                // Sequence tracking uses @c vbuf.sequence from
                // VIDIOC_DQBUF to detect kernel-side frame drops
                // (where the camera produced a frame but no buffer
                // was available to hold it).  Loop-iteration timing
                // measures how long our capture loop spends between
                // successive DQBUF returns — if it's significantly
                // longer than the nominal frame period the capture
                // thread is the bottleneck.  DQBUF lag compares
                // @c vbuf.timestamp to wall-clock @c now() so we can
                // tell how stale the frame is by the time we see it.
                Atomic<uint32_t> _lastVbufSequence{0};
                Atomic<int64_t>      _kernelDroppedPeriod{0};
                Atomic<int64_t>      _loopIterationsPeriod{0};
                Atomic<int64_t>      _loopTimeSumUsPeriod{0};
                Atomic<int64_t>      _loopTimeMaxUsPeriod{0};
                Atomic<int64_t>      _dqbufLagSumUsPeriod{0};
                Atomic<int64_t>      _dqbufLagMaxUsPeriod{0};
                Atomic<int64_t>      _dqbufLagCountPeriod{0};
                // Count of frames whose hardware SOE timestamp was so
                // far off the wall clock that we substituted the
                // dequeue time instead.  Should be ~1 at stream
                // startup; any steady-state non-zero value indicates
                // the UVC PTS regression isn't locking (driver bug or
                // camera glitch) and deserves investigation.
                Atomic<int64_t>     _timestampSubstitutedPeriod{0};
                // Capture-thread-only state (no atomic needed):
                bool    _seqInitialized = false;
                int64_t _prevIterUs = 0;
 
                // -- General state --
                FrameRate  _frameRate;
                FrameCount _frameCount{0};
};
 
class V4l2Factory : public MediaIOFactory {
        public:
                V4l2Factory() = default;
 
                String name() const override { return String("V4L2"); }
                String displayName() const override { return String("V4L2 Capture"); }
                String description() const override {
                        return String("V4L2 video capture with optional ALSA audio (Linux)");
                }
 
                bool canBeSource() const override { return true; }
 
                bool            canHandlePath(const String &path) const override;
                StringList      enumerate() const override;
                Config::SpecMap configSpecs() const override;
                List<MediaDesc> queryDevice(const Config &config) const override;
                void            printDeviceInfo(const Config &config) const override;
 
                MediaIO *create(const Config &config, ObjectBase *parent = nullptr) const override;
};
 
PROMEKI_NAMESPACE_END
 
 
#endif // PROMEKI_ENABLE_V4L2