WebXR 命中测试模块

1. 引言

本模块描述一种机制，允许 WebXR 应用将射线投射到用户的现实世界环境中，并根据 XR 设备所能掌握的最佳知识，报告该射线与物理对象相交的点，以及被相交表面的朝向。这允许将虚拟对象与这些表面对齐放置，例如将对象真实地放在地板上或附着到墙上。命中测试 API 是 WebXR Device API 的扩展，并构建在 WebXR 增强现实模块之上。

1.1. 术语

本文档所理解的命中测试，是指检查一条理想化的数学射线（半直线）是否与底层增强现实硬件和软件所理解的现实世界相交的行为。针对使用该 API 的应用所创建的虚拟对象进行的射线相交，明确不属于命中测试 API 的范围。

2. 初始化

2.1. 特性描述符

为了让应用表明其有意在会话期间执行命中测试，必须使用适当的特性描述符来请求会话。本模块引入字符串 hit-test，作为命中测试特性的新有效特性描述符。

如果设备暴露了原生命中测试能力，则该设备能够支持命中测试特性。内联 XR 设备不得被视为能够支持命中测试特性。

命中测试特性受特性策略约束，并要求在请求文档的源上允许 "xr-spatial-tracking" 策略。

3. 命中测试选项

3.1. XRHitTestTrackableType

XRHitTestTrackableType 枚举指定可用于创建命中测试源的实体类型。

enum XRHitTestTrackableType {
  "point",
  "plane",
  "mesh"
};

类型为 "point" 的命中测试可跟踪对象表示命中测试结果将基于底层增强现实系统检测到的特征点来计算。
类型为 "plane" 的命中测试可跟踪对象表示命中测试结果将基于底层增强现实系统检测到的平面来计算。
类型为 "mesh" 的命中测试可跟踪对象表示命中测试结果将基于底层增强现实系统检测到的网格来计算。

3.2. XRHitTestOptionsInit

XRHitTestOptionsInit 字典表示一组可配置值，这些值会影响正在执行的命中测试的行为。

dictionary XRHitTestOptionsInit {
  required XRSpace space;
  sequence<XRHitTestTrackableType> entityTypes;
  XRRay offsetRay;
};

space 字典成员指定 XRSpace， offsetRay 是相对于该空间来指定的。

entityTypes 字典成员指定将用于计算命中测试结果的 XRHitTestTrackableTypes 数组。

offsetRay 字典成员指定将用于执行命中测试的 XRRay。offsetRay 将被解释为以 space 所定义的坐标系表示。

XRHitTestOptionsInit 字典具有关联的有效 entityTypes，如果在字典构造时提供了 entityTypes，则它被设置为该值。如果在构造时未提供 entityTypes，则有效 entityTypes 被设置为包含单个元素 "plane" 的数组。

XRHitTestOptionsInit 字典具有关联的有效 offsetRay，如果在字典构造时提供了 offsetRay，则它被设置为该值。如果在构造时未提供 offsetRay，则有效 offsetRay 被设置为一个通过不带任何参数调用 XRRay() 而构造的 XRRay。

3.3. XRTransientInputHitTestOptionsInit

XRTransientInputHitTestOptionsInit 字典表示一组可配置值，这些值会影响正在为瞬态输入执行的命中测试的行为。

dictionary XRTransientInputHitTestOptionsInit {
  required DOMString profile;
  sequence<XRHitTestTrackableType> entityTypes;
  XRRay offsetRay;
};

profile 字典成员指定将用于计算命中测试结果的瞬态输入源的输入配置文件名称。

entityTypes 字典成员指定将用于计算命中测试结果的 XRHitTestTrackableTypes 数组。

offsetRay 字典成员指定将用于执行命中测试的 XRRay。offsetRay 在为瞬态输入源计算命中测试结果时，将被解释为以其 profile 匹配传入的 profile 的 XRInputSource 所定义的坐标系表示。

XRTransientInputHitTestOptionsInit 字典具有关联的有效 entityTypes，如果在字典构造时提供了 entityTypes，则它被设置为该值。如果在构造时未提供 entityTypes，则有效 entityTypes 被设置为包含单个元素 "plane" 的数组。

