1. 简介
本规范引入了新的 WebXR Device API 能力,即 Raw Camera Access API。新引入的 API 使基于 WebXR 的应用能够访问摄像头图像像素,从而允许它们利用这些新信息 计算自定义的逐帧视觉效果,或拍摄叠加了摄像头图像的应用渲染内容快照。
注:本文档中指定的 API 形态 主要解决以智能手机为中心的场景。有关上下文,请参见 issue #2。
1.1. 术语
本文档使用缩写 AR 表示增强现实,使用 VR 表示虚拟现实。
2. 初始化
2.1. 特性描述符
应用可以通过传递适当的特性描述符,请求在 XRSession
上启用原始摄像头访问。本模块引入新字符串——camera-access,作为原始
摄像头访问特性的新的有效特性描述符。
如果设备暴露原生摄像头 能力,则该设备能够支持原始摄像头访问特性。内联 XR 设备不得被视为能够 支持原始摄像头访问特性。
原始摄像头访问特性受权限
策略约束,并要求请求文档的源允许 "xr-spatial-tracking" 策略。
此外,请求文档的源还必须允许 "camera" 权限
策略。
const session= await navigator. xr. requestSession( "immersive-ar" , { requiredFeatures: [ "camera-access" ], });
3. 访问摄像头纹理
3.1. XRView
partial interface XRView { [SameObject ]readonly attribute XRCamera ?; };camera
XRView
被扩展为包含一个 camera
属性,该属性引用一个 XRCamera 实例,
其中包含与此视图相关的摄像头图像信息。当第一次在给定 XRView
实例上访问 camera
属性时,用户代理必须运行取得摄像头算法。对同一 XRView
实例的后续访问必须返回相同的 XRCamera 实例
(如果曾返回过一个),否则返回 null。
为了为 XRView
view 取得
摄像头,用户代理必须运行以下步骤:
-
令 session 为 view 的会话。
-
如果 camera-access 特性描述符未被包含 在 session 的已授予特性集中,则返回
null并中止这些步骤。 -
令 frame 为 view 的帧。
-
如果 frame 的 active 布尔值为
false,则抛出InvalidStateError并中止这些步骤。 -
如果 frame 的 animationFrame 布尔值为
false,则抛出InvalidStateError并中止这些步骤。 -
令 camera image 包含一个大小为 width 乘 height 纹素的摄像头图像缓冲区,该缓冲区由原生摄像头返回,并且对 frame 的时间有效。
-
如果 camera image 为
null,则返回null并中止这些步骤。 -
确保 camera image 包含与 view 对齐的数据,包括适当调整 width 和 height。如果无法做到这一点,则返回
null并中止这些步骤。 -
以 view、camera image、width 和 height 调用创建摄像头实例算法,并返回其 结果。
3.2. XRCamera
[SecureContext ,Exposed =Window ]interface {XRCamera readonly attribute unsigned long ;width readonly attribute unsigned long ; };height
XRCamera
接口被引入,用作暴露可从
XRWebGLBinding
取得的摄像头纹理相关信息的一种方式。
XRCamera
包含 width
属性,该属性包含摄像头图像的宽度(以纹素为单位)。
XRCamera
包含 height
属性,该属性包含摄像头图像的高度(以纹素为单位)。
每个 XRCamera
都有一个关联的 视图实例,其中包含返回该 XRCamera 实例所来自的
XRView。
每个 XRCamera
都有一个关联的 摄像头图像数据缓冲区。
XRView
view、camera image、width 和 height
创建摄像头实例,用户代理必须运行
以下步骤:
3.3. XRWebGLBinding
partial interface XRWebGLBinding {WebGLTexture ?(getCameraImage XRCamera ); };camera
getCameraImage(camera)
方法在被调用时,可用于从 XRWebGLBinding
取得摄像头图像。
返回的 WebGLTexture
如果非 null,则为不透明
纹理。
XRWebGLBinding
binding 为 XRCamera
camera 取得
摄像头图像,用户代理必须运行以下步骤:
-
令 session 为 binding 的会话。
-
令 view 为 camera 的视图。
-
如果 view 的会话与 session 不匹配,则抛出
InvalidStateError并中止这些步骤。 -
令 frame 为 view 的帧。
-
如果 frame 的 active 布尔值为
false,则抛出InvalidStateError并中止这些步骤。 -
如果 frame 的 animationFrame 布尔值为
false,则抛出InvalidStateError并中止这些步骤。 -
令 context 为 binding 的上下文。
-
令 camera image 为 camera 的摄像头图像。
-
令 result 为一个在 context 上创建的
WebGLTexture, 其中包含 camera image 的数据。 result 是一个不透明纹理。 -
返回 result。
用户代理可以缓存对 getCameraImage(camera)
调用的结果,以供该方法的后续调用返回,前提是缓存以绑定和摄像头实例为键。
即使使用缓存,用户代理也必须通过运行到取得摄像头图像算法的第 6 步(含)来执行初始验证。
由于允许这种缓存,应用应将返回的 WebGLTexture
视为只读。
注:允许缓存是因为用户代理
保留对返回的 WebGLTexture
生命周期的所有权(因为它被视为不透明
纹理),并且因为在同一 requestAnimationFrame() 回调内多次调用此方法(通过使用 XRCamera,以及
因此传递性地使用 XRFrame
作为缓存键的一部分来保证),并在同一绑定上调用(通过使用 XRWebGLBinding
作为缓存键的一部分来保证),将得到内容相同的纹理。
如果从调用 getCameraImage(camera)
返回的 WebGLTexture
支持透明度,则它必须包含预乘 alpha 的颜色。
我们是否应该指定更多
有关返回的 WebGLTexture
的信息?
例如:它是否可作为颜色渲染目标、纹理格式是什么等。
4. 原生设备概念
4.1. 原生摄像头
Raw Camera API 规范假定实现该 API 所基于的原生设备 提供一种以动画帧同步的方式访问摄像头图像的方法。这样的设备被称为 支持原生 摄像头能力。
除了设备能够提供摄像头图像外,Raw Camera Access API 只能
提供与请求它们的 XRView
对齐的摄像头图像纹理。如果摄像头姿态与 XRView
的姿态相同,并且摄像头的视锥体与 XRView
的视锥体形状相同,则称该摄像头图像与该 XRView
对齐。如果由原生摄像头返回的摄像头图像覆盖的视锥体完全包含
XRView
的视锥体,则只要该操作会使视锥体形状完全匹配,用户代理就可以裁剪摄像头图像。
5. 隐私与安全考量
Raw Camera Access API 在目前所有可用的 WebXR 能力中具有最高的隐私影响,因为它是唯一允许应用直接观察用户 环境的 API。鉴于此,用户代理应在允许创建启用了 camera-access 特性的会话 之前征求用户同意。有关更多详细信息,请参阅 WebXR Device API § security 与 WebXR Device API § user-intention 章节,以及下方的 § 5.1 用户 体验与 § 5.2 隐私指示器章节。
要求所提供的摄像头图像与 XRView
对齐,为减轻该 API 对用户隐私的影响提供了部分缓解。
此要求的一个结果是,根据 XR 合成器的混合技术,摄像头图像将包含用户可能已经看到的相同信息,
从而直接反馈环境中哪些部分对网站可见。请注意,在某些情况下,网站可能会
抑制此信息(例如在智能手机上渲染一个覆盖整个视图的不透明对象,
从而遮挡由合成器渲染的环境)。
除了要求用户代理征求用户同意之外,还强烈鼓励应用开发者 如果存在其他方式实现其用例,则不要请求 camera-access 特性。
5.1. 用户体验
如上所述,由于 Raw Camera Access API 的隐私影响,用户代理应在创建启用了 camera-access 特性的会话之前征求用户 同意。这可以通过多种方式实现,其中一些方式需要直接与用户交互。
直接与用户交互的一些示例包括:
-
显示权限提示,允许用户选择向站点暴露信息的精细程度。 此类提示的模型如下所示。
-
显示一系列权限提示,这些提示会考虑创建包含应用传递给
requestSession()调用的所请求和可选特性的会话所需的各种用户同意级别。
本规范的意图是确保用户代理不会鼓励应用开发者 在他们想要提供的体验并非绝对需要时请求 camera-access 特性。由于该特性的隐私影响,当站点请求访问摄像头图像时,用户代理可以 引入额外阻力,希望这能激励应用不要无谓地请求该特性。
5.2. 隐私指示器
每当创建了一个带有 camera-access
的 XRSession
且该会话尚未 ended
时,
用户代理必须显示隐私指示器。如果将来可以在会话创建后修改会话的已
授予特性集,则只要 camera-access 特性描述符被包含在该会话的已授予特性集中,就应显示该指示器。
显示给用户的指示器应传达设备摄像头正在使用且站点可访问该摄像头这一事实, 因而用户应格外注意,确保落入摄像头视野内的内容是他们愿意与该站点分享的。 这在公共场所尤其如此,因为可能存在未同意被记录的旁观者。
示例指示器包括(但不限于):
-
在移动设备上,在状态栏中显示摄像头正在使用的通知;
-
渲染一个 UI 元素(例如内容周围的边框、象征“录制” 按钮的圆形图标等),暗示内容正在被录制;
-
使用录制设备的 LED 指示灯(如果存在且可由用户代理控制);
-
在会话开始时发出相机快门音效;
6. 致谢
以下个人为 WebXR Raw Camera Access 规范的设计做出了贡献: