XR_ANDROID_spatial_discovery_bounds

名称字符串

XR_ANDROID_spatial_discovery_bounds

扩展程序类型

实例扩展程序

已注册的扩展程序编号

762

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

XR_EXT_spatial_entity

创作贡献者

Nihav Jain，Google
Natalie Fleury，Meta
Yuichi Taguchi，Meta
Yin Li，Microsoft
Ron Bessems，Meta
Karthik Kadappan，Magic Leap
Jimmy Alamparambil，ByteDance
Zhipeng Liu，ByteDance
Jun Yan，ByteDance

概览

此扩展程序添加了空间边界定义，使应用能够在调用 xrCreateSpatialDiscoverySnapshotAsyncEXT 时过滤发现的空间实体。

空间边界

XrSpatialBoundsSpherefANDROID 结构的定义如下：

typedef struct XrSpatialBoundsSpherefANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrSpheref          sphere;
} XrSpatialBoundsSpherefANDROID;

成员说明

• type 是此结构的 XrStructureType。
• next 是 NULL 或指向结构链中下一个结构的指针。
• space 是 XrSpace，其中定义了边界的任何姿势。
• time 是定义边界姿势的 XrTime。
• sphere 是一个 XrSpheref，用于描述运行时必须在其中限制空间实体发现的球形体积。

支持 XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID 的空间功能（如 xrEnumerateSpatialCapabilityFeaturesEXT 所列举）允许应用通过将 XrSpatialBoundsSpherefANDROID 链接到 XrSpatialDiscoverySnapshotCreateInfoEXT :: next，将发现范围限制在位置或边界位于 sphere 内或与相交的空间实体。对于适用功能支持 XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID 的发现快照，如果此结构存在于 next 链中，则运行时不得包含位置或边界完全位于 sphere 之外的任何空间实体。

请务必注意，在 XrSpatialDiscoverySnapshotCreateInfoEXT 的下一个链中包含 XrSpatialBoundsSpherefANDROID 会与其他提供的过滤条件形成“AND”条件。来自不支持 XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID 的空间功能的实体不得包含在发现快照中。此行为与 OpenXR 规范的其他部分不同，在其他部分中，运行时会忽略下一个指针链中无法识别或不受支持的结构。此外，如下一个链结构唯一性部分所述，运行时只会处理下一个链中首次出现的 XrSpatialBoundsSpherefANDROID 结构。

有效用法（隐式）

• 必须先启用 XR_ANDROID_spatial_discovery_bounds 扩展程序，然后才能使用 XrSpatialBoundsSpherefANDROID
• type 必须为 XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID
• next 必须为 NULL 或指向结构链中下一个结构的有效指针
• space 必须是有效的 XrSpace 句柄

XrSpatialBoundsBoxfANDROID 结构的定义如下：

typedef struct XrSpatialBoundsBoxfANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrBoxf             box;
} XrSpatialBoundsBoxfANDROID;

成员说明

• type 是此结构的 XrStructureType。
• next 是 NULL 或指向结构链中下一个结构的指针。
• space 是 XrSpace，其中定义了边界的任何姿势。
• time 是定义边界姿势的 XrTime。
• box 是一个 XrBoxf，用于描述运行时必须在其中发现空间实体的盒体。

支持 XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID 的空间功能（如 xrEnumerateSpatialCapabilityFeaturesEXT 所列举）允许应用通过将 XrSpatialBoundsBoxfANDROID 链接到 XrSpatialDiscoverySnapshotCreateInfoEXT :: next，将发现范围限制在位置或边界位于 box 内或与 相交的空间实体。对于适用功能支持 XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID 的发现快照，如果此结构存在于 next 链中，则运行时不得包含位置或边界完全位于 box 之外的任何空间实体。

请务必注意，在 XrSpatialDiscoverySnapshotCreateInfoEXT 的下一个链中包含 XrSpatialBoundsBoxfANDROID 会作为“AND”条件与其他提供的过滤条件一起使用。来自不支持 XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID 的空间功能的实体不得包含在发现快照中。此行为与 OpenXR 规范的其他部分不同，在其他部分中，运行时会忽略下一个指针链中无法识别或不受支持的结构。此外，如下一个链结构唯一性部分所述，运行时将仅处理下一个链中首次出现的 XrSpatialBoundsBoxfANDROID 结构。

有效用法（隐式）