XRTransientInputHitTestOptionsInit 字典具有关联的有效 offsetRay，如果在字典构造时提供了 offsetRay，则它被设置为该值。如果在构造时未提供 offsetRay，则有效 offsetRay 被设置为一个通过不带任何参数调用 XRRay() 而构造的 XRRay。

4. 命中测试源

4.1. XRHitTestSource

[SecureContext, Exposed=Window]
interface XRHitTestSource {
  undefined cancel();
};

XRHitTestSource 对象充当对命中测试的活动订阅的句柄。

每个 XRHitTestSource 都具有关联的session，它存储用于创建该命中测试源的 XRSession。

每个 XRHitTestSource 都具有关联的native origin，它存储足以标识用于请求命中测试的 XRSpace 的native origin 的信息。随后在计算命中测试结果时将使用这些信息。

每个 XRHitTestSource 都具有关联的entity types，它是一个 XRHitTestTrackableTypes 数组，描述在计算命中测试结果时将考虑哪些实体类型。

每个 XRHitTestSource 都具有关联的offset ray，它是一个在计算命中测试结果时将使用的 XRRay。

只要 XRHitTestSource 存在于 session 的活动命中测试源集合中，它就被视为活动。

为了从 session、 space、entityTypes 和 offsetRay 创建命中测试源，用户代理必须运行以下步骤：

令 hitTestSource 为一个新的 XRHitTestSource。
将 hitTestSource 的 session 初始化为 session。
将 hitTestSource 的native origin 初始化为 space 的native origin。
将 hitTestSource 的 entity types 初始化为 entityTypes。
根据 offsetRay 和 space 计算 transformedOffsetRay，使得 transformedOffsetRay 在被解释为 space 的native origin 坐标系中的射线时，表示的射线与 offsetRay 在被解释为 space 的effective origin 坐标系中的射线相同。
将 hitTestSource 的offset ray 初始化为 transformedOffsetRay。
返回 hitTestSource。

当在 XRHitTestSource hitTestSource 上调用 cancel() 方法时，它表示应用不再有兴趣为指定的 hitTestSource 获取命中测试结果。

调用 cancel() 方法时，用户代理必须通过运行以下步骤来取消命中测试源：

如果 hitTestSource 不是活动的，则抛出 InvalidStateError 并中止这些步骤。
从 session 的活动命中测试源集合中移除 hitTestSource。

当应用不再保留对特定 XRHitTestSource hitTestSource 的任何引用时，如果 hitTestSource 仍然活动，用户代理可以取消命中测试源。该取消可以在未指定的时间发生（也可以完全不发生），应用不应依赖此行为来进行清理。

4.2. XRTransientInputHitTestSource

[SecureContext, Exposed=Window]
interface XRTransientInputHitTestSource {
  undefined cancel();
};

XRTransientInputHitTestSource 对象充当针对瞬态输入源的命中测试活动订阅的句柄。

每个 XRTransientInputHitTestSource 都具有关联的 session，它存储用于创建该命中测试源的 XRSession。

每个 XRTransientInputHitTestSource 都具有关联的 profile，它存储输入源的输入配置文件名称。随后在计算瞬态输入源的命中测试结果时将使用这些信息。

每个 XRTransientInputHitTestSource 都具有关联的 entity types，它是一个 XRHitTestTrackableTypes 数组，描述在计算命中测试结果时将考虑哪些实体类型。

每个 XRTransientInputHitTestSource 都具有关联的 offset ray，它是一个在计算命中测试结果时将使用的 XRRay。

只要 XRTransientInputHitTestSource 存在于 session 的瞬态输入的活动命中测试源集合中，它就被视为活动。

为了从 session、profile、entityTypes 和 offsetRay 为瞬态输入创建命中测试源，用户代理必须运行以下步骤：

令 hitTestSource 为一个新的 XRTransientInputHitTestSource。
将 hitTestSource 的 session 初始化为 session。
将 hitTestSource 的 profile 初始化为 profile。
将 hitTestSource 的 entity types 初始化为 entityTypes。
将 hitTestSource 的 offset ray 初始化为 offsetRay。
返回 hitTestSource。

当在 XRTransientInputHitTestSource hitTestSource 上调用 cancel() 方法时，它表示应用不再有兴趣为指定的 hitTestSource 获取命中测试结果。

调用 cancel() 方法时，用户代理必须通过运行以下步骤来取消瞬态输入的命中测试源：

