视觉帧源

CameraVisionFrameSource、WebcamVisionFrameSource 和 QuestVisionFrameSource 的参考，包括 Inspector 字段、捕捉预设和平台支持。

帧源从你的场景中捕获图像，并将其作为上下翻转的 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 检视器。

捕获设置

字段	类型	默认值	说明
捕获预设	CapturePreset	平衡	选择一个预配置的分辨率和帧率组合。设置为 自定义 即可手动输入值。
捕获宽度	int	—	输出宽度（像素）。仅在预设为 自定义.
捕获高度	int	—	输出高度（像素）。仅在预设为 自定义.
目标 FPS	int	—	目标捕获帧率。仅在预设为 自定义.
Camera Capture Mode	CameraCaptureMode	Auto	选择渲染管线的捕获策略。除非画面是黑屏，否则保持为 Auto 。

Camera

字段	类型	默认值	说明
目标摄像机	Camera	（自动解析）	要捕获的摄像机。如果留空，则在运行时解析为 Camera.main 。

调试

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

如果 目标摄像机 为空且场景中没有任何摄像机标记为 MainCamera时，帧源在 失败 运行时进入 状态，错误类型为 InvalidConfiguration。请始终显式分配摄像机，或者确保有一个摄像机具有 MainCamera 标记。

捕获预设值

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

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

摄像机捕获模式值

模式	适用场景
Auto	默认。在内置渲染管线中，使用渲染钩子（Camera.onPreRender / Camera.onPostRender）。在 SRP/URP 中，使用显式渲染路径（TargetCamera.Render() 在 LateUpdate）。先选择此项，只有在画面为黑屏时才覆盖。
BuiltInHooks	强制使用内置渲染管线的捕获钩子。仅与内置 RP 兼容——在 SRP/URP 上选择此项会得到黑屏画面。
ExplicitRenderCompatibility	强制执行每帧显式摄像机渲染。当 Auto 在 SRP/URP 上产生黑屏，或使用高度自定义的渲染设置时使用。会在配置的捕获 FPS 下额外添加一次有界的摄像机渲染。
SrpNative	在此 SDK 构建中不可用。 请参见下方说明。

SrpNative 在当前 SDK 构建中不起作用。 选择它会导致 CameraVisionFrameSource 立即进入 失败 状态，错误类型为 ErrorKind = UnsupportedPlatform。如果 Auto 在你的 SRP/URP 项目中产生黑屏时，请使用 ExplicitRenderCompatibility 代替。

WebcamVisionFrameSource

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

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

WebcamVisionFrameSource Inspector.

摄像头设置

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

源标识

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

列出可用设备

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

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

在运行时切换设备

要在不中止会话的情况下切换到其他摄像头：

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

权限流程（Android / iOS）

在 Android 和 iOS 上，当 StartCapture() 被调用时，组件会异步请求摄像头权限。 State 属性会依次转换为：

Idle → AwaitingPermission → Starting → Ready

如果用户拒绝权限， State 变为 失败 是位于 ErrorKind 被设置为 PermissionDenied。可通过 IVisionFrameSourceStatusProvider.StatusChanged 监控这一点——参见 Vision scripting API 中的状态监视器模式。

在 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 包产生强编译时依赖。

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

QuestVisionFrameSource Inspector.

QuestVisionFrameSource 需要 Meta Quest 3 或 3S 运行 Horizon OS 并启用了 Passthrough Camera API。Quest 2 和 Quest Pro 不支持 PassthroughCameraAccess。在编辑器中或其他平台上，组件会进入 失败 状态，并且不会产生任何帧。 ErrorKind = UnsupportedPlatform AndroidManifest.xml 所需权限。

你的 manifest 必须同时声明 和 horizonos.permission.HEADSET_CAMERA 是位于 android.permission.CAMERA。如果没有这些声明，透视捕获会在设备上静默失败，帧源会进入 失败 状态。设备不会显示权限对话框——它只是拒绝访问。

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）。
启动中	正在初始化捕获——设备正在打开， RenderTextures 正在创建。
就绪	捕获正在运行，且正在生成帧。
降级	捕获正在运行，但帧健康检查检测到问题（例如连续空白帧）。
已停止	捕获已正常停止。
失败	捕获失败且无法继续。检查 ErrorKind 是位于 StatusMessage 了解详情。

VisionSourceErrorKind

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

要针对这些状态编写脚本并响应 StatusChanged 事件，请参见 Vision scripting API.

平台兼容性矩阵

功能	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()记录的警告。请参阅 发布策略 有关 WebGL 特定行为和 HTTPS 要求，请参见。

下一步

发布策略自定义帧源视觉脚本 API