> 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/convai-unity-sdk/features/vision/frame-sources.md).

# 视觉帧源

说明为角色捕获可见视频的帧来源，涵盖场景相机、网络摄像头和 Meta Quest 透视画面。

帧源会捕获场景中的图像，并将它们作为上下翻转的 `RenderTexture` 用于 `ConvaiVisionPublisher` 流进行输出。Convai SDK 自带三个内置帧源： `CameraVisionFrameSource` 用于 Unity 场景相机， `WebcamVisionFrameSource` 用于物理设备，且 `QuestVisionFrameSource` 用于 Meta Quest 透视模式。

| 帧源                        | 最适合                                 | 平台                                |
| ------------------------- | ----------------------------------- | --------------------------------- |
| `CameraVisionFrameSource` | 流式传输任意 Unity 场景相机——主相机、安防相机、俯视视图    | PC、Mac、Android、iOS、主机             |
| `WebcamVisionFrameSource` | 流式传输连接到玩家机器或移动设备的物理摄像头设备            | PC、Mac、Android、iOS                |
| `QuestVisionFrameSource`  | 流式传输 Meta Quest 3 或 3S 头显上的真实世界透视画面 | Meta Quest 3 / 3S（需要 Meta XR SDK） |

通过添加帧源 **添加组件** 并输入类名，或在以下位置的组件菜单中导航： **Convai → Vision**.

### CameraVisionFrameSource

`CameraVisionFrameSource` 捕获 Unity 的 `Camera`的输出，并将其提供给发布器。 `RenderTexture` 它会在每一帧自动选择适用于当前渲染管线（Built-in 或 SRP/URP）的正确捕获后端，当 **相机捕获模式** 设置为 `自动`.

**组件菜单路径：** `Convai/Vision/Camera Vision Frame Source`

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FaKI0RXZXBWMQR9Vh417C%2Fimage.png?alt=media&amp;token=b6d32b1e-ccc0-422b-b749-d533b9aa1d68" alt="CameraVisionFrameSource Inspector"><figcaption><p>CameraVisionFrameSource Inspector。</p></figcaption></figure>

**捕获设置**

| 字段         | 类型                  | 默认   | 说明                                   |
| ---------- | ------------------- | ---- | ------------------------------------ |
| **捕获预设**   | `CapturePreset`     | `平衡` | 选择预配置的分辨率和帧率组合。设置为 `Custom` 以手动输入数值。 |
| **捕获宽度**   | `int`               | —    | 以像素为单位的输出宽度。仅当预设为 `Custom`.          |
| **捕获高度**   | `int`               | —    | 以像素为单位的输出高度。仅当预设为 `Custom`.          |
| **目标 FPS** | `int`               | —    | 目标捕获帧率。仅当预设为 `Custom`.               |
| **相机捕获模式** | `CameraCaptureMode` | `自动` | 选择渲染管线捕获策略。除非画面是黑屏，否则保持为 `自动` 。      |

**Camera**

| 字段                | 类型       | 默认       | 说明                               |
| ----------------- | -------- | -------- | -------------------------------- |
| **Target Camera** | `Camera` | *（自动解析）* | 要捕获的相机。如果留空，将解析为 `Camera.main` 。 |

如果 **Target Camera** 为空且场景中没有任何相机标记为 **MainCamera**，则帧源会在运行时进入 `Failed` 状态，并带有 `ErrorKind = InvalidConfiguration`。请始终显式指定相机，或确保有一台相机带有 **MainCamera** 标记。

**调试**

| 字段            | 类型       | 默认         | 说明                                                      |
| ------------- | -------- | ---------- | ------------------------------------------------------- |
| **源 ID**      | `string` | `"camera"` | 用于领域事件和多源场景中的标识符。                                       |
| **启用诊断帧健康探针** | `bool`   | `false`    | 执行同步的逐帧像素回读以验证帧内容。仅在排查黑屏问题时使用；每帧都会产生一次 GPU 回读开销。发布前请禁用。 |

