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

SHH.CameraSdk/Abstractions/Models/DynamicStreamOptions.cs

@@ -0,0 +1,120 @@
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 视频流动态配置项（运行时可调整参数容器）
+/// 核心职责：承载无需重启流即可动态调整的视频参数，支持局部更新
+/// 核心特性：
+/// <para>1. Nullable 模式：仅非空字段会触发参数更新，避免全量重置导致的性能抖动</para>
+/// <para>2. 分类管理：按画面策略、帧率控制、传输输出、厂商扩展划分参数，逻辑清晰</para>
+/// <para>3. 空值检查：通过 IsEmpty 判断是否存在有效配置，避免无效底层 SDK 调用</para>
+/// </summary>
+public class DynamicStreamOptions
+{
+    #region --- 1. 画面策略 (Resolution & Scaling) ---
+
+    /// <summary>
+    /// 目标输出宽度（像素）
+    /// <para>Nullable 规则：null = 保持当前配置；非 null = 触发图像缩放逻辑</para>
+    /// <para>注意事项：建议与 TargetHeight 成对设置，避免画面比例失衡</para>
+    /// </summary>
+    public int? TargetWidth { get; set; }
+
+    /// <summary>
+    /// 目标输出高度（像素）
+    /// <para>Nullable 规则：null = 保持当前配置；非 null = 触发图像缩放逻辑</para>
+    /// <para>协作关系：与 TargetWidth 配合使用，若仅设置其一，会按原始宽高比自动计算另一值</para>
+    /// </summary>
+    public int? TargetHeight { get; set; }
+
+    /// <summary>
+    /// 图像放大开关
+    /// <para>Nullable 规则：null = 保持当前策略；true = 允许放大；false = 禁止放大</para>
+    /// <para>性能影响：禁止放大可节省插值计算资源，适合低性能设备</para>
+    /// </summary>
+    public bool? AllowEnlarge { get; set; }
+
+    /// <summary>
+    /// 图像缩小开关
+    /// <para>Nullable 规则：null = 保持当前策略；true = 允许缩小；false = 禁止缩小</para>
+    /// <para>适用场景：禁止缩小可保留原始画质，适合需要高清分析的场景</para>
+    /// </summary>
+    public bool? AllowShrink { get; set; }
+
+    #endregion
+
+    #region --- 2. 频率控制 (Frame Rate Control) ---
+
+    /// <summary>
+    /// 目标渲染/显示帧率（fps）
+    /// <para>Nullable 规则：null = 不修改；0 = 跟随原始流速度；非 0 = 强制限定显示帧率</para>
+    /// <para>作用域：仅影响 UI 预览层，不会改变底层码流的采集帧率</para>
+    /// </summary>
+    public int? TargetDisplayFps { get; set; }
+
+    /// <summary>
+    /// 目标 AI 分析帧率（fps）
+    /// <para>Nullable 规则：null = 不修改；非 null = 限定算法处理的输入帧率</para>
+    /// <para>性能优化：降低此值可显著减少高分辨率下的 GPU/CPU 负荷（如 4K 从 30fps 降到 5fps）</para>
+    /// </summary>
+    public int? TargetAnalyzeFps { get; set; }
+
+    #endregion
+
+    #region --- 3. 传输与输出 (Transmission & Output) ---
+
+    /// <summary>
+    /// Web 推流开关
+    /// <para>Nullable 规则：null = 保持当前状态；true = 启动推流；false = 停止推流</para>
+    /// <para>协作组件：开启后会将处理后的视频帧推送到流媒体服务器（如 FFmpeg/RTSP 服务器）</para>
+    /// </summary>
+    public bool? EnableStreamOutput { get; set; }
+
+    /// <summary>
+    /// 渲染窗体句柄
+    /// <para>Nullable 规则：null = 保持当前窗口；非 null = 切换到新窗口渲染</para>
+    /// <para>适用场景：支持视频窗口拖拽、多显示器切换等交互操作</para>
+    /// </summary>
+    public IntPtr? RenderHandle { get; set; }
+
+    /// <summary>
+    /// 码流类型切换
+    /// <para>取值规则：0 = 主码流(高清/大带宽)；1 = 子码流(标清/低延迟)；2 = 第三码流</para>
+    /// <para>Nullable 规则：null = 不切换；非 null = 执行码流切换</para>
+    /// <para>注意事项：切换会销毁并重建预览句柄，可能导致短暂的画面中断</para>
+    /// </summary>
+    public int? StreamType { get; set; }
+
+    #endregion
+
+    #region --- 4. 厂商扩展 (Vendor Specific) ---
+
+    /// <summary>
+    /// 厂商特有参数扩展字典
+    /// <para>用途：存放无法标准化的品牌专属功能参数</para>
+    /// <para>示例：海康 "FocusMode"=Auto/Manual；大华 "SmartH264"=true/false</para>
+    /// <para>注意事项：键值对需与对应厂商 SDK 的参数名一致，否则无效</para>
+    /// </summary>
+    public Dictionary<string, object> VendorExtensions { get; set; } = new();
+
+    #endregion
+
+    #region --- 5. 配置有效性检查 ---
+
+    /// <summary>
+    /// 逻辑空检查：判断当前配置包是否包含任何有效修改项
+    /// <para>使用场景：调用 SDK 前判断，避免无意义的底层调用，提升性能</para>
+    /// </summary>
+    public bool IsEmpty =>
+        TargetWidth is null &&
+        TargetHeight is null &&
+        AllowEnlarge is null &&
+        AllowShrink is null &&
+        TargetDisplayFps is null &&
+        TargetAnalyzeFps is null &&
+        EnableStreamOutput is null &&
+        RenderHandle is null &&
+        StreamType is null &&
+        VendorExtensions.Count == 0;
+
+    #endregion
+}