XR_ANDROID_spatial_discovery_bounds

Name String

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 列舉) 可讓應用程式將探索範圍限制在位置或邊界位於內或與 sphere 相交的空間實體，方法是將 XrSpatialBoundsSpherefANDROID 鏈結至 XrSpatialDiscoverySnapshotCreateInfoEXT :: next。對於適用功能支援 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 列舉) 可讓應用程式將探索範圍限制在位置或邊界位於 box 內或與 box 相交的空間實體，方法是將 XrSpatialBoundsBoxfANDROID 鏈結至 XrSpatialDiscoverySnapshotCreateInfoEXT :: next。對於適用功能支援 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 列舉) 可讓應用程式將探索範圍限制在位置或邊界位於 frustum 內或與 frustum 相交的空間實體，方法是將 XrSpatialBoundsFrustumfANDROID 鏈結至 XrSpatialDiscoverySnapshotCreateInfoEXT :: next。對於適用功能支援 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-05-03 (Nihav Jain，Google)

  • 初始擴充功能說明