XR_ANDROID_spatial_discovery_bounds

Name String

XR_ANDROID_spatial_discovery_bounds

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

762

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_EXT_spatial_entity

Mitwirkende

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

Übersicht

Diese Erweiterung fügt Definitionen für räumliche Grenzen hinzu, mit denen Anwendungen gefundene räumliche Entitäten filtern können, wenn xrCreateSpatialDiscoverySnapshotAsyncEXT aufgerufen wird.

Räumliche Grenzen

Die Struktur XrSpatialBoundsSpherefANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • space ist der XrSpace, in dem alle Positionen für die Grenzen definiert sind.
  • time ist ein XrTime, bei dem die Posen für die Grenzen definiert sind.
  • sphere ist ein XrSpheref, das das kugelförmige Volumen beschreibt, innerhalb dessen die Laufzeit die Erkennung räumlicher Entitäten einschränken muss.

Räumliche Funktionen, die XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID unterstützen (wie von xrEnumerateSpatialCapabilityFeaturesEXT aufgezählt), ermöglichen es der Anwendung, die Erkennung auf räumliche Entitäten zu beschränken, deren Position oder Grenzen innerhalb von liegen oder sich mit sphere überschneiden. Dazu wird XrSpatialBoundsSpherefANDROID mit XrSpatialDiscoverySnapshotCreateInfoEXT :: next verkettet. Wenn diese Struktur in der next-Kette vorhanden ist, darf die Laufzeit für einen Discovery-Snapshot, in dem die entsprechende Funktion XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID unterstützt, keine räumlichen Entitäten enthalten, deren Standort oder Grenzen vollständig außerhalb von sphere liegen.

Wichtig: Die Einbeziehung von XrSpatialBoundsSpherefANDROID in die nächste Kette von XrSpatialDiscoverySnapshotCreateInfoEXT fungiert als „UND“-Bedingung mit den anderen bereitgestellten Filtern. Entitäten, die aus räumlichen Funktionen stammen, die XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID nicht unterstützen, dürfen nicht im Discovery-Snapshot enthalten sein. Dieses Verhalten unterscheidet sich vom Rest der OpenXR-Spezifikation, bei der nicht erkannte oder nicht unterstützte Strukturen in der nächsten Zeigerkette von der Laufzeit ignoriert werden. Wie im Abschnitt Eindeutigkeit der nächsten Kettenstruktur beschrieben, verarbeitet die Laufzeit außerdem nur das erste Vorkommen der XrSpatialBoundsSpherefANDROID-Struktur in der nächsten Kette.

Gültige Verwendung (implizit)

Die Struktur XrSpatialBoundsBoxfANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • space ist der XrSpace, in dem alle Positionen für die Grenzen definiert sind.
  • time ist ein XrTime, bei dem die Posen für die Grenzen definiert sind.
  • box ist ein XrBoxf, das das Boxvolumen beschreibt, innerhalb dessen die Laufzeit die Erkennung räumlicher Entitäten einschränken muss.

Räumliche Funktionen, die XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID unterstützen (wie von xrEnumerateSpatialCapabilityFeaturesEXT aufgezählt), ermöglichen es der Anwendung, die Erkennung auf räumliche Entitäten zu beschränken, deren Position oder Grenzen innerhalb von liegen oder sich mit box überschneiden. Dazu wird XrSpatialBoundsBoxfANDROID mit XrSpatialDiscoverySnapshotCreateInfoEXT :: next verkettet. Wenn diese Struktur in der next-Kette vorhanden ist, darf die Laufzeit für einen Discovery-Snapshot, in dem die entsprechende Funktion XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID unterstützt, keine räumlichen Entitäten enthalten, deren Standort oder Grenzen vollständig außerhalb von box liegen.

