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 = 不修改；非 null = 限定算法处理的输入帧率</para>
    /// <para>性能优化：降低此值可显著减少高分辨率下的 GPU/CPU 负荷（如 4K 从 30fps 降到 5fps）</para>
    /// </summary>
    public int? TargetFps { 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 &&
        TargetFps is null &&
        EnableStreamOutput is null &&
        RenderHandle is null &&
        StreamType is null &&
        VendorExtensions.Count == 0;

    #endregion
}