> 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/frame-sources.md).

# 帧源

## 选择并配置视觉帧源

帧源是负责捕获图像并将其以 Y 轴翻转的形式提供给发布器的组件 `RenderTexture`. Convai SDK 附带三个内置帧源——一个用于 Unity 场景摄像机，一个用于物理网络摄像头，一个用于 Meta Quest 透视摄像头——每个都针对其目标平台进行了优化。本页介绍如何添加、配置和排查这三者。

### 选择帧源

| 帧源                        | 适用于                                  | 平台                         |
| ------------------------- | ------------------------------------ | -------------------------- |
| `CameraVisionFrameSource` | 可流式传输任意 Unity 场景摄像机——主摄像机、安防摄像机、俯视视角 | PC、Mac、Android、iOS、主机      |
| `WebcamVisionFrameSource` | 流式传输连接到玩家电脑或移动设备的物理摄像头设备             | PC、Mac、Android、iOS         |
| `QuestVisionFrameSource`  | 在 Meta Quest 头显上流式传输现实世界透视画面         | Meta Quest（需要 Meta XR SDK） |

通过以下方式添加帧源： **添加组件** 并输入类名，或者导航到以下菜单路径中的组件菜单： **Convai → 视觉**.

<figure><img src="/files/0d69003a2d4fd627328c4c6f50eeb6ce5ab5d715" alt=""><figcaption></figcaption></figure>

***

## CameraVisionFrameSource

`CameraVisionFrameSource` 捕获 Unity 的 `摄像机`的输出到一个 `RenderTexture` 并在每一帧将其提供给发布器。当处于活动渲染管线（内置或 SRP/URP）时，它会自动选择正确的捕获后端，前提是 **摄像机捕获模式** 被设置为 `自动`.

**组件菜单路径：** `Convai/视觉/摄像机视觉帧源`

<figure><img src="/files/7ff48ce3abd4de5530b577a686a843dc62e14f2c" alt=""><figcaption></figcaption></figure>

### 检查器参考

#### 捕获设置

<table><thead><tr><th width="169.49993896484375">字段</th><th width="178.5">类型</th><th width="103.5">默认值</th><th>描述</th></tr></thead><tbody><tr><td><strong>捕获预设</strong></td><td><code>CapturePreset</code></td><td><code>均衡</code></td><td>选择预配置的分辨率和帧率组合。设置为 <code>自定义</code> 即可手动输入值。</td></tr><tr><td><strong>捕获宽度</strong></td><td><code>int</code></td><td>—</td><td>输出宽度（像素）。仅在预设为 <code>自定义</code>.</td></tr><tr><td><strong>捕获高度</strong></td><td><code>int</code></td><td>—</td><td>输出高度（像素）。仅在预设为 <code>自定义</code>.</td></tr><tr><td><strong>目标 FPS</strong></td><td><code>int</code></td><td>—</td><td>目标捕获帧率。仅在预设为 <code>自定义</code>.</td></tr><tr><td><strong>摄像机捕获模式</strong></td><td><code>CameraCaptureMode</code></td><td><code>自动</code></td><td>选择渲染管线捕获策略。保持为 <code>自动</code> ，除非另有指示。</td></tr></tbody></table>

#### 摄像机

| 字段        | 类型    | 默认值      | 描述                                     |
| --------- | ----- | -------- | -------------------------------------- |
| **目标摄像机** | `摄像机` | *（自动解析）* | 要捕获的摄像机。如果留空，将解析为 `Camera.main` ，在运行时。 |

#### 调试

<table><thead><tr><th width="196.50006103515625">字段</th><th width="95.00006103515625">类型</th><th width="98.5">默认值</th><th>描述</th></tr></thead><tbody><tr><td><strong>源 ID</strong></td><td><code>字符串</code></td><td><code>"camera"</code></td><td>用于领域事件和多源场景的标识符。</td></tr><tr><td><strong>启用诊断帧健康探测</strong></td><td><code>bool</code></td><td><code>false</code></td><td>执行同步的逐帧像素回读以验证帧内容。仅在诊断黑屏问题时使用；每一帧都会带来 GPU 回读开销。</td></tr></tbody></table>

### 捕获预设值

<table><thead><tr><th width="124.99993896484375">预设</th><th width="105.5">宽度</th><th width="102">高度</th><th width="100.49993896484375">FPS</th><th>使用场景</th></tr></thead><tbody><tr><td><code>低开销</code></td><td>640</td><td>480</td><td>10</td><td>大规模部署、移动端或带宽受限环境</td></tr><tr><td><code>均衡</code></td><td>1280</td><td>720</td><td>15</td><td>通用用途——大多数场景的默认值</td></tr><tr><td><code>高细节</code></td><td>1920</td><td>1080</td><td>30</td><td>对 AI 理解而言细微视觉细节很重要的场景</td></tr><tr><td><code>自定义</code></td><td><em>（手动设置）</em></td><td><em>（手动设置）</em></td><td><em>（手动设置）</em></td><td>完全控制尺寸和帧率</td></tr></tbody></table>

