XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

798

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

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

Keine bekannten Ansprüche auf geistiges Eigentum.

Mitwirkende

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

Übersicht

Diese Erweiterung bietet Georäumliche Anker und Oberflächenanker, die auf der grundlegenden Georäumlichen Erweiterung aufbauen. Geospatial Anchors sind Anker, die im Raum relativ zur Erde an einem bestimmten Längen- und Breitengrad und in einer bestimmten Höhe positioniert sind. Oberflächenanker sind erdbezogene Anker, die an einem bestimmten Breiten- und Längengrad sowie in einer bestimmten Höhe relativ zu einer Oberfläche platziert werden, die dem Visual Positioning Service bekannt ist. Wenn sich die Genauigkeit der Position der Laufzeit relativ zur Erde verbessert, wird die Position des Ankers entsprechend angepasst.

Systemfunktionen für Georäumliche 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 weder in OpenXR noch in dieser Erweiterung definiert.
  • maxSurfaceAnchorCount ist ein uint32_t, der die maximale Anzahl von Oberflächenankern angibt, die erstellt werden können.

Eine Anwendung kann die Funktionen des Systems für Georäumliche Anker prüfen, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemGeospatialAnchorPropertiesANDROID-Struktur mit den XrSystemProperties verknüpft.

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

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

Gültige Verwendung (implizit)

Ebenen-Tracking 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, der angibt, ob der Geospatial Tracker Ebenen verfolgt, um die Positionierung von oberflächengebundenen Ankern zu verbessern.

Die Ebenenerkennung kann aktiviert werden, um die Positionierung von an Oberflächen verankerten Ankern zu verbessern.

Wenn die Anwendung das Ebenen-Tracking aktivieren möchte, um die Positionen von Oberflächenankern zu verbessern, kann sie beim Aufruf von xrCreateGeospatialTrackerANDROID eine XrGeospatialTrackerAnchorTrackingInfoANDROID-Struktur mit XrGeospatialTrackerCreateInfoANDROID verketten.

Gültige Verwendung (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 für die Erstellung des Ankers enthält.
  • anchorEntityId ist ein Verweis auf XrSpatialEntityIdEXT, in dem die ID der Ankerentität zurückgegeben wird.

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

Gültige Verwendung (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_POSE_INVALID
  • 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 Verwendung (implizit)

Oberflächenanker

Oberflächenanker sind Anker, die relativ zu einer Oberfläche wie Gelände oder Dächern platziert werden.

Die Aufzählung 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 Aufzählung XrSurfaceAnchorTypeANDROID gibt den Typ der Oberfläche an, auf die sich ein Anker bezieht.

Die Enumeranten 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 für die Erstellung des Ankers 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 raumbezogenen Ankern kann die Laufzeit Geländedaten abrufen, um die richtige Höhe zu bestimmen. Die Laufzeit muss XR_ERROR_LIMIT_REACHED zurückgeben, wenn die Anwendung versucht, mehr als XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount Oberflächenanker gleichzeitig zu erstellen. Wenn sich der in XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker angegebene XrGeospatialTrackerANDROID nicht im Status XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID befindet, 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 Verwendung (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_POSE_INVALID
  • 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 zu der durch surfaceAnchorType angegebenen Oberfläche.

Gültige Verwendung (implizit)

Die Funktion xrCreateSurfaceAnchorCompleteANDROID ist so definiert:

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

Parameterbeschreibungen

Gültige Verwendung (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 Oberflächenanker-Erstellung.

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 den Wert XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID hat, enthält eine Struktur in der next-Kette möglicherweise weitere Informationen zum Fehler.
  • 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 Verwendung (implizit)

Beispiel

Terrain-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 Gebäude

Neue Enums

Neue Enum-Konstanten

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION
  • Erweiterung von XrResult :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • Erweiterung 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.