如果 hitTestSource 不是活动的，则抛出 InvalidStateError 并中止这些步骤。
从 session 的瞬态输入的活动命中测试源集合中移除 hitTestSource。

当应用不再保留对特定 XRTransientInputHitTestSource hitTestSource 的任何引用时，如果 hitTestSource 仍然活动，用户代理可以取消瞬态输入的命中测试源。该取消可以在未指定的时间发生（也可以完全不发生），应用不应依赖此行为来进行清理。

5. 命中测试结果

5.1. XRHitTestResult

[SecureContext, Exposed=Window]
interface XRHitTestResult {
  XRPose? getPose(XRSpace baseSpace);
};

XRHitTestResult 包含命中测试的单个结果。它封装了用于执行命中测试的射线与底层 XR 设备所理解的用户环境的相交点相关的信息。

每个 XRHitTestResult 都具有关联的 frame，它是为其计算该结果的 XRFrame。

每个 XRHitTestResult 都具有关联的 native origin。此 native origin 定义一个新的坐标系，其 Y 轴表示相交点处表面的法向量。

为了在给定 XRFrame frame、XRHitTestTrackableType 数组 entityTypes，以及原生命中测试结果 nativeResult 的情况下创建命中测试结果，用户代理必须运行以下步骤：

令 hitTestResult 为一个新的 XRHitTestResult。
令 session 为 frame 的 session。
令 device 为 session 的 XR 设备。
向 device 查询 nativeResult 的原生实体类型 nativeEntityType。
将 nativeEntityType 从原生实体类型转换为 entityType。
如果 entityType 为 null，或者不存在于 entityTypes 数组中，则返回 null 并中止这些步骤。
将 hitTestResult 的 frame 设置为 frame。
将 hitTestResult 的 native origin 设置为从 nativeResult 获得的 native origin。
返回 hitTestResult。

当在 XRHitTestResult hitTestResult 上以 baseSpace 参数调用 getPose(baseSpace) 方法时，它以 XRPose 的形式，提供在 frame 所表示的时间，hitTestResult 相对于 baseSpace 的姿态。

当在 hitTestResult 上调用 getPose(baseSpace) 方法时，用户代理必须运行以下步骤：

令 frame 为 hitTestResult 的 frame。
如果 frame 的 active 布尔值为 false，则抛出 InvalidStateError 并中止这些步骤。
令 pose 为一个新的 XRPose。
令 space 为一个新的 XRSpace，其 native origin 设置为native origin，origin offset 设置为恒等变换，并且 session 设置为 frame 的 session。
在 frame 所表示的时间，填充姿态：将 space 在 baseSpace 中的姿态填入 pose。
返回 pose。

5.2. XRTransientInputHitTestResult

[SecureContext, Exposed=Window]
interface XRTransientInputHitTestResult {
  [SameObject] readonly attribute XRInputSource inputSource;
  readonly attribute FrozenArray<XRHitTestResult> results;
};

XRTransientInputHitTestResult 包含按 XRInputSource inputSource 分组的瞬态输入命中测试结果数组。

inputSource 属性包含用于计算 results 数组的 XRInputSource。

results 属性包含计算得到的 XRHitTestResult 数组。

每个 XRTransientInputHitTestResult 都具有关联的 frame，它是为其计算这些结果的 XRFrame。

为了在给定 XRInputSource inputSource、XRFrame frame、XRHitTestTrackableType 数组 entityTypes，以及原生命中测试结果数组 nativeResults 的情况下为瞬态输入创建命中测试结果，用户代理必须运行以下步骤：

令 hitTestResult 为一个新的 XRTransientInputHitTestResult。
将 hitTestResult 的 frame 设置为 frame。
将 hitTestResult 的 inputSource 设置为 inputSource。
令 results 为一个空的 XRHitTestResult 数组。
对 nativeResults 中的每个 nativeResult：
1. 从 frame、entityTypes 和 nativeResult 创建命中测试结果 result。
2. 如果 result 为 null，则继续处理 nativeResults 中的下一项。
3. 将 result 添加到 results 数组。
将 hitTestResult 的 results 设置为 results。
返回 hitTestResult。

6. 请求命中测试