**捕获预设值**

| 预设           | 宽度       | 高度       | FPS      | 使用场景                    |
| ------------ | -------- | -------- | -------- | ----------------------- |
| `低开销`        | 640      | 480      | 10       | 大规模部署、移动端或带宽受限环境        |
| `平衡`         | 1280     | 720      | 15       | 通用用途——大多数场景的默认选择        |
| `HighDetail` | 1920     | 1080     | 30       | 对 AI 理解而言，细节视觉信息至关重要的场景 |
| `Custom`     | *（手动设置）* | *（手动设置）* | *（手动设置）* | 完全控制尺寸和帧率               |

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FuH5swxR0OIRTA745WqNU%2Fimage.png?alt=media&amp;token=ec9a30a9-c52f-4cf3-9f5c-cdbcb58e369f" alt="Capture preset options in the Inspector dropdown"><figcaption><p>Inspector 下拉菜单中的捕获预设选项。</p></figcaption></figure>

**相机捕获模式值**

| 模式                            | 何时使用                                                                                                                                                                  |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `自动`                          | 默认。在 Built-in Render Pipeline 上，使用渲染钩子（`Camera.onPreRender` / `Camera.onPostRender`）。在 SRP/URP 上，使用显式渲染路径（`TargetCamera.Render()` 在 `LateUpdate`）。请先选择此项，仅在画面为黑屏时再覆盖。 |
| `BuiltInHooks`                | 强制使用 Built-in Render Pipeline 捕获钩子。仅与 Built-in RP 兼容——在 SRP/URP 上选择此项会产生黑屏画面。                                                                                         |
| `ExplicitRenderCompatibility` | 强制每帧进行一次显式相机渲染。当 `自动` 在 SRP/URP 上产生黑屏，或用于高度自定义的渲染设置时使用。会按配置的捕获 FPS 增加一次受限的额外相机渲染。                                                                                     |
| `SrpNative`                   | **此 SDK 构建中不可用。** 见下方说明。                                                                                                                                              |

{% hint style="danger" %}
**`SrpNative` 在当前 SDK 构建中不可正常工作。** 选择它会使 `CameraVisionFrameSource` 立即进入 `Failed` 状态，带有 `ErrorKind = UnsupportedPlatform`。如果 `自动` 如果你的 SRP/URP 项目出现黑屏，请使用 `ExplicitRenderCompatibility` 替代。
{% endhint %}

### WebcamVisionFrameSource

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

**组件菜单路径：** `Convai/Vision/Webcam Vision Frame Source`

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FEttJqgxRJv03l4yph6zn%2Fimage.png?alt=media&amp;token=69ddccbd-661e-4eb7-af3a-686307134b87" alt="WebcamVisionFrameSource Inspector"><figcaption><p>WebcamVisionFrameSource Inspector。</p></figcaption></figure>

**摄像头设置**

| 字段          | 类型       | 默认     | 说明                                                |
| ----------- | -------- | ------ | ------------------------------------------------- |
| **摄像头设备名称** | `string` | `""`   | 要打开的摄像头设备名称。空字符串会选择第一个可用设备。                       |
| **请求宽度**    | `int`    | `640`  | 发送给驱动程序的请求捕获宽度。实际分辨率可能不同。                         |
| **请求高度**    | `int`    | `480`  | 发送给驱动程序的请求捕获高度。                                   |
| **请求 FPS**  | `int`    | `15`   | 发送给驱动程序的请求帧率。                                     |
| **最大输出宽度**  | `int`    | `1280` | 输出的最大宽度 `RenderTexture`。宽于此值的帧会被缩小。设置为 `0` 可禁用缩放。 |
| **最大输出高度**  | `int`    | `720`  | 输出的最大高度 `RenderTexture`.                          |

**源标识**

