> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/debug-preview.md).

# 调试预览

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

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

{% hint style="warning" %}
`VisionDebugPreview` 是一个 **仅编辑器** 组件。它会在玩家构建中运行时自动禁用。不要将其用于游戏内 UI 或生产环境诊断。
{% endhint %}

### 将调试预览添加到场景中

{% stepper %}
{% step %}
**添加组件**

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

<figure><img src="/files/909efd2cfbd8e5bd85928e048668544d665e6c2b" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**分配帧源（可选）**

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

{% step %}
**进入播放模式**

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

<figure><img src="/files/efb0ea40846e0570464bc740db8e18dcac0fc59e" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

***

### Inspector 参考

#### 帧源

<table><thead><tr><th width="170.49993896484375">字段</th><th width="149.99993896484375">类型</th><th width="143.5">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>帧源组件</strong></td><td><code>MonoBehaviour</code></td><td><em>（自动解析）</em></td><td>要预览的帧源。留空可使用回退自动发现。</td></tr><tr><td><strong>回退到活动帧源</strong></td><td><code>bool</code></td><td><code>true</code></td><td>当分配的源处于空闲状态或未分配时，自动查找并显示场景中第一个正在积极捕获的源。</td></tr></tbody></table>

#### 覆盖层布局

<table><thead><tr><th width="156.49993896484375">字段</th><th width="162">类型</th><th width="133.5">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>覆盖层位置</strong></td><td><code>预览位置</code></td><td><code>右下角</code></td><td>覆盖层锚定在游戏视图中的角落。</td></tr><tr><td><strong>覆盖层宽度</strong></td><td><code>int</code> （160–640）</td><td><code>320</code></td><td>预览覆盖层的像素宽度。</td></tr><tr><td><strong>X 偏移</strong></td><td><code>int</code> （0–200）</td><td><code>10</code></td><td>覆盖层边缘与屏幕边缘之间的水平像素距离。</td></tr><tr><td><strong>Y 偏移</strong></td><td><code>int</code> （0–200）</td><td><code>10</code></td><td>覆盖层边缘与屏幕边缘之间的垂直像素距离。</td></tr></tbody></table>

#### 宽高比

<table><thead><tr><th width="198.99993896484375">字段</th><th width="127.99993896484375">类型</th><th width="125.5">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>使用源宽高比</strong></td><td><code>bool</code></td><td><code>true</code></td><td>根据帧源的实际捕获尺寸计算覆盖层高度。</td></tr><tr><td><strong>自定义宽高比</strong></td><td><code>float</code> （1–3）</td><td><code>1.778</code> (16:9)</td><td>当 <strong>使用源宽高比</strong> 被禁用时，用于计算覆盖层高度的宽高比。</td></tr></tbody></table>

#### 预览设置

<table><thead><tr><th width="141.5">字段</th><th width="83.5">类型</th><th width="100.5">默认值</th><th>说明</th></tr></thead><tbody><tr><td><strong>显示预览</strong></td><td><code>bool</code></td><td><code>true</code></td><td>启用或禁用图像覆盖层。可在运行时切换。</td></tr><tr><td><strong>显示统计信息</strong></td><td><code>bool</code></td><td><code>true</code></td><td>启用或禁用统计覆盖层。可在运行时切换。</td></tr></tbody></table>

### 预览位置值

<table><thead><tr><th width="330.49993896484375">值</th><th>覆盖层锚点</th></tr></thead><tbody><tr><td><code>左上角</code></td><td>游戏视图的左上角</td></tr><tr><td><code>右上角</code></td><td>右上角</td></tr><tr><td><code>左下角</code></td><td>左下角</td></tr><tr><td><code>右下角</code></td><td>右下角（默认）</td></tr></tbody></table>

***

### 统计覆盖层

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

<table><thead><tr><th width="192.5">统计项</th><th>说明</th></tr></thead><tbody><tr><td><strong>FPS</strong></td><td>当前由帧源产生的每秒帧数</td></tr><tr><td><strong>帧数</strong></td><td>自捕获开始以来捕获的总帧数</td></tr><tr><td><strong>State</strong></td><td>当前 <code>VisionSourceState</code> 帧源的（例如， <code>就绪</code>, <code>降级</code>)</td></tr><tr><td><strong>尺寸</strong></td><td>以像素为单位的捕获分辨率</td></tr></tbody></table>

***

### 运行时脚本

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

```csharp
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;
```

***

### 已知限制

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

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

***

## 结论

`VisionDebugPreview` 让你以零成本在生产构建中实时看到角色所见的一切，以及捕获统计信息。在整个开发过程中使用它，以验证帧源健康状况，确认捕获是否以预期帧率运行，并在问题到达玩家之前将其捕获。有关完整实现示例，请参见 [使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/usage-examples.md)。有关生产环境脚本模式，请参见 [高级主题](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/advanced-topics.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/debug-preview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.