partial interface XRSession {
  Promise<XRHitTestSource> requestHitTestSource(XRHitTestOptionsInit options);
  Promise<XRTransientInputHitTestSource> requestHitTestSourceForTransientInput(XRTransientInputHitTestOptionsInit options);
};

XRSession 被扩展为包含一个关联的活动命中测试源集合，该集合将在计算命中测试结果时使用。

XRSession 被扩展为包含一个关联的瞬态输入的活动命中测试源集合，该集合将在计算瞬态输入的命中测试结果时使用。

当活动命中测试源的总数或最近发出的请求数被认为对于 API 的合法使用而言过高时，应用被视为发出了不合理数量的请求。这是用户代理可以采取的可选隐私措施，用以避免滥用。

应用可以使用 XRSession 的 requestHitTestSource() 方法来请求命中测试。

当在 XRSession session 上调用 requestHitTestSource(options) 方法时，必须运行以下步骤：

令 promise 为一个新的 Promise。
如果 hit-test 特性描述符未包含在 session 的已启用特性列表中，则以 NotSupportedError 拒绝 promise 并中止这些步骤。
如果 session 的 ended 值为 true，则抛出 InvalidStateError 并中止这些步骤。
如果存在不合理数量的请求，则用户代理可以用 NotAllowedError 拒绝 promise 并中止这些步骤。
如果 session 的帧更新列表中尚未存在计算所有命中测试结果算法，则将其添加到该列表中。
使用 session、options 的 space、 options 的有效 entityTypes 和 options 的有效 offsetRay 创建命中测试源 hitTestSource。
如果 hitTestSource 为 null，则以 OperationError 拒绝 promise 并中止这些步骤。
将创建的 hitTestSource 存储在 session 的活动命中测试源集合中。
用创建的 hitTestSource 兑现 promise。

当在 XRSession session 上调用 requestHitTestSourceForTransientInput(options) 方法时，必须运行以下步骤：

令 promise 为一个新的 Promise。
如果 hit-test 特性描述符未包含在 session 的已启用特性列表中，则以 NotSupportedError 拒绝 promise 并中止这些步骤。
如果 session 的 ended 值为 true，则抛出 InvalidStateError 并中止这些步骤。
如果存在不合理数量的请求，则用户代理可以用 NotAllowedError 拒绝 promise 并中止这些步骤。
如果 session 的帧更新列表中尚未存在计算所有命中测试结果算法，则将其添加到该列表中。
使用 session、options 的 profile、 options 的有效 entityTypes 和 options 的有效 offsetRay 为瞬态输入创建命中测试源 hitTestSource。
如果 hitTestSource 为 null，则以 OperationError 拒绝 promise 并中止这些步骤。
将创建的 hitTestSource 存储在 session 的瞬态输入的活动命中测试源集合中。
用创建的 hitTestSource 兑现 promise。

7. 计算命中测试结果

为了为给定的 XRFrame frame 计算所有命中测试结果，用户代理必须执行以下步骤：

以 frame 调用计算命中测试结果算法。
以 frame 调用计算瞬态输入的命中测试结果算法。

为了为给定的 XRFrame frame 计算命中测试结果，对于存在于 session 的活动命中测试源集合中的每个命中测试源 hitTestSource，用户代理必须执行以下步骤：

令 entityTypes 为 hitTestSource 的 entity types。
令 session 为 frame 的 session。
令 device 为 session 的 XR 设备。
向 device 的跟踪系统查询 hitTestSource 的native origin 的最新 coordinates。
将 hitTestSource 的offset ray offsetRay 解释为相对于 coordinates 表示，并使用该解释执行原生命中测试，获得原生命中测试结果 nativeResults。
令 hitTestResults 为一个空列表。
对于 nativeResults 中的每个原生命中测试结果 nativeResult，执行以下步骤：
1. 从 frame、entityTypes 和 nativeResult 创建命中测试结果 hitTestResult。
2. 如果 hitTestResult 为 null，则继续处理 nativeResults 中的下一项。
3. 将 hitTestResult 添加到 hitTestResults 中，使该列表仍按从 offsetRay 到 nativeResult 的沿射线距离排序。
将 hitTestResults 存储在 frame 的命中测试源到命中测试结果的映射中，以 hitTestSource 为键。