### 摄像机捕获模式值

<table><thead><tr><th width="262">模式</th><th>何时使用</th></tr></thead><tbody><tr><td><code>自动</code></td><td>默认。检测活动渲染管线并自动选择合适的后端。</td></tr><tr><td><code>BuiltInHooks</code></td><td>强制使用 <code>Camera.onPreRender</code> / <code>Camera.onPostRender</code> 回调。仅兼容内置渲染管线。</td></tr><tr><td><code>SrpNative</code></td><td>强制使用 SRP/URP 显式渲染路径（<code>TargetCamera.Render()</code> 在 <code>LateUpdate</code>）。在以下情况使用 <code>自动</code> 无法正确检测 SRP 时。</td></tr><tr><td><code>ExplicitRenderCompatibility</code></td><td>一种兼容性回退方案，显式渲染摄像机。适用于高度定制的渲染设置。</td></tr></tbody></table>

{% hint style="warning" %}
保持 **摄像机捕获模式** 在 `自动` 除非你有特定理由覆盖它。为渲染管线选择错误的后端会导致黑屏或空白视频流。
{% endhint %}

{% hint style="warning" %}
**启用诊断帧健康探测** 每一帧都会执行同步的 GPU 到 CPU 像素回读。仅在调试期间启用，并在发布前禁用它。在生产环境中，SDK 会在内部执行更轻量级的帧健康检查。
{% endhint %}

***

## WebcamVisionFrameSource

`WebcamVisionFrameSource` 使用 Unity 的 `WebCamTexture` API 捕获物理摄像头设备，并将输出转换为一个 `RenderTexture`。它处理设备选择、权限请求（在 Android 和 iOS 上）、自动旋转校正以及分辨率限制。

**组件菜单路径：** `Convai/视觉/网络摄像头视觉帧源`

<figure><img src="/files/2f9c8cdd7c974d174472895e86110e9d8a553520" alt=""><figcaption></figcaption></figure>

### 检查器参考

#### 网络摄像头设置

<table><thead><tr><th width="206.00006103515625">字段</th><th width="82.49993896484375">类型</th><th width="74.00006103515625">默认值</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></td><td><code>640</code></td><td>发送给驱动的请求捕获宽度。实际分辨率可能不同。</td></tr><tr><td><strong>请求高度</strong></td><td><code>int</code></td><td><code>480</code></td><td>发送给驱动的请求捕获高度。</td></tr><tr><td><strong>请求 FPS</strong></td><td><code>int</code></td><td><code>15</code></td><td>发送给驱动的请求帧率。</td></tr><tr><td><strong>最大输出宽度</strong></td><td><code>int</code></td><td><code>1280</code></td><td>输出的最大宽度 <code>RenderTexture</code>。宽于此值的帧会被缩小。设置为 <code>0</code> 可禁用缩放。</td></tr><tr><td><strong>最大输出高度</strong></td><td><code>int</code></td><td><code>720</code></td><td>输出的最大高度 <code>RenderTexture</code>.</td></tr></tbody></table>

#### 源标识

<table><thead><tr><th width="109.5">字段</th><th width="82.9998779296875">类型</th><th width="101.5">默认值</th><th>描述</th></tr></thead><tbody><tr><td><strong>源 ID</strong></td><td><code>字符串</code></td><td><code>"webcam"</code></td><td>用于领域事件和多源场景的标识符。</td></tr></tbody></table>

### 列出可用设备

要在运行时枚举已连接的网络摄像头设备：

```csharp
string[] deviceNames = WebcamVisionFrameSource.GetAvailableDeviceNames();
foreach (string name in deviceNames)
    Debug.Log(name);
```

### 在运行时切换设备

若要在不中断会话的情况下切换到其他网络摄像头：

```csharp
// Requires a reference to the WebcamVisionFrameSource component
WebcamVisionFrameSource webcam = GetComponent<WebcamVisionFrameSource>();
IConvaiOperation<Unit> op = webcam.SwitchWebcamAsync("Front Camera");
```

### 权限流程（Android / iOS）

在 Android 和 iOS 上，组件会在以下情况异步请求摄像头权限：当 `StartCapture()` 被调用时。 `状态` 属性会经历以下状态转换：

`空闲 → 等待权限 → 启动中 → 就绪`

如果用户拒绝权限， `状态` 变为 `失败` 和 `错误类型` 被设置为 `权限被拒绝`。你可以通过以下方式监控它： `IVisionFrameSourceStatusProvider.StatusChanged` ——参见 [高级主题](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/advanced-topics.md) 了解详情。

{% hint style="info" %}
在 Android 和 iOS 上，系统摄像头权限对话框会在以下情况首次出现： `StartCapture()` 运行时。请确保你的应用清单或 `Info.plist` 在发布前声明摄像头使用说明。
{% endhint %}

***

## QuestVisionFrameSource

