> 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） | 通过以下方式添加帧源： **添加组件** 并输入类名，或者在下方的组件菜单中导航到 **Convai → Vision**. ### CameraVisionFrameSource `CameraVisionFrameSource` 捕获 Unity `Camera`的输出，并将其作为 `RenderTexture` 提供给发布器。它会在每一帧自动为当前渲染管线（内置或 SRP/URP）选择正确的捕获后端，当 **Camera Capture Mode** 被设置为 `Auto`. **组件菜单路径：** `Convai/Vision/Camera Vision Frame Source`
CameraVisionFrameSource Inspector

CameraVisionFrameSource 检视器。

**捕获设置** | 字段 | 类型 | 默认值 | 说明 | | ----------------------- | ------------------- | ------ | ----------------------------------- | | **捕获预设** | `CapturePreset` | `平衡` | 选择一个预配置的分辨率和帧率组合。设置为 `自定义` 即可手动输入值。 | | **捕获宽度** | `int` | — | 输出宽度（像素）。仅在预设为 `自定义`. | | **捕获高度** | `int` | — | 输出高度（像素）。仅在预设为 `自定义`. | | **目标 FPS** | `int` | — | 目标捕获帧率。仅在预设为 `自定义`. | | **Camera Capture Mode** | `CameraCaptureMode` | `Auto` | 选择渲染管线的捕获策略。除非画面是黑屏，否则保持为 `Auto` 。 | **Camera** | 字段 | 类型 | 默认值 | 说明 | | --------- | -------- | -------- | ------------------------------------- | | **目标摄像机** | `Camera` | *（自动解析）* | 要捕获的摄像机。如果留空，则在运行时解析为 `Camera.main` 。 | **调试** | 字段 | 类型 | 默认值 | 说明 | | ------------- | -------- | ---------- | ------------------------------------------------------- | | **源 ID** | `string` | `"camera"` | 用于域事件和多源场景中的标识符。 | | **启用诊断帧健康探针** | `bool` | `false` | 执行同步的逐帧像素回读以验证帧内容。仅在诊断黑屏问题时使用；每帧都会产生一次 GPU 回读开销。发布前请禁用。 | {% hint style="warning" %} 如果 **目标摄像机** 为空且场景中没有任何摄像机标记为 **MainCamera**时，帧源在 `失败` 运行时进入 `状态，错误类型为 InvalidConfiguration`。请始终显式分配摄像机，或者确保有一个摄像机具有 **MainCamera** 标记。 {% endhint %} **捕获预设值** | 预设 | 宽度 | 高度 | FPS | 使用场景 | | ----- | -------- | -------- | -------- | ----------------------- | | `低开销` | 640 | 480 | 10 | 大规模部署、移动端或带宽受限环境 | | `平衡` | 1280 | 720 | 15 | 通用用途——大多数场景的默认选择 | | `高细节` | 1920 | 1080 | 30 | 对 AI 理解而言，精细视觉细节至关重要的场景 | | `自定义` | *（手动设置）* | *（手动设置）* | *（手动设置）* | 完全控制尺寸和帧率 |
Capture preset options in the Inspector dropdown

检视器下拉菜单中的捕获预设选项。

**摄像机捕获模式值** | 模式 | 适用场景 | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `Auto` | 默认。在内置渲染管线中，使用渲染钩子（`Camera.onPreRender` / `Camera.onPostRender`）。在 SRP/URP 中，使用显式渲染路径（`TargetCamera.Render()` 在 `LateUpdate`）。先选择此项，只有在画面为黑屏时才覆盖。 | | `BuiltInHooks` | 强制使用内置渲染管线的捕获钩子。仅与内置 RP 兼容——在 SRP/URP 上选择此项会得到黑屏画面。 | | `ExplicitRenderCompatibility` | 强制执行每帧显式摄像机渲染。当 `Auto` 在 SRP/URP 上产生黑屏，或使用高度自定义的渲染设置时使用。会在配置的捕获 FPS 下额外添加一次有界的摄像机渲染。 | | `SrpNative` | **在此 SDK 构建中不可用。** 请参见下方说明。 | {% hint style="danger" %} **`SrpNative` 在当前 SDK 构建中不起作用。** 选择它会导致 `CameraVisionFrameSource` 立即进入 `失败` 状态，错误类型为 `ErrorKind = UnsupportedPlatform`。如果 `Auto` 在你的 SRP/URP 项目中产生黑屏时，请使用 `ExplicitRenderCompatibility` 代替。 {% endhint %} ### WebcamVisionFrameSource `WebcamVisionFrameSource` 使用 Unity 的 `WebCamTexture` API 捕获物理摄像头设备，并将输出转换为 `RenderTexture`。它会处理设备选择、权限请求（在 Android 和 iOS 上）、自动旋转校正以及分辨率限制。 **组件菜单路径：** `Convai/Vision/Webcam Vision Frame Source`
WebcamVisionFrameSource Inspector