为了为给定的 XRFrame frame 计算瞬态输入的命中测试结果，对于存在于 session 的瞬态输入的活动命中测试源集合中的每个命中测试源 hitTestSource，用户代理必须执行以下步骤：

令 entityTypes 为 hitTestSource 的 entity types。
令 session 为 frame 的 session。
令 device 为 session 的 XR 设备。
令 candidateInputSources 为包含在活动 XR 输入源列表中、且被认为是瞬态的所有 session 输入源的集合。
令 matchingInputSources 为 candidateInputSources 中所有其 profiles 数组包含一个等于 hitTestSource 的profile 的项的输入源集合。
令 hitTestResults 为一个空的 XRTransientInputHitTestResults 数组。
对于 matchingInputSources 中的每个瞬态输入源 inputSource：
1. 向 device 的跟踪系统查询 inputSource 的 targetRaySpace 的 native origin 的最新 coordinates。
2. 将 hitTestSource 的offset ray 解释为相对于 coordinates 表示，并使用该解释执行原生命中测试，获得原生命中测试结果 nativeResults。
3. 从 frame、inputSource、 entityTypes 和 nativeResults 为瞬态输入创建命中测试结果 hitTestResult。
4. 将 hitTestResult 添加到 hitTestResults 数组。
将 hitTestResults 存储在 frame 的瞬态输入的命中测试源到命中测试结果的映射中，以 hitTestSource 为键。

8. 获取命中测试结果

partial interface XRFrame {
  sequence<XRHitTestResult> getHitTestResults(XRHitTestSource hitTestSource);
  sequence<XRTransientInputHitTestResult> getHitTestResultsForTransientInput(XRTransientInputHitTestSource hitTestSource);
};

XRFrame 被扩展为包含一个关联的命中测试源到命中测试结果的映射，它存储从 XRHitTestSource 到 XRHitTestResults 数组的映射。

XRFrame 被扩展为包含一个关联的瞬态输入的命中测试源到命中测试结果的映射，它存储从 XRTransientInputHitTestSource 到 XRTransientInputHitTestResults 数组的映射。

应用可以通过使用 XRFrame 的 getHitTestResults() 方法，从 XRHitTestSource 获取命中测试结果。

当在 XRFrame frame 上调用 getHitTestResults(hitTestSource) 方法时，用户代理必须运行以下步骤：

如果 frame 的 active 布尔值为 false，则抛出 InvalidStateError 并中止这些步骤。
检查 frame 的命中测试源到命中测试结果的映射中是否存在 hitTestSource 的项。如果该项不存在，则抛出 InvalidStateError 并中止这些步骤。
在 frame 的命中测试源到命中测试结果的映射中查找 hitTestSource 的项，并将其赋给 results。
返回 results。

应用可以通过使用 XRFrame 的 getHitTestResultsForTransientInput() 方法，从 XRTransientInputHitTestSource 获取瞬态输入的命中测试结果。

当在 XRFrame frame 上调用 getHitTestResultsForTransientInput(hitTestSource) 方法时，用户代理必须运行以下步骤：

如果 frame 的 active 布尔值为 false，则抛出 InvalidStateError 并中止这些步骤。
检查 frame 的瞬态输入的命中测试源到命中测试结果的映射中是否存在 hitTestSource 的项。如果该项不存在，则抛出 InvalidStateError 并中止这些步骤。
在 frame 的瞬态输入的命中测试源到命中测试结果的映射中查找 hitTestSource 的项，并将其赋给 results。
返回 results。

9. 几何基元

9.1. XRRayDirectionInit

XRRayDirectionInit 字典表示要传递给 XRRay(origin, direction) 构造器的方向向量。

dictionary XRRayDirectionInit {
  double x = 0;
  double y = 0;
  double z = -1;
  double w = 0;
};

9.2. XRRay

XRRay 是一条由 origin 点和 direction 向量描述的几何射线。

XRRay 包含一个 matrix，它是一个矩阵。

[SecureContext, Exposed=Window]
interface XRRay {
  constructor(optional DOMPointInit origin = {}, optional XRRayDirectionInit direction = {});
  constructor(XRRigidTransform transform);
  [SameObject] readonly attribute DOMPointReadOnly origin;
  [SameObject] readonly attribute DOMPointReadOnly direction;
  [SameObject] readonly attribute Float32Array matrix;
};