| 字段       | 类型       | 默认         | 说明                |
| -------- | -------- | ---------- | ----------------- |
| **源 ID** | `string` | `"webcam"` | 用于领域事件和多源场景中的标识符。 |

**列出可用设备**

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

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

**在运行时切换设备**

要在不中止会话的情况下切换到另一台摄像头：

```csharp
WebcamVisionFrameSource webcam = GetComponent<WebcamVisionFrameSource>();
await webcam.SwitchWebcamAsync("Front Camera");
```

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

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

`Idle → AwaitingPermission → Starting → Ready`

如果用户拒绝权限， `State` 变为 `Failed` 和 `ErrorKind` 设置为 `PermissionDenied`。可通过 `IVisionFrameSourceStatusProvider.StatusChanged` ——见 [Vision 脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md) 来监控此状态，采用状态监视器模式。

在 Android 和 iOS 上，系统摄像头权限对话框会在第一次 `StartCapture()` 运行时出现。请确保你的应用 `AndroidManifest.xml` 声明 `android.permission.CAMERA` 以及你的 iOS `Info.plist` 包含 `NSCameraUsageDescription` 后再提交到应用商店。

### QuestVisionFrameSource

`QuestVisionFrameSource` 会从 Meta Quest 3 或 3S 头显流式传输真实世界的透视画面，为 Convai 角色提供物理环境的实时视图。该组件通过反射绑定到 Meta 的 `PassthroughCameraAccess` API，因此 SDK 不会在编译时硬依赖 Meta XR 包。Inspector 会显示一个专门的实时状态面板——分辨率、目标 FPS、帧计数， `State`，以及 `ErrorKind` ——与 `CameraVisionFrameSource` 和 `WebcamVisionFrameSource`.

**组件菜单路径：** `Convai/Vision/Quest Vision Frame Source`

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FoA5FatTGc5p3SmJc88oW%2Fimage.png?alt=media&amp;token=215d91ba-3e5a-424b-8a16-efc0a9b74c0a" alt="QuestVisionFrameSource Inspector"><figcaption><p>QuestVisionFrameSource Inspector 中显示的面板一致。</p></figcaption></figure>

`QuestVisionFrameSource` 需要 **Meta Quest 3 或 3S** 运行带有 Passthrough Camera API 的 Horizon OS。Quest 2 和 Quest Pro 不支持 `PassthroughCameraAccess`。在编辑器中或其他平台上， `PassthroughCameraAccess` 无法找到或读取，因此组件会进入 `Failed` 状态，并带有 `ErrorKind = InvalidConfiguration` 且不产生任何帧。

{% hint style="danger" %}
**需要 AndroidManifest.xml 权限。** 你的 manifest 必须同时声明 `horizonos.permission.HEADSET_CAMERA` 和 `android.permission.CAMERA`。如果没有这些声明，透视捕获会在设备上静默失败，帧源会进入 `Failed` 状态。设备不会显示权限对话框——它会直接拒绝访问。
{% endhint %}

**Quest 摄像头访问**

| 字段          | 类型              | 默认       | 说明                                              |
| ----------- | --------------- | -------- | ----------------------------------------------- |
| **透视摄像头访问** | `MonoBehaviour` | *（自动发现）* | 对场景中某个 `PassthroughCameraAccess` 组件的引用。留空可自动查找。 |

**输出设置**

| 字段         | 类型       | 默认                    | 说明                                             |
| ---------- | -------- | --------------------- | ---------------------------------------------- |
| **源 ID**   | `string` | `"quest-passthrough"` | 用于领域事件中的标识符。                                   |
| **最大输出宽度** | `int`    | `1280`                | 输出的最大宽度 `RenderTexture`.                       |
| **最大输出高度** | `int`    | `720`                 | 输出的最大高度 `RenderTexture`.                       |
| **目标帧率**   | `int`    | `15`                  | 捕获的目标每秒帧数。                                     |
| **翻转 Y**   | `bool`   | `true`                | 垂直翻转透视纹理。正确的视频方向需要此项——仅当 Meta SDK 更改其坐标约定时才禁用。 |

