namespace SHH.CameraSdk;

/// <summary>
/// 帧需求定义模型
/// 功能：描述某个程序/模块对视频帧的消费需求，用于帧分发调度与帧率控制
/// 用途：配合 FrameController，实现按订阅者需求精准分配帧资源，避免资源浪费
/// </summary>
public class FrameRequirement
{
    #region --- 订阅者核心标识 (Subscriber Core Identification) ---

    /// <summary> 订阅者唯一ID（如 "Client_A"、"AI_Service"、"WPF_Display_Main"） </summary>
    /// <remarks> 用于区分不同的帧消费模块，作为帧分发路由的关键标识 </remarks>
    public string AppId { get; set; } = string.Empty;

    #endregion

    #region --- 帧需求参数 (Frame Requirement Parameters) ---

    /// <summary> 目标帧率（单位：fps，订阅者期望的每秒接收帧数，0 表示无特定需求） </summary>
    /// <remarks> 例如：UI 预览需 8fps，AI 分析需 2fps，按需分配以节省计算资源 </remarks>
    public int TargetFps { get; set; } = 0;

    /// <summary> 上次获取帧的时间点（单位：毫秒，通常为 Environment.TickCount64） </summary>
    /// <remarks> 用于帧率控制算法，判断是否达到订阅者的目标帧率需求 </remarks>
    public long LastCaptureTick { get; set; } = 0;

    #endregion

    #region --- 需求状态控制 (Requirement Status Control) ---

    /// <summary> 需求是否激活（true=正常接收帧，false=暂停接收，保留配置） </summary>
    /// <remarks> 支持动态启停订阅，无需删除需求配置，提升灵活性 </remarks>
    public bool IsActive { get; set; } = true;

    #endregion
}