XRRay(origin, direction) 构造器在被调用时必须执行以下步骤：

令 ray 为一个新的 XRRay。
将 ray 的 origin 初始化为 { x: 0.0, y: 0.0, z: 0.0, w: 1.0 }。
将 ray 的 direction 初始化为 { x: 0.0, y: 0.0, z: -1.0, w: 0.0 }。
如果 direction 的 x、 y 和 z 全部为零，则抛出 TypeError 并中止这些步骤。
如果 direction 的 w 不是 0.0，则抛出 TypeError 并中止这些步骤。
如果 origin 的 w 不是 1.0，则抛出 TypeError 并中止这些步骤。
将 ray 的 origin 的 x 值初始化为 origin 的 x， y 值初始化为 origin 的 y，并将 z 值初始化为 origin 的 z。
将 ray 的 direction 的 x 值初始化为 direction 的 x， y 值初始化为 direction 的 y，并将 z 值初始化为 direction 的 z。
归一化 ray 的 direction 的 x、 y 和 z 分量。
将 ray 的matrix 初始化为 null。
返回 ray。

XRRay(transform) 构造器在被调用时必须执行以下步骤：

令 ray 为一个新的 XRRay。
将 ray 的 origin 初始化为 { x: 0.0, y: 0.0, z: 0.0, w: 1.0 }。
将 ray 的 direction 初始化为 { x: 0.0, y: 0.0, z: -1.0, w: 0.0 }。
通过预乘 transform 的 matrix 来变换 ray 的 origin，并将 ray 设置为结果。
通过预乘 transform 的 matrix 来变换 ray 的 direction，并将 ray 设置为结果。
归一化 ray 的 direction 的 x、 y 和 z 分量。
将 ray 的matrix 初始化为 null。
返回 ray。

origin 属性定义射线起源处的三维空间点，以米为单位给出。origin 的 w 属性必须为 1.0。

direction 属性定义射线的三维方向向量。direction 的 w 属性必须为 0.0，并且该向量必须归一化为长度 1.0。

matrix 属性是一个矩阵，它表示一个可用于沿 XRRay 放置对象的变换。它是从一条起源于 [0, 0, 0] 且沿负 Z 轴延伸的射线，到由 XRRay 的 origin 和 direction 所描述射线的变换。这样的矩阵必须具有一个旋转分量，该旋转分量使任何垂直于 direction 和 Z 轴的向量保持不变。此属性必须通过为 XRRay 获取矩阵来计算。此属性应该惰性求值。

注：XRRay 的 matrix 可用于在渲染时轻松定位射线的图形表示。

要为给定的 XRRay ray 获取矩阵

如果 ray 的 matrix 不是 null，则执行以下步骤：
1. 如果对 matrix 执行的 IsDetachedBuffer 操作为 false，则返回 ray 的 matrix。
令 z 为向量 [0, 0, -1]。
令 axis 为 z 与 ray 的 direction 的向量叉积， z × direction。
令 cos_angle 为 z 与 ray 的 direction 的标量点积， z · direction。
根据以下内容设置 rotation：

如果 cos_angle 大于 -1 且小于 1
将 rotation 设置为表示绕 axis 按 arccos(cos_angle) 进行右手平面旋转的旋转矩阵。
否则，如果 cos_angle 为 -1
将 rotation 设置为表示绕向量 [1, 0, 0] 按 arccos(cos_angle) 进行右手平面旋转的旋转矩阵。
否则
将 rotation 设置为恒等矩阵。
令 translation 为其分量对应于 ray 的 origin 的平移矩阵。
令 matrix 为在列向量表示法中，将 rotation 从左侧预乘到 translation 上的结果（即 translation * rotation）。
将 ray 的 matrix 设置为 matrix。
返回 matrix。

沿射线距离 distance，从 XRRay ray 到任何实体 entity，定义为使 ray.origin + ray.direction * distance 得到属于实体 entity 的点，distance 为非负数，并且不存在更小的 distance 值仍能使上述谓词成立。由 XR 设备来定义“属于某个实体的点”的含义。

10. 原生设备概念

实现命中测试 API 的用户代理必须有一种方式从底层 XR 设备获取有关用户环境的信息。本节试图描述与设备原生能力相关的要求和概念，并且必然保持足够的不完全规定，以便为不同的底层框架/设备留出充分空间。

