XR_ANDROID_spatial_discovery_bounds

Name String

XR_ANDROID_spatial_discovery_bounds

Extension Type

Instance extension

Registered Extension Number

762

Revision

1

Ratification Status

Not ratified

Extension and Version Dependencies

XR_EXT_spatial_entity

Contributors

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

Overview

This extension adds definitions for spatial bounds that allows applications to filter discovered spatial entities when calling xrCreateSpatialDiscoverySnapshotAsyncEXT .

Spatial Bounds

The XrSpatialBoundsSpherefANDROID structure is defined as:

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • space is the XrSpace that any poses for the bounds are defined in.
  • time is an XrTime at which the poses for the bounds are defined.
  • sphere is an XrSpheref which describes the spherical volume within which the runtime must constrain its discovery of spatial entities.

Spatial capabilities that support XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID (as enumerated by xrEnumerateSpatialCapabilityFeaturesEXT ) allow the application to restrict the discovery to spatial entities whose location or bounds are within or intersecting with sphere by chaining XrSpatialBoundsSpherefANDROID to XrSpatialDiscoverySnapshotCreateInfoEXT :: next . For a discovery snapshot in which the applicable capability supports XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID , if this structure is present in the next chain, the runtime must not include any spatial entities whose location or bounds are entirely outside of sphere .

It is important to note that the inclusion of XrSpatialBoundsSpherefANDROID in the next chain of XrSpatialDiscoverySnapshotCreateInfoEXT acts as an 'AND' condition with the other filters provided. Entities coming from spatial capabilities that do not support XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID must not be included in the discovery snapshot. This behavior is different from the rest of the OpenXR specification where unrecognized or unsupported structures in the next pointer chain are ignored by the runtime. Also, as described in the Next Chain Structure Uniqueness section, the runtime will only process the first occurrence of the XrSpatialBoundsSpherefANDROID structure in the next chain.

Valid Usage (Implicit)

The XrSpatialBoundsBoxfANDROID structure is defined as:

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • space is the XrSpace that any poses for the bounds are defined in.
  • time is an XrTime at which the poses for the bounds are defined.
  • box is an XrBoxf which describes the box volume within which the runtime must constrain its discovery of spatial entities.

Spatial capabilities that support XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID (as enumerated by xrEnumerateSpatialCapabilityFeaturesEXT ) allow the application to restrict the discovery to spatial entities whose location or bounds are within or intersecting with box by chaining XrSpatialBoundsBoxfANDROID to XrSpatialDiscoverySnapshotCreateInfoEXT :: next . For a discovery snapshot in which the applicable capability supports XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID , if this structure is present in the next chain, the runtime must not include any spatial entities whose location or bounds are entirely outside of box .

It is important to note that the inclusion of XrSpatialBoundsBoxfANDROID in the next chain of XrSpatialDiscoverySnapshotCreateInfoEXT acts as an 'AND' condition with the other filters provided. Entities coming from spatial capabilities that do not support XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID must not be included in the discovery snapshot. This behavior is different from the rest of the OpenXR specification where unrecognized or unsupported structures in the next pointer chain are ignored by the runtime. Also, as described in the Next Chain Structure Uniqueness section, the runtime will only process the first occurrence of the XrSpatialBoundsBoxfANDROID structure in the next chain.

Valid Usage (Implicit)

The XrSpatialBoundsFrustumfANDROID structure is defined as:

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

Member Descriptions

  • type is the XrStructureType of this structure.
  • next is NULL or a pointer to the next structure in a structure chain.
  • space is the XrSpace that any poses for the bounds are defined in.
  • time is an XrTime at which the poses for the bounds are defined.
  • frustum is an XrFrustumf which describes the frustum volume within which the runtime must constrain its discovery of spatial entities.

Spatial capabilities that support XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID (as enumerated by xrEnumerateSpatialCapabilityFeaturesEXT ) allow the application to restrict the discovery to spatial entities whose location or bounds are within or intersecting with frustum by chaining XrSpatialBoundsFrustumfANDROID to XrSpatialDiscoverySnapshotCreateInfoEXT :: next . For a discovery snapshot in which the applicable capability supports XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID , if this structure is present in the next chain, the runtime must not include any spatial entities whose location or bounds are entirely outside of frustum .

It is important to note that the inclusion of XrSpatialBoundsFrustumfANDROID in the next chain of XrSpatialDiscoverySnapshotCreateInfoEXT acts as an 'AND' condition with the other filters provided. Entities coming from spatial capabilities that do not support XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID must not be included in the discovery snapshot. This behavior is different from the rest of the OpenXR specification where unrecognized or unsupported structures in the next pointer chain are ignored by the runtime. Also, as described in the Next Chain Structure Uniqueness section, the runtime will only process the first occurrence of the XrSpatialBoundsFrustumfANDROID structure in the next chain.

Valid Usage (Implicit)

Example

The following code demonstrates how to use spatial bounds to filter the discovery of spatial entities.

// 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));

New Structures

New Enum Constants

  • XR_ANDROID_SPATIAL_DISCOVERY_BOUNDS_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_bounds_SPEC_VERSION

  • Extending 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

  • Extending XrStructureType :

    • XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
    • XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
    • XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID

Issues

  • Why is the support for spatial bounds dependent on an XrSpatialCapabilityFeatureEXT definition?

    • Resolved
    • Answer: Not every spatial capability is capable of supporting spatial bounds. An example of this is a hypothetical global container entity that does not have any spatial position or bounds of its own but merely helps collect and organize the other entities inside it. The XrSpatialCapabilityFeatureEXT values enumerated by the capability helps inform the app about the support for spatial bounds filtering.

Version History

  • Revision 1, 2025-05-03 (Nihav Jain, Google)

    • Initial extension description