`QuestVisionFrameSource` 从 Meta Quest 头显流式传输现实世界透视画面，使 Convai 角色能够实时查看用户所处的物理环境。该组件通过反射绑定到 Meta 的 `PassthroughCameraAccess` API，因此 SDK 不会对 Meta XR 包产生强编译期依赖。

**组件菜单路径：** `Convai/视觉/Quest 视觉帧源`

<figure><img src="/files/255eae068b8e671de517cb73f0ec9e47b6fcd549" alt=""><figcaption></figcaption></figure>

### 检查器参考

#### Quest 摄像头访问

<table><thead><tr><th width="159">字段</th><th width="150.49993896484375">类型</th><th width="162.5">默认值</th><th>描述</th></tr></thead><tbody><tr><td><strong>透视摄像头访问</strong></td><td><code>MonoBehaviour</code></td><td><em>（自动发现）</em></td><td>对以下项的引用： <code>PassthroughCameraAccess</code> 场景中的组件。留空可自动查找。</td></tr></tbody></table>

#### 输出设置

<table><thead><tr><th width="178.5">字段</th><th width="95.5">类型</th><th width="191.5">默认值</th><th>描述</th></tr></thead><tbody><tr><td><strong>源 ID</strong></td><td><code>字符串</code></td><td><code>"quest-passthrough"</code></td><td>用于领域事件的标识符。</td></tr><tr><td><strong>最大输出宽度</strong></td><td><code>int</code></td><td><code>1280</code></td><td>输出的最大宽度 <code>RenderTexture</code>.</td></tr><tr><td><strong>最大输出高度</strong></td><td><code>int</code></td><td><code>720</code></td><td>输出的最大高度 <code>RenderTexture</code>.</td></tr><tr><td><strong>目标帧率</strong></td><td><code>int</code></td><td><code>15</code></td><td>捕获的目标每秒帧数。</td></tr><tr><td><strong>翻转 Y 轴</strong></td><td><code>bool</code></td><td><code>true</code></td><td>垂直翻转透视纹理。为确保视频方向正确而必需；仅当 Meta SDK 更改其坐标约定时才禁用。</td></tr></tbody></table>

{% hint style="warning" %}
`QuestVisionFrameSource` 需要 **Meta XR SDK** 已安装。在非 Quest 平台上，组件会进入 `失败` 状态，且 `错误类型` 设为 `不支持的平台` ，并且不产生任何帧。
{% endhint %}

{% hint style="info" %}
与 `PassthroughCameraAccess` 的绑定在运行时通过反射建立。如果 Meta XR 包更新且 `PassthroughCameraAccess` 其 API 发生变化，组件将记录错误并进入 `失败` 状态。在这种情况下请检查 SDK 更新。
{% endhint %}

***

## 源状态参考

这三种帧源都实现了 `IVisionFrameSourceStatusProvider`，它提供一个 `状态` 属性和一个 `StatusChanged` 事件。

### VisionSourceState

<table><thead><tr><th width="197.50006103515625">状态</th><th>含义</th></tr></thead><tbody><tr><td><code>空闲</code></td><td>捕获尚未开始。</td></tr><tr><td><code>AwaitingPermission</code></td><td>等待用户授予摄像头权限（Android / iOS）。</td></tr><tr><td><code>Starting</code></td><td>捕获正在初始化——设备正在打开，RenderTexture 正在创建。</td></tr><tr><td><code>Ready</code></td><td>捕获正在运行并生成帧。</td></tr><tr><td><code>Degraded</code></td><td>捕获正在运行，但帧健康检查检测到问题（例如连续空白帧）。</td></tr><tr><td><code>Stopped</code></td><td>捕获已正常停止。</td></tr><tr><td><code>失败</code></td><td>捕获失败且无法继续。请检查 <code>错误类型</code> 和 <code>StatusMessage</code> 了解详情。</td></tr></tbody></table>

### VisionSourceErrorKind

<table><thead><tr><th width="211.5">错误类型</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>此平台不支持该源（例如 <code>QuestVisionFrameSource</code> 在 PC 上）。</td></tr><tr><td><code>DeviceUnavailable</code></td><td>无法打开请求的摄像头设备。</td></tr><tr><td><code>InvalidConfiguration</code></td><td>某个字段值超出范围或不一致（请检查 <code>StatusMessage</code>).</td></tr><tr><td><code>未知</code></td><td>发生了意外错误。</td></tr></tbody></table>

有关针对这些状态进行脚本编写以及响应 `StatusChanged` 事件，请参见 [高级主题](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/advanced-topics.md).

## 结论

每种帧源都面向特定平台和捕获场景——请使用 `CameraVisionFrameSource` 用于 Unity 场景摄像机， `WebcamVisionFrameSource` 用于桌面和移动端的物理设备，以及 `QuestVisionFrameSource` 用于 Meta Quest 透视画面。随着帧源已配置并处于 `Ready` 状态，请继续到 [发布与策略](/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision/publishing-and-policies.md) 以控制帧何时以及如何发送到 Convai 后端。


---

# 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/frame-sources.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.