XRReferenceSpace

安全上下文:此功能仅在 安全上下文 (HTTPS) 中可用,在某些或所有 支持的浏览器 中可用。

WebXR 设备 API 的 XRReferenceSpace 接口使用指定的跟踪行为描述虚拟世界中特定跟踪实体或对象的坐标系。跟踪行为由所选 参考空间类型 定义。它扩展了基类 XRSpace,添加了对几种不同跟踪行为的支持,以及请求描述跟踪对象与世界中另一个位置之间的偏移变换的新参考空间。

所有参考空间(唯一例外是边界参考空间)都使用 XRReferenceSpace 类型描述。边界空间以 XRBoundedReferenceSpace 对象的形式实现。这些是特殊空间,可以让您在其中建立一个“安全”的边界,以便查看器可以在其中移动。对于允许用户物理移动的 XR 系统,例如使用真实世界相机跟踪移动的 XR 系统,该边界会建立用户能够四处移动的区域的边缘,无论是由于物理障碍,还是由于 XR 硬件的限制。有关使用边界来防止用户与物理和虚拟障碍物发生碰撞的更多信息,请参阅文章 使用边界参考空间保护查看器

EventTarget XRSpace XRReferenceSpace

实例属性

XRReferenceSpace 继承了 EventTarget 的属性,但没有定义任何额外的属性。

实例方法

除了以下方法外,XRReferenceSpace 还继承了来自 EventTarget 的方法。

getOffsetReferenceSpace()

创建并返回一个新的参考空间对象,其类型与您调用该方法的对象相同(因此,无论是 XRReferenceSpace 还是 XRBoundedReferenceSpace)。新的参考空间可用于将坐标从调用该方法的对象的参考空间转换为不同的坐标空间。这在渲染时定位对象以及在改变查看器在 3D 空间中的位置和/或方向时执行必要的变换很有用。

事件

reset

当浏览器检测到跟踪对象的原点与用户的环境或位置之间存在不连续性时,reset 事件将发送到 XRReferenceSpace 对象。例如,这可能发生在用户重新校准 XR 设备后,或设备在丢失和恢复跟踪后自动调整其原点。

参考空间类型

参考空间的类型列在下面的表格中,其中包含有关其用例及其用于实现它们的接口的简要信息。

bounded-floor

一个 XRBoundedReferenceSpace,类似于 local 类型,只是用户预计不会移动到由返回对象中的 boundsGeometry 给出的预定边界之外。

local

一个 XRReferenceSpace 跟踪空间,其本机原点位于会话创建时查看器位置附近。确切位置取决于底层平台和实现。用户预计不会从其起始位置移动太多,甚至根本不会移动,并且跟踪针对此用例进行了优化。对于具有六个自由度 (6DoF) 跟踪的设备,local 参考空间尝试相对于环境保持原点稳定。

local-floor

一个 XRReferenceSpace,类似于 local 类型,只是起始位置放置在查看器安全站立的位置,其中 y 轴的值在楼层水平时为 0。如果该楼层水平未知,则 用户代理 将估计楼层水平。如果估计的楼层水平非零,则浏览器预计会以避免 指纹识别 的方式对其进行舍入(可能舍入到最近的厘米)。

unbounded

一个 XRReferenceSpace 跟踪空间,它允许用户完全自由移动,可能从其原点移动极长距离。查看器根本没有被跟踪;跟踪针对用户当前位置周围的稳定性进行了优化,因此本机原点可能会根据需要漂移以适应这一需求。

viewer

一个 XRReferenceSpace 跟踪空间,其本机原点跟踪查看器的位置和方向。这用于用户可以物理移动的环境中,并且受所有 XRSession 实例支持,包括沉浸式和内联,尽管它对内联会话最有用。当确定查看器和输入之间的距离,或使用偏移空间时,它特别有用。否则,通常,会更频繁地使用其他参考空间类型之一。

使用注意事项

创建 XRReferenceSpace

有两种情况需要获取 XRReferenceSpace。第一种是当您设置场景时,需要获取一个参考空间来代表用户在整个 XRSession 期间对世界的视角。为此,请调用 XRSession 方法 requestReferenceSpace(),并指定您希望获取的参考空间类型。

js
xrSession.requestReferenceSpace("local").then((refSpace) => {
  xrReferenceSpace = refSpace;
  // …
});

您可能需要获取新参考空间的另一种情况是,如果您需要将原点移动到新的位置;例如,当您的项目允许用户使用键盘、鼠标、触控板或未通过 XR 设备连接的游戏控制器等输入设备在环境中移动时,通常会这样做。由于原点通常是用户在空间中的位置,因此您需要更改原点以反映他们的移动和他们所做的任何方向变化。

要移动或旋转用户对世界的视角,您需要更改用于表示该视角的 XRReferenceSpace。但是,XRReferenceSpace 是不可变的,因此您需要创建一个新的参考空间来表示更改后的视角。这可以使用 getOffsetReferenceSpace() 方法轻松完成。

js
let offsetTransform = new XRRigidTransform(
  { x: 2, y: 0, z: 1 },
  { x: 0, y: 0, z: 0, w: 1 },
);
xrReferenceSpace = xrReferenceSpace.getOffsetReferenceSpace(offsetTransform);

这将用一个新的 XRReferenceSpace 替换当前的 XRReferenceSpace,新的 XRReferenceSpace 的原点和方向会进行调整,使得新原点相对于当前原点位于 (2, 0, 1),并且通过一个单位 四元数 进行旋转,该四元数将空间的方向调整为使观察者相对于之前的世界方向朝上。

几何

任何 XRReferenceSpace 的原生原点总是被配置为使 +X 方向被视为向右,+Y 方向被视为向上,+Z 方向被视为“向后”或朝向用户。

规范

规范
WebXR 设备 API
# xrreferencespace-interface

浏览器兼容性

BCD 表格仅在浏览器中加载

参见