namespace SHH.CameraSdk;

/// <summary>
/// 视频分辨率档位描述符（Record 类型，不可变对象）
/// 核心职责：定义相机通道在特定编码格式下支持的分辨率、帧率上限及友好描述
/// 协作场景：
/// <para>1. 前端界面：展示清晰度选择下拉列表</para>
/// <para>2. 配置校验：下发分辨率前判断是否符合硬件能力，防止超限黑屏</para>
/// <para>3. 性能评估：通过总像素量计算编码/解码的计算负载与带宽压力</para>
/// </summary>
/// <param name="Width">画面像素宽度（如 1920、3840）</param>
/// <param name="Height">画面像素高度（如 1080、2160）</param>
/// <param name="MaxFps">该分辨率下硬件支持的最大输出帧率（防止超限配置）</param>
/// <param name="Description">档位友好描述（如 "高清(1080P/H.265)"）</param>
public record ResolutionProfile(
    int Width,
    int Height,
    int MaxFps,
    string Description
)
{
    #region --- 计算属性 (Derived Properties) ---

    /// <summary>
    /// 当前档位的总像素量
    /// 业务用途：衡量编码/解码的计算负载、网络传输的带宽压力
    /// 计算公式：Width * Height
    /// </summary>
    public long TotalPixels => (long)Width * Height;

    /// <summary>
    /// 当前档位的屏幕宽高比
    /// 业务用途：前端渲染容器（WinForm/WPF/Web）自动调整比例，避免画面拉伸变形
    /// 保护逻辑：高度为 0 时返回 0，防止除零异常
    /// </summary>
    public double AspectRatio => Height == 0 ? 0 : (double)Width / Height;

    /// <summary>
    /// 判断当前档位是否属于高清范畴（行业标准：720P 及以上，即 1280x720 分辨率）
    /// 业务用途：前端分类展示、带宽策略选择
    /// </summary>
    public bool IsHighDefinition => Width >= 1280 && Height >= 720;

    #endregion

    #region --- 重写方法 (Overridden Methods) ---

    /// <summary>
    /// 格式化分辨率档位的显示文本
    /// 输出格式：友好描述 (宽x高@最大帧率fps)
    /// 示例：高清(1080P/H.265) (1920x1080@30fps)
    /// </summary>
    /// <returns>格式化的显示字符串</returns>
    public override string ToString() => $"{Description} ({Width}x{Height}@{MaxFps}fps)";

    #endregion
}