XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

798

Revision

1

Ratifikationsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

XR_ANDROID_geospatial
und
XR_EXT_future
und
XR_EXT_spatial_entity
und
XR_EXT_spatial_anchor

Datum der letzten Änderung

2025-10-30

IP-Status

Es sind keine Ansprüche wegen geistigen Eigentums bekannt.

Mitwirkende

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

Übersicht

Diese Erweiterung bietet Geospatial Anchors und Surface Anchors, die auf der Basis-Erweiterung für Geodaten basieren. Geospatial Anchors sind Anker, die im Raum relativ zur Erde an einem bestimmten Breiten-, Längen- und Höhengrad positioniert sind. Surface Anchors sind erdbezogene Anker, die an einem bestimmten Breitengrad, Längengrad und einer bestimmten Höhe relativ zu einer Oberfläche platziert werden, die vom Visual Positioning Service erkannt wird. Wenn sich die Genauigkeit der Position der Laufzeit relativ zur Erde verbessert, wird die Position des Ankers entsprechend angepasst.

Systemfunktion für raumbezogene Anker

Die Struktur XrSystemGeospatialAnchorPropertiesANDROID ist so definiert:

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette. Solche Strukturen sind in OpenXR Core oder dieser Erweiterung nicht definiert.
  • maxSurfaceAnchorCount ist ein uint32_t, der die maximale Anzahl von Oberflächenankern angibt, die erstellt werden können.

Eine Anwendung kann die Funktionen für geografische Anker des Systems prüfen, indem sie beim Aufrufen von xrGetSystemProperties eine XrSystemGeospatialAnchorPropertiesANDROID-Struktur an die XrSystemProperties anhängt .

Wenn XrSystemGeospatialPropertiesANDROID :: supportsGeospatial gleich XR_TRUE ist, gibt maxSurfaceAnchorCount die maximale Anzahl von Oberflächenankern an, die von der Laufzeit unterstützt werden. Das Limit muss in diesem Fall größer als 0 sein.

Wenn XrSystemGeospatialPropertiesANDROID :: supportsGeospatial nicht XR_TRUE ist , muss maxSurfaceAnchorCount 0 sein.

Gültige Nutzung (implizit)

Ebenenverfolgung für Anker

Die Struktur XrGeospatialTrackerAnchorTrackingInfoANDROID ist so definiert:

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • shouldTrackPlanes ist ein XrBool32, das angibt, ob der Geospatial Tracker Ebenen verfolgt, um die Positionierung von an Oberflächen fixierten Ankern zu verbessern.

Die Ebeneerkennung kann aktiviert werden, um die Positionierung von oberflächengebundenen Ankern zu verbessern.

Wenn die Anwendung die Ebenenverfolgung aktivieren möchte, um die Posen von Oberflächenankern zu verbessern, kann sie beim Aufrufen von xrCreateGeospatialTrackerANDROID eine XrGeospatialTrackerAnchorTrackingInfoANDROID-Struktur an XrGeospatialTrackerCreateInfoANDROID anhängen .

Gültige Nutzung (implizit)

Geospatial Anchors

Die Funktion xrCreateGeospatialAnchorANDROID ist so definiert:

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

Parameterbeschreibungen

  • spatialContext ist der XrSpatialContextEXT, in dem der Anker erstellt werden soll. Der Kontext muss für XR_SPATIAL_CAPABILITY_ANCHOR_EXT konfiguriert sein. Andernfalls muss die Laufzeit XR_ERROR_VALIDATION_FAILURE zurückgeben.
  • createInfo ist ein Zeiger auf XrGeospatialAnchorCreateInfoANDROID, der Parameter zum Erstellen von Ankern enthält.
  • anchorEntityId ist ein Zeiger auf XrSpatialEntityIdEXT, in dem die Ankerentitäts-ID zurückgegeben wird.

Wenn der in XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker angegebene XrGeospatialTrackerANDROID nicht den Status XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID hat, muss die Laufzeit XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID zurückgeben .

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrGeospatialAnchorCreateInfoANDROID ist so definiert:

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • geospatialTracker ist der XrGeospatialTrackerANDROID, der zum Erstellen des Ankers verwendet werden soll.
  • geospatialPose ist ein Zeiger auf XrGeospatialPoseANDROID, der die Position und Ausrichtung des Ankers definiert.

Gültige Nutzung (implizit)

Oberflächenanker

