> 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).

# 视觉帧源

帧源从您的场景中捕获图像，并将其作为上下翻转的 `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） |

通过以下方式添加帧源： **Add Component** 并输入类名，或者在以下位置下导航到组件菜单： **Convai → Vision**.

### CameraVisionFrameSource

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

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

<figure><img src="/files/0d69003a2d4fd627328c4c6f50eeb6ce5ab5d715" alt="CameraVisionFrameSource Inspector"><figcaption><p>CameraVisionFrameSource 检视器。</p></figcaption></figure>

**捕获设置**

| 字段          | 类型                  | 默认值  | 描述                                     |
| ----------- | ------------------- | ---- | -------------------------------------- |
| **捕获预设**    | `CapturePreset`     | `平衡` | 选择一个预先配置的分辨率和帧率组合。设置为 `Custom` 以手动输入值。 |
| **捕获宽度**    | `int`               | —    | 输出宽度（像素）。仅在预设为 `Custom`.               |
| **捕获高度**    | `int`               | —    | 输出高度（像素）。仅在预设为 `Custom`.               |
| **目标 FPS**  | `int`               | —    | 目标捕获帧率。仅在预设为 `Custom`.                 |
| **摄像机捕获模式** | `CameraCaptureMode` | `自动` | 选择渲染管线捕获策略。保留为 `自动` ，除非画面是黑屏。          |

**摄像机**

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

如果 **目标摄像机** 为空且场景中没有任何摄像机被标记为 **MainCamera**，则帧源进入 `Failed` 状态，在运行时显示 `ErrorKind = InvalidConfiguration`。请始终显式分配摄像机，或确保有一个摄像机具有 **MainCamera** 标记。

**调试**

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

**捕获预设值**

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

<figure><img src="/files/7ff48ce3abd4de5530b577a686a843dc62e14f2c" alt="Capture preset options in the Inspector dropdown"><figcaption><p>检视器下拉菜单中的捕获预设选项。</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="/files/2f9c8cdd7c974d174472895e86110e9d8a553520" alt="WebcamVisionFrameSource Inspector"><figcaption><p>WebcamVisionFrameSource 检视器。</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 包产生硬依赖。在 SDK 4.5.0 中，检视器新增了专门的实时状态面板——分辨率、目标 FPS、帧计数， `State`，以及 `ErrorKind` ——与以下内容中已显示的面板一致： `CameraVisionFrameSource` 和 `WebcamVisionFrameSource`。早期版本为此组件使用 Unity 默认检视器；没有序列化字段发生变化。

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

<figure><img src="/files/255eae068b8e671de517cb73f0ec9e47b6fcd549" alt="QuestVisionFrameSource Inspector"><figcaption><p>QuestVisionFrameSource 检视器。</p></figcaption></figure>

`QuestVisionFrameSource` 需要 **Meta Quest 3 或 3S** 运行 Horizon OS 并启用 Passthrough Camera API。Quest 2 和 Quest Pro 不支持 `PassthroughCameraAccess`。在编辑器或其他平台上，该组件会进入 `Failed` 状态，并显示 `ErrorKind = UnsupportedPlatform` 且不产生任何帧。

{% 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`                  | 用于捕获的目标每秒帧数。                                   |
| **翻转 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`           | 捕获正在运行，但帧健康检查检测到问题（例如连续空白帧）。                   |
| `Stopped`            | 捕获已正常停止。                                       |
| `Failed`             | 捕获失败且无法继续。检查 `ErrorKind` 和 `StatusMessage` 详见。 |

**VisionSourceErrorKind**

| 错误类型                   | 原因                                                                      |
| ---------------------- | ----------------------------------------------------------------------- |
| `无`                    | 无错误。                                                                    |
| `超时`                   | 源未能在预期时间窗口内生成可用帧。                                                       |
| `PermissionDenied`     | 摄像头权限被用户或操作系统拒绝。                                                        |
| `UnsupportedPlatform`  | 该源在此平台上不受支持（例如， `QuestVisionFrameSource` 在 PC 上，或 `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" %}
[视觉脚本 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 dynamically by asking a question.

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

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.