WebcamVisionFrameSource Inspector.

**摄像头设置** | 字段 | 类型 | 默认值 | 说明 | | ----------- | -------- | ------ | -------------------------------------------------- | | **摄像头设备名称** | `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(); await webcam.SwitchWebcamAsync("Front Camera"); ``` **权限流程（Android / iOS）** 在 Android 和 iOS 上，当 `StartCapture()` 被调用时，组件会异步请求摄像头权限。 `State` 属性会依次转换为： `Idle → AwaitingPermission → Starting → Ready` 如果用户拒绝权限， `State` 变为 `失败` 是位于 `ErrorKind` 被设置为 `PermissionDenied`。可通过 `IVisionFrameSourceStatusProvider.StatusChanged` 监控这一点——参见 [Vision scripting API](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.md) 中的状态监视器模式。 {% hint style="info" %} 在 Android 和 iOS 上，系统摄像头权限对话框会在第一次 `StartCapture()` 运行时出现。确保你的应用的 `AndroidManifest.xml` 声明了 `android.permission.CAMERA` 以及你的 iOS `Info.plist` 包含 `NSCameraUsageDescription` ，然后再提交到应用商店。 {% endhint %} ### QuestVisionFrameSource `QuestVisionFrameSource` 从 Meta Quest 3 或 3S 头显流式传输真实世界透视画面，为 Convai 角色提供对物理环境的实时视图。该组件通过反射绑定到 Meta 的 `PassthroughCameraAccess` API，因此 SDK 不会对 Meta XR 包产生强编译时依赖。 **组件菜单路径：** `Convai/Vision/Quest Vision Frame Source`
QuestVisionFrameSource Inspector

QuestVisionFrameSource Inspector.

{% hint style="warning" %} `QuestVisionFrameSource` 需要 **Meta Quest 3 或 3S** 运行 Horizon OS 并启用了 Passthrough Camera API。Quest 2 和 Quest Pro 不支持 `PassthroughCameraAccess`。在编辑器中或其他平台上，组件会进入 `失败` 状态，并且不会产生任何帧。 `ErrorKind = UnsupportedPlatform` AndroidManifest.xml 所需权限。 {% endhint %} {% hint style="danger" %} **你的 manifest 必须同时声明** 和 `horizonos.permission.HEADSET_CAMERA` 是位于 `android.permission.CAMERA`。如果没有这些声明，透视捕获会在设备上静默失败，帧源会进入 `失败` 状态。设备不会显示权限对话框——它只是拒绝访问。 {% 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，则组件会记录错误并进入 `失败` 状态。届时请检查 SDK 更新。 ### 源状态参考 这三种帧源都实现了 `IVisionFrameSourceStatusProvider`，它公开了一个 `State` 属性和一个 `StatusChanged` 事件。可使用它们从脚本监控捕获健康状况。 **VisionSourceState** | State | 含义 | | ------ | -------------------------------------------------- | | `空闲` | 尚未开始捕获。 | | `等待授权` | 等待用户授予相机权限（Android / iOS）。 | | `启动中` | 正在初始化捕获——设备正在打开， `RenderTexture`s 正在创建。 | | `就绪` | 捕获正在运行，且正在生成帧。 | | `降级` | 捕获正在运行，但帧健康检查检测到问题（例如连续空白帧）。 | | `已停止` | 捕获已正常停止。 | | `失败` | 捕获失败且无法继续。检查 `ErrorKind` 是位于 `StatusMessage` 了解详情。 | **VisionSourceErrorKind** | 错误类型 | 原因 | | ---------------------- | --------------------------------------------------------------------- | | `无` | 无错误。 | | `超时` | 源未在预期时间窗口内产生可用帧。 | | `PermissionDenied` | 摄像头权限被用户或操作系统拒绝。 | | `UnsupportedPlatform` | 该源不受此平台支持（例如， `QuestVisionFrameSource` 在 PC 上，或 `SrpNative` 选择了捕获模式）。 | | `DeviceUnavailable` | 无法打开请求的摄像头设备。 | | `InvalidConfiguration` | 字段值超出范围或不一致（检查 `StatusMessage`). | | `未知` | 发生了意外错误。 | 要针对这些状态编写脚本并响应 `StatusChanged` 事件，请参见 [Vision scripting 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 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/convai-unity-sdk/features/vision/frame-sources.md?ask= ``` 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.