调试预览

在 Unity 编辑器中通过实时覆盖层验证 Vision 捕获，显示活动帧源、捕获统计和源状态。

使用调试预览可视化 Vision 捕获

VisionDebugPreview 将活动帧源的输出以屏幕覆盖层的形式渲染在 Unity 编辑器中，让你能立即通过视觉确认捕获是否正常工作。它还会显示一个实时统计面板，展示帧率、总帧数和源状态。由于此组件专为开发用途设计，因此在玩家构建中会自动禁用——在你发布项目时它不会带来任何运行时开销。

VisionDebugPreview 是一个 仅编辑器 组件。它会在玩家构建中运行时自动禁用。不要将其用于游戏内 UI 或生产环境诊断。

将调试预览添加到场景中

1

添加组件

在场景中选择任意 GameObject——可以是你的帧源所在对象，也可以是专门的调试对象。点击 添加组件 → Convai/Vision/Vision 调试预览（仅编辑器）.

2

分配帧源（可选）

在 帧源组件 字段，拖入你想要预览的 IVisionFrameSource 组件。如果你将其留空，并且 回退到活动帧源 已启用，组件会自动选择场景中第一个正在捕获的源。

3

进入播放模式

按 播放。游戏视图中会出现一个覆盖层，显示实时纹理和统计面板。可使用下方所述的 Inspector 字段调整位置和大小。

---

Inspector 参考

帧源

字段	类型	默认值	说明
帧源组件	MonoBehaviour	（自动解析）	要预览的帧源。留空可使用回退自动发现。
回退到活动帧源	bool	true	当分配的源处于空闲状态或未分配时，自动查找并显示场景中第一个正在积极捕获的源。

覆盖层布局

字段	类型	默认值	说明
覆盖层位置	预览位置	右下角	覆盖层锚定在游戏视图中的角落。
覆盖层宽度	int （160–640）	320	预览覆盖层的像素宽度。
X 偏移	int （0–200）	10	覆盖层边缘与屏幕边缘之间的水平像素距离。
Y 偏移	int （0–200）	10	覆盖层边缘与屏幕边缘之间的垂直像素距离。

宽高比

字段	类型	默认值	说明
使用源宽高比	bool	true	根据帧源的实际捕获尺寸计算覆盖层高度。
自定义宽高比	float （1–3）	1.778 (16:9)	当 使用源宽高比 被禁用时，用于计算覆盖层高度的宽高比。

预览设置

字段	类型	默认值	说明
显示预览	bool	true	启用或禁用图像覆盖层。可在运行时切换。
显示统计信息	bool	true	启用或禁用统计覆盖层。可在运行时切换。

预览位置值

值	覆盖层锚点
左上角	游戏视图的左上角
右上角	右上角
左下角	左下角
右下角	右下角（默认）

---

统计覆盖层

当 显示统计信息 已启用时，覆盖层会显示以下实时数值：

统计项	说明
FPS	当前由帧源产生的每秒帧数
帧数	自捕获开始以来捕获的总帧数
State	当前 VisionSourceState 帧源的（例如， 就绪, 降级)
尺寸	以像素为单位的捕获分辨率

---

运行时脚本

VisionDebugPreview 提供了一个很小的脚本 API，用于切换覆盖层并读取当前统计信息：

using Convai.Runtime.Vision.Debug;

VisionDebugPreview preview = GetComponent<VisionDebugPreview>();

// 切换覆盖层可见性
preview.ShowPreview = false;
preview.ShowStats = true;

// 读取当前捕获统计信息
float fps = preview.CurrentFps;
long frames = preview.FrameCount;
bool capturing = preview.IsCapturing;

---

已知限制

VisionDebugPreview 预览 IVisionFrameSource.CurrentRenderTexture。它确实 不是 显示 WebGL 画布捕获路径。在 WebGL 中，覆盖层会显示为空白或无法初始化，因为 WebGL 构建中没有帧源组件。

如果没有活动的帧源，并且 回退到活动帧源 为 false，覆盖层会显示一个占位符，指示未找到捕获源。启用回退或显式分配帧源即可解决此问题。

---

结论

VisionDebugPreview 让你以零成本在生产构建中实时看到角色所见的一切，以及捕获统计信息。在整个开发过程中使用它，以验证帧源健康状况，确认捕获是否以预期帧率运行，并在问题到达玩家之前将其捕获。有关完整实现示例，请参见 使用示例。有关生产环境脚本模式，请参见 高级主题.