XR_ANDROID_spatial_discovery_bounds

Name String

XR_ANDROID_spatial_discovery_bounds

Type d'extension

Extension d'instance

Numéro d'extension enregistré

762

Révision

1

État de la ratification

Non ratifié

Dépendances d'extension et de version

XR_EXT_spatial_entity

Participants

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

Présentation

Cette extension ajoute des définitions pour les limites spatiales qui permettent aux applications de filtrer les entités spatiales découvertes lors de l'appel de xrCreateSpatialDiscoverySnapshotAsyncEXT .

Limites spatiales

La structure XrSpatialBoundsSpherefANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • space est l'XrSpace dans lequel les poses des limites sont définies.
  • time est un XrTime auquel les poses des limites sont définies.
  • sphere est un XrSpheref qui décrit le volume sphérique dans lequel l'environnement d'exécution doit limiter sa découverte d'entités spatiales.

Les fonctionnalités spatiales compatibles avec XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID (comme énumérées par xrEnumerateSpatialCapabilityFeaturesEXT) permettent à l'application de limiter la découverte aux entités spatiales dont l'emplacement ou les limites se trouvent dans sphere ou l'intersectent en associant XrSpatialBoundsSpherefANDROID à XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Pour un instantané de découverte dans lequel la fonctionnalité applicable est compatible avec XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID , si cette structure est présente dans la chaîne next, l'environnement d'exécution ne doit pas inclure d'entités spatiales dont l'emplacement ou les limites se trouvent entièrement en dehors de sphere .

Il est important de noter que l'inclusion de XrSpatialBoundsSpherefANDROID dans la chaîne suivante de XrSpatialDiscoverySnapshotCreateInfoEXT agit comme une condition "ET" avec les autres filtres fournis. Les entités provenant de fonctionnalités spatiales qui ne sont pas compatibles avec XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID ne doivent pas être incluses dans l'instantané de découverte. Ce comportement est différent du reste de la spécification OpenXR, où les structures non reconnues ou non compatibles de la chaîne de pointeurs suivante sont ignorées par l'environnement d'exécution. De plus, comme décrit dans la section Unicité de la structure de la chaîne suivante, l'environnement d'exécution ne traite que la première occurrence de la structure XrSpatialBoundsSpherefANDROID dans la chaîne suivante.

Utilisation valide (implicite)

La structure XrSpatialBoundsBoxfANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • space est l'XrSpace dans lequel les poses des limites sont définies.
  • time est un XrTime auquel les poses des limites sont définies.
  • box est un XrBoxf qui décrit le volume de la boîte dans lequel l'environnement d'exécution doit limiter sa découverte d'entités spatiales.

Les fonctionnalités spatiales compatibles avec XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID (comme énumérées par xrEnumerateSpatialCapabilityFeaturesEXT) permettent à l'application de limiter la découverte aux entités spatiales dont l'emplacement ou les limites se trouvent dans box ou l'intersectent en associant XrSpatialBoundsBoxfANDROID à XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Pour un instantané de découverte dans lequel la fonctionnalité applicable est compatible avec XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID , si cette structure est présente dans la chaîne next, l'environnement d'exécution ne doit pas inclure d'entités spatiales dont l'emplacement ou les limites se trouvent entièrement en dehors de box .

Il est important de noter que l'inclusion de XrSpatialBoundsBoxfANDROID dans la chaîne suivante de XrSpatialDiscoverySnapshotCreateInfoEXT agit comme une condition "ET" avec les autres filtres fournis. Les entités provenant de fonctionnalités spatiales qui ne sont pas compatibles avec XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID ne doivent pas être incluses dans l'instantané de découverte. Ce comportement est différent du reste de la spécification OpenXR, où les structures non reconnues ou non compatibles de la chaîne de pointeurs suivante sont ignorées par l'environnement d'exécution. De plus, comme décrit dans la section Unicité de la structure de la chaîne suivante, l'environnement d'exécution ne traite que la première occurrence de la structure XrSpatialBoundsBoxfANDROID dans la chaîne suivante.

Utilisation valide (implicite)

La structure XrSpatialBoundsFrustumfANDROID est définie comme suit :

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

Descriptions des membres

  • type est le XrStructureType de cette structure.
  • next est NULL ou un pointeur vers la structure suivante dans une chaîne de structures.
  • space est l'XrSpace dans lequel les poses des limites sont définies.
  • time est un XrTime auquel les poses des limites sont définies.
  • frustum est un XrFrustumf qui décrit le volume du tronc dans lequel l'environnement d'exécution doit limiter sa découverte d'entités spatiales.

Les fonctionnalités spatiales compatibles avec XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID (comme énumérées par xrEnumerateSpatialCapabilityFeaturesEXT) permettent à l'application de limiter la découverte aux entités spatiales dont l'emplacement ou les limites se trouvent dans frustum ou l'intersectent en associant XrSpatialBoundsFrustumfANDROID à XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Pour un instantané de découverte dans lequel la fonctionnalité applicable est compatible avec XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID , si cette structure est présente dans la chaîne next, l'environnement d'exécution ne doit pas inclure d'entités spatiales dont l'emplacement ou les limites se trouvent entièrement en dehors de frustum .

Il est important de noter que l'inclusion de XrSpatialBoundsFrustumfANDROID dans la chaîne suivante de XrSpatialDiscoverySnapshotCreateInfoEXT agit comme une condition "ET" avec les autres filtres fournis. Les entités provenant de fonctionnalités spatiales qui ne sont pas compatibles avec XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID ne doivent pas être incluses dans l'instantané de découverte. Ce comportement est différent du reste de la spécification OpenXR, où les structures non reconnues ou non compatibles de la chaîne de pointeurs suivante sont ignorées par l'environnement d'exécution. De plus, comme décrit dans la section Unicité de la structure de la chaîne suivante, l'environnement d'exécution ne traite que la première occurrence de la structure XrSpatialBoundsFrustumfANDROID dans la chaîne suivante.

Utilisation valide (implicite)

Exemple

Le code suivant montre comment utiliser des limites spatiales pour filtrer la découverte d'entités spatiales.

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

Nouvelles structures

Nouvelles constantes d'énumération

  • XR_ANDROID_SPATIAL_DISCOVERY_BOUNDS_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_bounds_SPEC_VERSION

  • Extension de 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

  • Extension de XrStructureType :

    • XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
    • XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
    • XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID

Problèmes

  • Pourquoi la prise en charge des limites spatiales dépend-elle d'une définition XrSpatialCapabilityFeatureEXT ?

    • Résolu
    • Réponse : Toutes les fonctionnalités spatiales ne sont pas compatibles avec les limites spatiales. Par exemple, une entité de conteneur globale hypothétique qui n'a pas de position ni de limites spatiales propres, mais qui permet simplement de collecter et d'organiser les autres entités qu'elle contient. Les valeurs XrSpatialCapabilityFeatureEXT énumérées par la fonctionnalité permettent d'informer l'application de la compatibilité avec le filtrage des limites spatiales.

Historique des versions

  • Révision 1, 03/05/2025 (Nihav Jain, Google)

    • Description initiale de l'extension