10.1. 原生命中测试

在本规范中，假定 XR 设备暴露了一种供用户代理执行满足以下要求的原生命中测试的方式：

接受将针对用户环境进行测试的 3D 射线。
返回表示传入射线与用户环境相交点的 3D 姿态集合。集合中的每个条目还应包含用于获得该原生结果的原生实体类型信息，以及足以使用户代理计算用户环境在相交点处表面法线的信息。

注：对于不以原生方式暴露命中测试功能的设备，用户代理仍有可能通过利用 XR 设备可能暴露的其他获取用户环境信息的方式来实现本规范。

10.2. 原生实体类型

原生命中测试结果由 XR 设备返回，并应包含用于计算结果的实体的类型信息。这类原生类型可以包括但不限于：

点 - 表示命中测试结果是基于用户环境中发现的特征点计算的。
平面 - 表示命中测试结果是基于用户环境中检测到的平面计算的。
网格 - 表示命中测试结果是基于用户环境中检测到的网格计算的。

要从原生实体类型转换为 XRHitTestTrackableType，用户代理必须运行以下步骤：

令 nativeEntityType 为要转换的原生实体类型。
令 entityType 为一个新的 XRHitTestTrackableType。
按如下方式初始化 entityType：

如果 nativeEntityType 包含与 "point" 对应的类型
将 entityType 设置为 "point"。
否则，如果 nativeEntityType 包含与 "plane" 对应的类型
将 entityType 设置为 "plane"。
否则，如果 nativeEntityType 包含与 "mesh" 对应的类型
将 entityType 设置为 "mesh"。
否则
将 entityType 设置为 null
返回 entityType。

10.3. 原生命中测试结果

从 XR 设备返回的原生命中测试结果应包含与用户环境的相交点位置。根据原生实体类型以及 XR 设备可用的信息，结果还应包含以某种方式定义的朝向，以允许用户代理计算用户环境在相交点处的表面法线。

关于相交点的位置和朝向信息应包含在原生命中测试结果的 native origin 中。Native origin 以某种方式定义一个新的坐标系，使其 Y 轴表示相交点处表面的法向量。如果 XR 设备未返回朝向，则用户代理应将 native origin 设置为使其定义的坐标系的 Y 轴指向上方（朝向负重力向量）。

确定是否需要指定由命中测试结果的 native origin 所定义坐标系的其他轴，以维持不同实现和不同 AR 框架之间的兼容性。

11. 隐私与安全考量

命中测试 API 可通过向多个方向发送命中测试射线，以或高或低的精度来映射用户环境。在创建 XR 会话时，命中测试必须作为特性描述符声明，这将允许用户代理通知用户，允许网站使用命中测试 API 可能带来的隐私影响。此外，当用户代理认为针对真正的非隐私侵入性使用发出了不合理数量的请求时，可以拒绝命中测试请求。

变更

自 2021年8月31日首份公开工作草案以来的变更

12. 致谢

以下个人为 WebXR 命中测试规范的设计作出了贡献：

WebXR 命中测试模块

摘要

本文档的状态

1. 引言

1.1. 术语

2. 初始化

2.1. 特性描述符

3. 命中测试选项

3.1. XRHitTestTrackableType

3.2. XRHitTestOptionsInit

3.3. XRTransientInputHitTestOptionsInit

4. 命中测试源

4.1. XRHitTestSource

4.2. XRTransientInputHitTestSource

5. 命中测试结果

5.1. XRHitTestResult

5.2. XRTransientInputHitTestResult

6. 请求命中测试

7. 计算命中测试结果

8. 获取命中测试结果

9. 几何基元

9.1. XRRayDirectionInit

9.2. XRRay

10. 原生设备概念

10.1. 原生命中测试

10.2. 原生实体类型

10.3. 原生命中测试结果

11. 隐私与安全考量

变更

自 2021年8月31日首份公开工作 草案以来的变更

12. 致谢

符合性

文档 约定

符合性 算法

索引

本 规范定义的术语

由引用 定义的术语

参考文献

规范性参考文献

IDL 索引

议题索引

自 2021年8月31日首份公开工作草案以来的变更

文档约定

符合性算法

本规范定义的术语

由引用定义的术语