> 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 透视画面。

帧源会从场景中捕获图像，并将其作为 Y 轴翻转的 `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` 中，并在每一帧将其提供给发布器。当 **摄像机捕获模式** 设置为 `Auto`.

**组件菜单路径：** `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 检视面板。</p></figcaption></figure>

**捕获设置**

| 字段         | 类型                  | 默认值        | 说明                                     |
| ---------- | ------------------- | ---------- | -------------------------------------- |
| **捕获预设**   | `CapturePreset`     | `Balanced` | 选择预先配置的分辨率和帧率组合。设置为 `Custom` 即可手动输入数值。 |
| **捕获宽度**   | `int`               | —          | 输出宽度（像素）。仅当预设为 `Custom`.               |
| **捕获高度**   | `int`               | —          | 输出高度（像素）。仅当预设为 `Custom`.               |
| **目标帧率**   | `int`               | —          | 目标采集帧率。仅当预设为 `Custom`.                 |
| **相机采集模式** | `CameraCaptureMode` | `Auto`     | 选择渲染管线的采集策略。请保持为 `Auto` 除非画面为黑屏。       |

**相机**

| 字段       | 类型       | 默认值      | 说明                                  |
| -------- | -------- | -------- | ----------------------------------- |
| **目标相机** | `Camera` | *（自动解析）* | 要采集的相机。若留空，则在运行时解析为 `Camera.main` 。 |

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

**调试**

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

**采集预设值**

| 预设            | 宽度       | 高度       | FPS      | 适用场景                    |
| ------------- | -------- | -------- | -------- | ----------------------- |
| `LowOverhead` | 640      | 480      | 10       | 高吞吐量部署、移动设备或带宽受限的环境     |
| `Balanced`    | 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>检查器下拉菜单中的采集预设选项。</p></figcaption></figure>

**相机采集模式值**

| 模式                            | 适用场景                                                                                                                                                   |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Auto`                        | 默认值。在内置渲染管线中使用渲染钩子（`Camera.onPreRender` / `Camera.onPostRender`）。在 SRP/URP 中使用显式渲染路径（`TargetCamera.Render()` 位于 `LateUpdate`中）。请先选择此项，仅在画面为黑屏时再改用其他选项。 |
| `BuiltInHooks`                | 强制使用内置渲染管线捕获钩子。仅兼容内置渲染管线 — 在 SRP/URP 中选择此项会导致画面为黑屏。                                                                                                    |
| `ExplicitRenderCompatibility` | 强制每帧显式渲染摄像机。适用于 `Auto` 在 SRP/URP 中导致画面为黑屏，或渲染设置经过高度自定义的情况。此选项会按照配置的捕获帧率，额外执行一次有上限的摄像机渲染。                                                               |
| `SrpNative`                   | **此 SDK 构建版本中不可用。** 请参阅下方说明。                                                                                                                           |

{% hint style="danger" %}
**`SrpNative` 在当前 SDK 构建版本中无法正常工作。** 选择此项会使 `CameraVisionFrameSource` 立即进入 `Failed` 状态，并设置 `ErrorKind = UnsupportedPlatform`。如果 `Auto` 在你的 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 检视面板。</p></figcaption></figure>

**摄像头设置**

| 字段          | 类型       | 默认值    | 说明                                                 |
| ----------- | -------- | ------ | -------------------------------------------------- |
| **摄像头设备名称** | `string` | `""`   | 要打开的摄像头设备名称。空字符串表示选择第一个可用设备。                       |
| **请求宽度**    | `int`    | `640`  | 发送给驱动程序的请求捕获宽度。实际分辨率可能不同。                          |
| **请求高度**    | `int`    | `480`  | 发送给驱动程序的请求捕获高度。                                    |
| **请求帧率**    | `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](https://docs.convai.com/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 检视面板。</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 权限。** 清单中必须声明以下两项权限： `horizonos.permission.HEADSET_CAMERA` 和 `android.permission.CAMERA`。如果未声明这些权限，设备上的透视捕获会静默失败，帧源也会进入 `Failed` 状态。设备不会显示权限对话框，而是直接拒绝访问。
{% endhint %}

**Quest 相机访问**

| 字段         | 类型              | 默认值      | 说明                                            |
| ---------- | --------------- | -------- | --------------------------------------------- |
| **透视相机访问** | `MonoBehaviour` | *（自动发现）* | 场景中对 `PassthroughCameraAccess` 组件的引用。留空则自动查找。 |

**输出设置**

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

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

### 帧源状态参考

这三个帧源都实现了 `IVisionFrameSourceStatusProvider`，该接口会公开一个 `State` 属性和 `StatusChanged` 事件。使用这些内容从脚本监控捕获状态。

**VisionSourceState**

| 状态                   | 含义                                                |
| -------------------- | ------------------------------------------------- |
| `Idle`               | 尚未启动捕获。                                           |
| `AwaitingPermission` | 正在等待用户授予相机权限（Android / iOS）。                      |
| `Starting`           | 正在初始化捕获 — 正在打开设备， `RenderTexture`正在创建。            |
| `Ready`              | 捕获正在运行，正在生成帧。                                     |
| `Degraded`           | 捕获正在运行，但帧健康检查检测到了问题（例如，连续出现空白帧）。                  |
| `Stopped`            | 捕获已正常停止。                                          |
| `Failed`             | 捕获失败，无法继续。请查看 `ErrorKind` 和 `StatusMessage` 了解详情。 |

**VisionSourceErrorKind**

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

有关如何针对这些状态编写脚本并响应 `StatusChanged` 事件，请参阅 [Vision 脚本 API](https://docs.convai.com/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()`捕获浏览器中可见的画布。请参阅 [发布策略](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/publishing-and-policies.md) 了解 WebGL 特有的行为和 HTTPS 要求。

### 后续步骤

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

{% content-ref url="/pages/cb7758289bc48a93210bce51933fd819fd05e245" %}
[自定义帧来源](https://docs.convai.com/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](https://docs.convai.com/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.
