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

SHH.CameraSdk/Core/Telemetry/FrameTrace.cs

@@ -0,0 +1,43 @@
+using System.Collections.Generic;
+namespace SHH.CameraSdk;
+
+/// <summary>
+/// 帧追踪数据模型
+/// 功能：记录单帧数据的生命周期关键信息，用于帧流转监控、丢帧分析与性能排查
+/// 适用场景：配合全局遥测或调试工具，追溯帧的处理路径、耗时及最终状态
+/// </summary>
+public class FrameTrace
+{
+    #region --- 帧核心标识 (Frame Core Identification) ---
+
+    /// <summary> 帧唯一序列号（全局唯一，用于关联帧的全生命周期） </summary>
+    public long FrameId { get; set; }
+
+    /// <summary> 帧产生时间戳（单位：毫秒，通常为 Environment.TickCount64 或 UTC 时间戳） </summary>
+    public long Timestamp { get; set; }
+
+    #endregion
+
+    #region --- 帧状态信息 (Frame Status Information) ---
+
+    /// <summary> 帧是否被丢弃（true=已丢弃，false=正常处理/分发） </summary>
+    public bool IsDropped { get; set; }
+
+    /// <summary> 帧丢弃原因（仅 IsDropped 为 true 时有效） </summary>
+    /// <remarks>示例值："NoSubscribers"（无订阅者）、"FpsLimit"（帧率限制）、"PipelineFull"（处理管道满）</remarks>
+    public string DropReason { get; set; } = string.Empty;
+
+    /// <summary> 帧最终分发目标列表（记录该帧被发送到的订阅者/模块标识） </summary>
+    /// <remarks>示例值：["WPF_Display_Main", "AI_Behavior_Engine"]</remarks>
+    public List<string> Targets { get; set; } = new();
+
+    #endregion
+
+    #region --- 帧性能指标 (Frame Performance Metrics) ---
+
+    /// <summary> 帧处置总耗时（单位：毫秒） </summary>
+    /// <remarks>计算范围：从帧产生到最终处理完成/丢弃的总时间，用于性能瓶颈分析</remarks>
+    public double ProcessDurationMs { get; set; }
+
+    #endregion
+}