Wichtig: Die Einbeziehung von XrSpatialBoundsBoxfANDROID in die nächste Kette von XrSpatialDiscoverySnapshotCreateInfoEXT fungiert als „UND“-Bedingung mit den anderen angegebenen Filtern. Entitäten, die aus räumlichen Funktionen stammen, die XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID nicht unterstützen, dürfen nicht im Discovery-Snapshot enthalten sein. Dieses Verhalten unterscheidet sich vom Rest der OpenXR-Spezifikation, bei der nicht erkannte oder nicht unterstützte Strukturen in der nächsten Zeigerkette von der Laufzeit ignoriert werden. Wie im Abschnitt Eindeutigkeit der nächsten Kettenstruktur beschrieben, verarbeitet die Laufzeit außerdem nur das erste Vorkommen der XrSpatialBoundsBoxfANDROID-Struktur in der nächsten Kette.

Gültige Verwendung (implizit)

Die Struktur XrSpatialBoundsFrustumfANDROID ist so definiert:

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

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • space ist der XrSpace, in dem alle Positionen für die Grenzen definiert sind.
  • time ist ein XrTime, bei dem die Posen für die Grenzen definiert sind.
  • frustum ist ein XrFrustumf, das das Frustum-Volumen beschreibt, innerhalb dessen die Laufzeit die Erkennung räumlicher Entitäten einschränken muss.

Räumliche Funktionen, die XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID unterstützen (wie von xrEnumerateSpatialCapabilityFeaturesEXT aufgezählt), ermöglichen es der Anwendung, die Erkennung auf räumliche Entitäten zu beschränken, deren Position oder Grenzen innerhalb von liegen oder sich mit frustum überschneiden. Dazu wird XrSpatialBoundsFrustumfANDROID mit XrSpatialDiscoverySnapshotCreateInfoEXT :: next verkettet. Wenn diese Struktur in der next-Kette vorhanden ist, darf die Laufzeit für einen Discovery-Snapshot, in dem die entsprechende Funktion XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID unterstützt, keine räumlichen Entitäten enthalten, deren Standort oder Grenzen vollständig außerhalb von frustum liegen.

Wichtig: Die Einbeziehung von XrSpatialBoundsFrustumfANDROID in die nächste Kette von XrSpatialDiscoverySnapshotCreateInfoEXT fungiert als „UND“-Bedingung mit den anderen bereitgestellten Filtern. Entitäten, die aus räumlichen Funktionen stammen, die XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID nicht unterstützen, dürfen nicht im Discovery-Snapshot enthalten sein. Dieses Verhalten unterscheidet sich vom Rest der OpenXR-Spezifikation, bei der nicht erkannte oder nicht unterstützte Strukturen in der nächsten Zeigerkette von der Laufzeit ignoriert werden. Wie im Abschnitt Eindeutigkeit der nächsten Kettenstruktur beschrieben, verarbeitet die Laufzeit außerdem nur das erste Vorkommen der XrSpatialBoundsFrustumfANDROID-Struktur in der nächsten Kette.

Gültige Verwendung (implizit)

Beispiel

Der folgende Code zeigt, wie Sie räumliche Grenzen verwenden, um die Erkennung räumlicher Entitäten zu filtern.

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

Neue Gebäude

Neue Enum-Konstanten

  • XR_ANDROID_SPATIAL_DISCOVERY_BOUNDS_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_bounds_SPEC_VERSION

  • Erweiterung von 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

  • Erweiterung von XrStructureType :

    • XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
    • XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
    • XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID

Probleme

  • Warum hängt die Unterstützung für räumliche Grenzen von einer XrSpatialCapabilityFeatureEXT-Definition ab?

    • Behoben
    • Antwort: Nicht jede räumliche Funktion unterstützt räumliche Grenzen. Ein Beispiel hierfür ist eine hypothetische globale Containerentität, die keine eigene räumliche Position oder Grenzen hat, sondern nur dazu dient, die anderen Entitäten darin zu erfassen und zu organisieren. Die von der Funktion aufgezählten XrSpatialCapabilityFeatureEXT-Werte informieren die App über die Unterstützung für die Filterung nach räumlichen Grenzen.

Versionsverlauf

  • Version 1, 03.05.2025 (Nihav Jain, Google)

    • Anfängliche Beschreibung der Erweiterung