与 `PassthroughCameraAccess` 的绑定是在运行时通过反射建立的。如果 Meta XR 包更新且 `PassthroughCameraAccess` 更改了其 API，组件会记录错误并进入 `Failed` 状态。在这种情况下请检查 SDK 更新。

### 源状态参考

这三种帧源都实现了 `IVisionFrameSourceStatusProvider`，它提供一个 `State` 属性和一个 `StatusChanged` 事件。使用它们可从脚本监控捕获健康状况。

**VisionSourceState**

| State                | 含义                                               |
| -------------------- | ------------------------------------------------ |
| `空闲`                 | 尚未开始捕获。                                          |
| `AwaitingPermission` | 等待用户授予摄像头权限（Android / iOS）。                      |
| `Starting`           | 捕获正在初始化——设备正在打开， `RenderTexture`正在创建 s。          |
| `Ready`              | 捕获正在运行并正在生成帧。                                    |
| `Degraded`           | 捕获正在运行，但帧健康检查检测到问题（例如，连续的空白帧）。                   |
| `已停止`                | 捕获已正常停止。                                         |
| `Failed`             | 捕获失败且无法继续。检查 `ErrorKind` 和 `StatusMessage` 了解详情。 |

**VisionSourceErrorKind**

| 错误类型                   | 原因                                  |
| ---------------------- | ----------------------------------- |
| `无`                    | 无错误。                                |
| `超时`                   | 帧源未能在预期时间窗口内生成可用帧。                  |
| `PermissionDenied`     | 摄像头权限被用户或操作系统拒绝。                    |
| `UnsupportedPlatform`  | 该平台不支持此帧源（例如， `SrpNative` 选择了捕获模式）。 |
| `DeviceUnavailable`    | 请求的摄像头设备无法打开。                       |
| `InvalidConfiguration` | 某个字段值超出范围或不一致（检查 `StatusMessage`).  |
| `未知`                   | 发生了意外错误。                            |

如需针对这些状态进行脚本编写并响应 `StatusChanged` 事件，请参阅 [Vision 脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md).

### 平台兼容性矩阵

| 功能                        | PC / Mac | Android / iOS | WebGL    | Meta Quest 3 / 3S |
| ------------------------- | -------- | ------------- | -------- | ----------------- |
| `CameraVisionFrameSource` | ✅        | ✅             | ❌（不需要帧源） | ✅                 |
| `WebcamVisionFrameSource` | ✅        | ✅（权限流程）       | ❌        | ❌                 |
| `QuestVisionFrameSource`  | ❌        | ❌             | ❌        | ✅（需要 Meta XR SDK） |
| WebGL 画布捕获                | ❌        | ❌             | ✅（自动）    | ❌                 |
| `VisionDebugPreview`      | ✅（仅编辑器）  | ✅（仅编辑器）       | ⚠️ 空白    | ✅（仅编辑器）           |
| 最大发布 FPS                  | 30       | 30            | 15       | 30                |

在 WebGL 上不需要也不会使用任何帧源组件。 `ConvaiVisionPublisher` 会通过以下方式自动捕获可见的浏览器画布： `canvas.captureStream()`。请参阅 [发布策略](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/publishing-and-policies.md) 有关 WebGL 特定行为和 HTTPS 要求，请参阅。

### 下一步

{% content-ref url="/pages/b15c237537e3521d8e360ca90de5e9b15be340ec" %}
[发布策略](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/publishing-and-policies.md)
{% endcontent-ref %}

{% content-ref url="/pages/cb7758289bc48a93210bce51933fd819fd05e245" %}
[自定义帧来源](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/custom-frame-sources.md)
{% endcontent-ref %}

{% content-ref url="/pages/9ee175b12da238182d707abd778abdc3a8706c80" %}
[Vision 脚本 API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md)
{% endcontent-ref %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/frame-sources.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.