• 必须先启用 XR_ANDROID_spatial_discovery_bounds 扩展程序，然后才能使用 XrSpatialBoundsBoxfANDROID
• type 必须为 XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
• next 必须为 NULL 或指向结构链中下一个结构的有效指针
• space 必须是有效的 XrSpace 句柄

XrSpatialBoundsFrustumfANDROID 结构的定义如下：

typedef struct XrSpatialBoundsFrustumfANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrFrustumf         frustum;
} XrSpatialBoundsFrustumfANDROID;

成员说明

• type 是此结构的 XrStructureType。
• next 是 NULL 或指向结构链中下一个结构的指针。
• space 是 XrSpace，其中定义了边界的任何姿势。
• time 是定义边界姿势的 XrTime。
• frustum 是一个 XrFrustumf，用于描述运行时必须在其中限制空间实体发现的视锥体体积。

支持 XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID 的空间功能（如 xrEnumerateSpatialCapabilityFeaturesEXT 所列举）允许应用通过将 XrSpatialBoundsFrustumfANDROID 链接到 XrSpatialDiscoverySnapshotCreateInfoEXT :: next，将发现范围限制在位置或边界位于 frustum 内或与相交的空间实体。对于适用功能支持 XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID 的发现快照，如果此结构存在于 next 链中，则运行时不得包含位置或边界完全位于 frustum 之外的任何空间实体。

请务必注意，在 XrSpatialDiscoverySnapshotCreateInfoEXT 的下一个链中包含 XrSpatialBoundsFrustumfANDROID 会与提供的其他过滤条件形成“AND”条件。来自不支持 XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID 的空间功能的实体不得包含在发现快照中。此行为与 OpenXR 规范的其他部分不同，在其他部分中，运行时会忽略下一个指针链中无法识别或不受支持的结构。此外，如下一个链结构唯一性部分所述，运行时只会处理下一个链中首次出现的 XrSpatialBoundsFrustumfANDROID 结构。

有效用法（隐式）

• 必须先启用 XR_ANDROID_spatial_discovery_bounds 扩展程序，然后才能使用 XrSpatialBoundsFrustumfANDROID
• type 必须为 XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
• next 必须为 NULL 或指向结构链中下一个结构的有效指针
• space 必须是有效的 XrSpace 句柄

示例

以下代码演示了如何使用空间边界来过滤空间实体的发现。

// previously initialized & configured with the XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT capability.
XrSpatialContextEXT spatialContext;

// Enumerate supported features for XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT capability
uint32_t featureCount = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> fooFeatures(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, featureCount, &featureCount, fooFeatures.data()));

// Check if spatial sphere bounds filter is supported
const auto supportsFeature = [&fooFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(fooFeatures.begin(), fooFeatures.end(), feature) != fooFeatures.end();
};

const bool supportsSphereBoundsFilter = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID);

// We want to look for entities in a sphere around the head with a radius of 2m.
XrSpatialBoundsSpherefANDROID sphereBounds {
  .type = XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID,
  .space = viewSpace,
  .time = predictedDisplayTime,
  .sphere = {
    .center = {
      .orientation = {
        .w = 1.0f,
      },
    },
    .radius = 2.0f,
  },
};

// We want to look for entities that have the following components.
std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = supportsSphereBoundsFilter ? &sphereBounds : nullptr,
  .componentTypeCount = snapshotComponents.size(),
  .componentTypes = snapshotComponents.data(),
};

XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

新结构

• 扩展 XrSpatialDiscoverySnapshotCreateInfoEXT：

  • XrSpatialBoundsBoxfANDROID
  • XrSpatialBoundsFrustumfANDROID
  • XrSpatialBoundsSpherefANDROID

新枚举常量

• XR_ANDROID_SPATIAL_DISCOVERY_BOUNDS_EXTENSION_NAME
• XR_ANDROID_spatial_discovery_bounds_SPEC_VERSION

• 扩展 XrSpatialCapabilityFeatureEXT：

  • XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID
  • XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID
  • XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

• 扩展 XrStructureType：

  • XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
  • XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
  • XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID

问题

• 为什么对空间边界的支持取决于 XrSpatialCapabilityFeatureEXT 定义？

  • 已解决
  • 答：并非所有空间功能都支持空间边界。例如，假设有一个全局容器实体，它本身没有任何空间位置或边界，只是帮助收集和整理其中的其他实体。该功能枚举的 XrSpatialCapabilityFeatureEXT 值有助于让应用了解对空间边界过滤的支持情况。

版本历史记录

• 修订版本 1，2025 年 5 月 3 日（Nihav Jain，Google）

  • 初始扩展程序说明