120 lines
5.0 KiB
C#
120 lines
5.0 KiB
C#
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
|
||
} |