Oberflächenanker werden relativ zu einer Oberfläche platziert, z. B. zu einem Gelände oder Dächern.

Die Enumeration XrSurfaceAnchorTypeANDROID ist so definiert:

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

Die Enumeration XrSurfaceAnchorTypeANDROID gibt den Typ der Oberfläche an, auf die sich ein Anker bezieht.

Die Enumerationen haben die folgenden Werte:

Enum-Beschreibung

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Typ eines Ankers, der relativ zum Boden platziert wird.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Typ eines Ankers, der relativ zum Dach oder zum Boden platziert wird, wenn kein Gebäude vorhanden ist.

Die Funktion xrCreateSurfaceAnchorAsyncANDROID ist so definiert:

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

Parameterbeschreibungen

  • spatialContext ist der XrSpatialContextEXT, in dem der Anker erstellt werden soll.
  • createInfo ist ein Zeiger auf XrSurfaceAnchorCreateInfoANDROID, der Parameter zum Erstellen von Ankern enthält.
  • future ist ein Zeiger auf XrFutureEXT, der das Ergebnis des asynchronen Vorgangs enthält.

Die Funktion xrCreateSurfaceAnchorAsyncANDROID startet einen asynchronen Vorgang zum Erstellen eines Oberflächenankers. Im Gegensatz zu standardmäßigen geografischen Ankern kann die Laufzeit Geländedaten abrufen, um die richtige Höhe zu ermitteln. Die Laufzeit muss XR_ERROR_LIMIT_REACHED zurückgeben, wenn die Anwendung versucht, mehr als XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount Oberflächenanker gleichzeitig zu erstellen. Wenn der in XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker angegebene XrGeospatialTrackerANDROID nicht im Status XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ist, muss die Laufzeit XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID zurückgeben . Der Vorgang kann asynchron mit dem Ergebnis XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID fehlschlagen, wenn für den angegebenen Ort keine Oberflächendaten vorhanden sind. Die Laufzeit muss XR_ERROR_VALIDATION_FAILURE zurückgeben, wenn XR_SPATIAL_CAPABILITY_ANCHOR_EXT nicht für spatialContext konfiguriert wurde .

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrSurfaceAnchorCreateInfoANDROID ist so definiert:

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • geospatialTracker ist der zu verwendende XrGeospatialTrackerANDROID.
  • surfaceAnchorType ist der XrSurfaceAnchorTypeANDROID für den Anker.
  • eastUpSouthOrientation ist die Ausrichtung in Bezug auf ein Koordinatensystem, in dem +X=Osten, +Y=Oben und +Z=Süden ist.
  • latitude ist der Breitengrad in Grad zwischen -89,9 und +89,9.
  • longitude ist der Längengrad in Grad zwischen -180 und +180.
  • altitudeRelativeToSurface ist die Höhe in Metern relativ zur Oberfläche, die durch surfaceAnchorType angegeben wird .

Gültige Nutzung (implizit)

Die Funktion xrCreateSurfaceAnchorCompleteANDROID ist so definiert:

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

Parameterbeschreibungen

Gültige Nutzung (implizit)

Rückgabecodes

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Die Struktur XrSurfaceAnchorCreateCompletionANDROID enthält das Ergebnis einer asynchronen Erstellung eines Oberflächenankers.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

Mitgliederbeschreibungen

  • type ist der XrStructureType dieser Struktur.
  • next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
  • futureResult ist das XrResult des Erstellungsvorgangs. Wenn futureResult XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID ist , kann eine Struktur in der next-Kette weitere Informationen zum Fehler liefern.
  • anchorEntityId ist die XrSpatialEntityIdEXT des erstellten Ankers oder XR_NULL_SPATIAL_ENTITY_ID_EXT, wenn futureResult nicht XR_SUCCESS ist .

Zukünftige Rückgabecodes

futureResult-Werte:

Erfolg

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Fehler

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Gültige Nutzung (implizit)

Beispiel

Gelände-Anker erstellen

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

XrFuturePollInfoEXT anchorPollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT anchorPollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
anchorPollInfo.future = anchorFuture;
anchorPollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (anchorPollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &anchorPollInfo, &anchorPollResult));
}

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

Neue Befehle

Neue Strukturen

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

  • XrResult erweitern :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

  • Erweitern von XrStructureType :

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Probleme

Versionsverlauf

  • Version 1, 30.10.2025 (Ben King)

    • Erster Entwurf