海康摄像头取流示例初始签入

SHH.CameraSdk/Core/Features/FrameConsumer.cs

@@ -0,0 +1,171 @@
+using OpenCvSharp;
+
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// [消费者] 专用渲染线程（零延迟设计）
+/// 核心策略：
+/// <para>1. 容量为1的阻塞队列：仅保留最新一帧，杜绝帧堆积</para>
+/// <para>2. 非阻塞入队+主动丢帧：渲染慢时直接丢弃新帧，确保主线程不阻塞</para>
+/// <para>3. 引用计数联动：丢帧时立即释放引用，内存自动回池复用</para>
+/// </summary>
+public class FrameConsumer : IDisposable
+{
+    #region --- 私有资源与状态 (Private Resources & States) ---
+
+    /// <summary> 帧缓冲队列（容量1）：仅存储最新一帧，保证零延迟渲染 </summary>
+    /// <remarks> BlockingCollection 封装线程安全操作，GetConsumingEnumerable 支持取消令牌 </remarks>
+    private readonly BlockingCollection<SmartFrame> _frameBuffer = new(1);
+
+    /// <summary> 取消令牌源：用于终止渲染循环 </summary>
+    private readonly CancellationTokenSource _cts = new();
+
+    /// <summary> 后台渲染任务 </summary>
+    private Task? _renderTask;
+
+    /// <summary> OpenCV 窗口名称 </summary>
+    private readonly string _windowName;
+
+    #endregion
+
+    #region --- 构造与生命周期 (Constructor & Lifecycle) ---
+
+    /// <summary>
+    /// 初始化帧渲染消费者
+    /// </summary>
+    /// <param name="windowName">OpenCV 显示窗口名称</param>
+    public FrameConsumer(string windowName = "Zero Latency Preview")
+    {
+        _windowName = windowName;
+    }
+
+    /// <summary>
+    /// 启动渲染线程
+    /// </summary>
+    public void Start()
+    {
+        // 防止重复启动
+        if (_renderTask != null) return;
+
+        // 启动长期运行的渲染任务，提升线程调度优先级
+        _renderTask = Task.Factory.StartNew(RenderLoop, TaskCreationOptions.LongRunning);
+        Console.WriteLine($"[Consumer] 渲染线程启动成功，窗口名称: {_windowName}");
+    }
+
+    /// <summary>
+    /// 停止渲染线程并清理资源
+    /// </summary>
+    public void Stop()
+    {
+        // 发送取消信号，终止渲染循环
+        _cts.Cancel();
+        // 标记队列完成添加，触发 GetConsumingEnumerable 退出遍历
+        _frameBuffer.CompleteAdding();
+
+        // 等待渲染任务结束（最多等待1秒，防止卡死）
+        if (_renderTask != null)
+        {
+            Task.WaitAny(_renderTask, Task.Delay(1000));
+            _renderTask = null;
+        }
+
+        // 清理队列残余帧：释放所有未消费帧的引用，防止内存泄漏
+        while (_frameBuffer.TryTake(out var residualFrame))
+        {
+            residualFrame.Dispose();
+        }
+
+        Console.WriteLine($"[Consumer] 渲染线程已停止，窗口: {_windowName}");
+    }
+
+    #endregion
+
+    #region --- 帧入队与渲染逻辑 (Frame Enqueue & Render Logic) ---
+
+    /// <summary>
+    /// [生产端入口] 接收帧并尝试入队（非阻塞）
+    /// </summary>
+    /// <param name="frame">待渲染的智能帧</param>
+    public void Enqueue(SmartFrame frame)
+    {
+        // 防护：线程已停止，直接释放帧引用
+        if (_cts.IsCancellationRequested)
+        {
+            frame.Dispose();
+            return;
+        }
+
+        // 核心零延迟策略：非阻塞尝试入队
+        // 队列满 → 上一帧未渲染完成 → 丢弃当前帧，释放引用
+        if (!_frameBuffer.TryAdd(frame))
+        {
+            frame.Dispose();
+            // Debug.WriteLine($"[Drop] 渲染线程[{_windowName}]处理过慢，丢弃一帧");
+        }
+        // 入队成功 → 帧由队列托管，等待渲染线程消费
+    }
+
+    /// <summary>
+    /// 后台渲染循环（核心逻辑）
+    /// </summary>
+    private void RenderLoop()
+    {
+        // 创建 OpenCV 显示窗口
+        Cv2.NamedWindow(_windowName, WindowFlags.Normal);
+
+        try
+        {
+            // 阻塞遍历队列：队列空时等待，收到取消信号时退出
+            foreach (var frame in _frameBuffer.GetConsumingEnumerable(_cts.Token))
+            {
+                try
+                {
+                    // 渲染有效性校验：Mat 未释放且不为空
+                    if (frame.InternalMat != null && !frame.InternalMat.IsDisposed)
+                    {
+                        // 零拷贝渲染：直接引用 InternalMat，无内存复制开销
+                        Cv2.ImShow(_windowName, frame.InternalMat);
+                        // 1ms 等待 UI 事件响应（必须调用，否则窗口无响应）
+                        Cv2.WaitKey(1);
+                    }
+                }
+                catch (Exception ex)
+                {
+                    Debug.WriteLine($"[RenderError] 窗口[{_windowName}]渲染失败: {ex.Message}");
+                }
+                finally
+                {
+                    // 至关重要：渲染完成后释放帧引用
+                    // 引用计数归零 → 帧自动回池复用，避免内存泄漏
+                    frame.Dispose();
+                }
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            // 正常取消，无需处理
+            Debug.WriteLine($"[RenderInfo] 窗口[{_windowName}]渲染循环已取消");
+        }
+        finally
+        {
+            // 销毁 OpenCV 窗口，释放 UI 资源
+            Cv2.DestroyWindow(_windowName);
+        }
+    }
+
+    #endregion
+
+    #region --- 资源释放 (Disposal) ---
+
+    /// <summary>
+    /// 释放所有资源
+    /// </summary>
+    public void Dispose()
+    {
+        Stop();
+        _frameBuffer.Dispose();
+        _cts.Dispose();
+    }
+
+    #endregion
+}