XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahlnummer

790

Revision

1

Ratifikationsstatus

Nicht ratifiziert

Abhängigkeiten von Erweiterungen und Versionen

XR_EXT_future

Datum der letzten Änderung

2025-12-18

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 die Geospatial API von Google, die eine präzise geografische Positionierung und Ausrichtung ermöglicht und es der Anwendung erlaubt, Inhalte in Bezug auf die Erde zu platzieren. Dazu werden Bewegungserkennung, GPS und andere Sensoren sowie das Visual Positioning System (VPS) von Google verwendet. VPS vergleicht Bilder von der Kamera eines Geräts mit Street View-Bildern, um einen genauen Standort und eine Ausrichtung zu bestimmen. Die Geospatial API bietet oft eine Positionsgenauigkeit von unter einem Meter (Größenordnungen besser als GPS) und eine Ausrichtungsgenauigkeit von unter einem Grad.

Damit die APIs in dieser Erweiterung (mit Ausnahme der Prüfung auf Erweiterungssupport) verwendet werden können, muss die Anwendung die Authentifizierungsanmeldedaten über einen Mechanismus wie XR_ANDROID_google_cloud_auth erfolgreich festgelegt haben . Weitere Informationen zur Einrichtung und zu Fehlerergebnissen finden Sie in der Dokumentation der Autorisierungserweiterung.

Berechtigungen

Für Android-Anwendungen muss die Berechtigung „android.permission.ACCESS_FINE_LOCATION“ in ihrem Manifest aufgeführt sein, damit diese Erweiterung verwendet werden kann. Die Berechtigung „android.permission.ACCESS_FINE_LOCATION“ gilt als gefährliche Berechtigung. Die App muss die Berechtigung zur Laufzeit anfordern, um diese Funktionen zu verwenden:

• xrCreateGeospatialTrackerANDROID

(Schutzebene: gefährlich)

Systemfunktionen prüfen

Die Struktur XrSystemGeospatialPropertiesANDROID ist so definiert:

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

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.
• supportsGeospatial ist ein XrBool32, das angibt, ob das aktuelle System raumbezogene Funktionen unterstützt.

Eine Anwendung kann prüfen, ob das System raumbezogene Funktionen unterstützt, indem sie beim Aufrufen von xrGetSystemProperties eine XrSystemGeospatialPropertiesANDROID-Struktur an die XrSystemProperties-Struktur anhängt .

Wenn eine Laufzeit XR_FALSE für supportsGeospatial zurückgibt, unterstützt das System keine geospatiale Funktionen. Daher muss XR_ERROR_FEATURE_UNSUPPORTED von xrCreateGeospatialTrackerANDROID zurückgegeben werden. Die Anwendung sollte keine raumbezogenen Funktionen verwenden, wenn supportsGeospatial auf XR_FALSE gesetzt ist .

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor XrSystemGeospatialPropertiesANDROID verwendet werden kann.
• type muss XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID sein
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.

Geospatial Tracker-Alias erstellen

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

Die Funktion xrCreateGeospatialTrackerANDROID ist so definiert:

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

Parameterbeschreibungen

• session ist eine XrSession, in der der Geospatial-Tracker aktiv ist.
• createInfo ist ein Zeiger auf eine XrGeospatialTrackerCreateInfoANDROID-Struktur, die die anfänglichen Parameter des Geospatial-Trackers angibt.
• geospatialTrackerOutput ist ein Zeiger auf ein Handle, in dem der erstellte XrGeospatialTrackerANDROID zurückgegeben wird.

Eine Anwendung kann ein XrGeospatialTrackerANDROID-Handle erstellen, indem sie xrCreateGeospatialTrackerANDROID aufruft . Das zurückgegebene XrGeospatialTrackerANDROID-Handle kann anschließend in API-Aufrufen verwendet werden. Wenn die Anwendung die erforderlichen Berechtigungen nicht erhalten hat, muss die Laufzeit XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben . Für eine bestimmte XrSession kann jeweils nur ein XrGeospatialTrackerANDROID vorhanden sein . Die Anwendung muss dafür sorgen, dass alle vorherigen XrGeospatialTrackerANDROID-Objekte zerstört wurden, bevor diese Funktion noch einmal aufgerufen wird. Andernfalls muss die Laufzeit XR_ERROR_LIMIT_REACHED zurückgeben. Wenn der Tracker erfolgreich erstellt wurde, wechselt er zuerst in den Status XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID. Die Anwendung muss warten, bis sich der Status in XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ändert, bevor sie den Tracker verwenden kann. Weitere Informationen finden Sie unter XrEventDataGeospatialTrackerStateChangedANDROID . Wenn die Anwendung einen XrGeospatialTrackerANDROID übergibt, der sich nicht im Status XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID befindet, an eine Funktion, die ihn erfordert, muss die Laufzeit XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID zurückgeben .

Das XrGeospatialTrackerANDROID-Handle muss schließlich über die Funktion xrDestroyGeospatialTrackerANDROID freigegeben werden.

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss vor dem Aufrufen von xrCreateGeospatialTrackerANDROID aktiviert werden.
• session muss ein gültiger XrSession-Handle sein
• createInfo muss ein Zeiger auf eine gültige XrGeospatialTrackerCreateInfoANDROID-Struktur sein.
• geospatialTrackerOutput muss ein Zeiger auf ein XrGeospatialTrackerANDROID-Handle sein.

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_PERMISSION_INSUFFICIENT
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

Die Struktur XrGeospatialTrackerCreateInfoANDROID ist so definiert:

typedef struct XrGeospatialTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrGeospatialTrackerCreateInfoANDROID;

Mitgliederbeschreibungen

• type ist der XrStructureType dieser Struktur.
• next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor XrGeospatialTrackerCreateInfoANDROID verwendet wird.
• type muss XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID sein
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein . Weitere Informationen finden Sie unter XrGeospatialTrackerAnchorTrackingInfoANDROID.

Die Funktion xrDestroyGeospatialTrackerANDROID ist so definiert:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Parameterbeschreibungen

• geospatialTracker ist der XrGeospatialTrackerANDROID, der zerstört werden soll.

Eine Anwendung kann die Funktion xrDestroyGeospatialTrackerANDROID verwenden, um den Geospatial-Tracker und die zugrunde liegenden Ressourcen freizugeben.

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor xrDestroyGeospatialTrackerANDROID aufgerufen wird.
• geospatialTracker muss ein gültiger XrGeospatialTrackerANDROID-Handle sein

Threadsicherheit

• Der Zugriff auf geospatialTracker und alle untergeordneten Handles muss extern synchronisiert werden.

Rückgabecodes

Erfolg

• XR_SUCCESS

Fehler

• XR_ERROR_CALL_ORDER_INVALID
• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID

Status des Geospatial Trackers

Die Enumeration XrGeospatialTrackerStateANDROID ist so definiert:

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

Die Enumeration XrGeospatialTrackerStateANDROID gibt die verschiedenen Status eines Geospatial-Trackers an.

Die Enumerationen haben die folgenden Werte:

Enum-Beschreibung

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Der Geospatial Tracker wird nicht ausgeführt.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Der Geospatial-Tracker ist aktiv und nutzbar.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Der Geospatial Tracker konnte nicht initialisiert werden und kann nicht verwendet werden.

Die Struktur XrEventDataGeospatialTrackerStateChangedANDROID ist so definiert:

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

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, dessen Status sich geändert hat.
• state ist der neue XrGeospatialTrackerStateANDROID .
• initializationResult ist das Fehlerergebnis, wenn state gleich XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID ist, andernfalls XR_SUCCESS .
• time ist der XrTime, zu dem die Statusänderung erfolgt ist.

Die Struktur XrEventDataGeospatialTrackerStateChangedANDROID wird gesendet, wenn sich der Status des Geospatial-Trackers ändert. Wenn die Anwendung einen gültigen XrGeospatialTrackerANDROID hat , sollte sie dieses Ereignis abrufen. Das erste Ereignis, das für einen Tracker empfangen wird, hat state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Nach einer laufzeitabhängigen Zeit muss sich der Status entweder in XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID oder XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID ändern . Diese Umstellung kann unterschiedlich lange dauern. Wenn sich state in XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID ändert, muss dies das letzte Ereignis sein, das für diesen Tracker empfangen wurde, und das Feld initializationResult enthält den Fehlercode. Es kann einige Sekunden dauern, bis ein Fehler auftritt. Die Anwendung sollte den Tracker in diesem Fall zerstören. Wenn sich state in XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID ändert , muss die App das Tracking aller zuvor erstellten geospatialen Anker dauerhaft beenden und sollte sie zerstören. Der Status kann beliebig oft zwischen XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID und XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID wechseln.

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor XrEventDataGeospatialTrackerStateChangedANDROID verwendet werden kann.
• type muss XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID sein
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.

Geospatial Pose

Die Struktur XrGeospatialPoseANDROID ist so definiert:

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

Mitgliederbeschreibungen

• eastUpSouthOrientation ist ein XrQuaternionf, das die Ausrichtung in Bezug auf ein Koordinatensystem definiert, in dem +X=Osten, +Y=Oben und +Z=Süden ist.
• latitude ist der Breitengrad in Grad zwischen -90 und +90.
• longitude ist der Längengrad in Grad zwischen -180 und +180.
• altitude ist die Höhe in Metern über dem WGS84-Ellipsoid.

Die Struktur XrGeospatialPoseANDROID stellt eine Position und Ausrichtung relativ zur Erde mithilfe des WGS84-Ellipsoids dar.

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor XrGeospatialPoseANDROID verwendet werden kann.
• latitude muss ein gültiger double-Wert sein
• longitude muss ein gültiger double-Wert sein
• altitude muss ein gültiger double-Wert sein

Die Enumeration XrGeospatialPoseFlagBitsANDROID ist so definiert:

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

Die Enumeration XrGeospatialPoseFlagBitsANDROID gibt Flags für raumbezogene Posen an.

Die Flag-Bits haben die folgenden Bedeutungen:

Flag-Beschreibungen

• XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID: Gibt an, dass das Orientierungselement gültige Daten enthält.
• XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID: Gibt an, dass das Positionsmitglied gültige Daten enthält.

Der Typ XrGeospatialPoseFlagsANDROID ist eine Bitmaske von XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Umwandlung von XrPosef in Geospatial Pose

Die Funktion xrLocateGeospatialPoseFromPoseANDROID ist so definiert:

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

Parameterbeschreibungen

• geospatialTracker ist der XrGeospatialTrackerANDROID, der für die Konvertierung verwendet werden soll.
• locateInfo ist ein Zeiger auf XrGeospatialPoseFromPoseLocateInfoANDROID, der Suchparameter enthält.
• geospatialPoseResult ist ein Zeiger auf XrGeospatialPoseResultANDROID, der das Ergebnis empfängt.

Die Funktion xrLocateGeospatialPoseFromPoseANDROID konvertiert eine Pose in XrGeospatialPoseFromPoseLocateInfoANDROID :: space in eine geografische Pose. Wenn der Status von geospatialTracker nicht XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID ist , muss die Laufzeit XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID zurückgeben . Wenn die Funktion XR_SUCCESS zurückgibt, bestimmt das Feld XrGeospatialPoseResultANDROID :: poseFlags von geospatialPoseResult, welche Ausgabefelder gültig sind. Wenn XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID in XrGeospatialPoseResultANDROID :: poseFlags nicht festgelegt ist , darf die Anwendung die Felder XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy oder XrGeospatialPoseResultANDROID :: verticalAccuracy in XrGeospatialPoseResultANDROID nicht lesen . Wenn XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID in XrGeospatialPoseResultANDROID :: poseFlags nicht festgelegt ist , darf die Anwendung XrGeospatialPoseANDROID :: eastUpSouthOrientation oder XrGeospatialPoseResultANDROID :: orientationYawAccuracy nicht lesen . Wenn XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID nicht festgelegt ist, darf XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID nicht festgelegt werden.

Wenn die Genauigkeit geringer als erwartet ist, kann dies ein Hinweis darauf sein, dass das Gerät keine VPS-Lokalisierung verwendet. Die Anwendung kann den Nutzer auffordern, sein Gerät auf Schilder und Gebäude zu richten, um die Lokalisierung zu verbessern.

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor xrLocateGeospatialPoseFromPoseANDROID aufgerufen wird.
• geospatialTracker muss ein gültiger XrGeospatialTrackerANDROID-Handle sein
• locateInfo muss ein Zeiger auf eine gültige XrGeospatialPoseFromPoseLocateInfoANDROID-Struktur sein.
• geospatialPoseResult muss ein Zeiger auf eine XrGeospatialPoseResultANDROID-Struktur sein.

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_POSE_INVALID
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

Die Struktur XrGeospatialPoseFromPoseLocateInfoANDROID ist so definiert:

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

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 pose definiert ist.
• time ist der XrTime, an dem pose ausgewertet werden soll .
• pose ist die XrPosef in space, die in eine raumbezogene Pose umgewandelt werden soll.

Gültige Nutzung (implizit)

• Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor XrGeospatialPoseFromPoseLocateInfoANDROID verwendet wird.
• type muss XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID sein
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
• space muss ein gültiger XrSpace-Handle sein

Die Struktur XrGeospatialPoseResultANDROID ist so definiert:

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

Mitgliederbeschreibungen

• type ist der XrStructureType dieser Struktur.
• next ist NULL oder ein Zeiger auf die nächste Struktur in einer Strukturkette.
• poseFlags ist eine Bitmaske von XrGeospatialPoseFlagsANDROID, die die Gültigkeit von Positionskomponenten angibt.
• geospatialPose ist die resultierende XrGeospatialPoseANDROID .
• horizontalAccuracy ist die geschätzte horizontale Genauigkeit der Position des raumbezogenen Geräts, definiert als der Radius in Metern des Kreises mit einem Konfidenzniveau von 68% um den angegebenen Längen- und Breitengrad.
• verticalAccuracy ist die geschätzte vertikale Genauigkeit der Position des raumbezogenen Poses, definiert als die Entfernung in Metern des Konfidenzniveaus von 68% um die angegebene Höhe. Mit anderen Worten: Es besteht eine Wahrscheinlichkeit von 68 %, dass sich die tatsächliche Höhe im Bereich [ XrGeospatialPoseANDROID :: altitude – verticalAccuracy , XrGeospatialPoseANDROID :: altitude + verticalAccuracy ] befindet.
• orientationYawAccuracy ist die geschätzte Giergenauigkeit der Ausrichtung der raumbezogenen Position, definiert als der Radius in Grad des Konfidenzniveaus von 68% um die angegebene Ausrichtung.

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor XrGeospatialPoseResultANDROID verwendet werden kann.
• type muss XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID sein
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.

Geospatial Pose in XrPosef umwandeln

Die Funktion xrLocateGeospatialPoseANDROID ist so definiert:

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

Parameterbeschreibungen

• geospatialTracker ist der XrGeospatialTrackerANDROID, der für die Konvertierung verwendet werden soll.
• locateInfo ist ein Zeiger auf XrGeospatialPoseLocateInfoANDROID mit Suchparametern.
• location ist ein Zeiger auf XrSpaceLocation, der die resultierende Pose empfängt.

Die Funktion xrLocateGeospatialPoseANDROID konvertiert eine geografische Position in eine XrSpaceLocation . Wenn XrGeospatialTrackerANDROID nicht ausgeführt wird, muss die Laufzeit XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID zurückgeben . Wenn die Funktion XR_SUCCESS zurückgibt, bestimmt das Feld XrSpaceLocation :: locationFlags von location, welche Ausgabefelder gültig sind.

Gültige Nutzung (implizit)

•  Die Erweiterung XR_ANDROID_geospatial muss aktiviert werden, bevor xrLocateGeospatialPoseANDROID aufgerufen wird.
• geospatialTracker muss ein gültiger XrGeospatialTrackerANDROID-Handle sein
• locateInfo muss ein Zeiger auf eine gültige XrGeospatialPoseLocateInfoANDROID-Struktur sein.
• location muss ein Zeiger auf eine XrSpaceLocation-Struktur sein.

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_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

Die Struktur XrGeospatialPoseLocateInfoANDROID ist so definiert:

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

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 die resultierende Pose dargestellt wird.
• time ist der XrTime, an dem die Pose lokalisiert werden soll.
• geospatialPose ist die XrGeospatialPoseANDROID, die konvertiert werden soll.

Gültige Nutzung (implizit)

•  Die Erweiterung XR_ANDROID_geospatial muss aktiviert sein, bevor XrGeospatialPoseLocateInfoANDROID verwendet wird.
• type muss XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID sein
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
• space muss ein gültiger XrSpace-Handle sein
• geospatialPose muss eine gültige XrGeospatialPoseANDROID-Struktur sein

Verfügbarkeit von VPS

Die Enumeration XrVPSAvailabilityANDROID ist so definiert:

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

Die Enumeration XrVPSAvailabilityANDROID gibt die VPS-Verfügbarkeit an.

Die Enumerationen haben die folgenden Werte:

Enum-Beschreibung

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

VPS ist in der Nähe des angegebenen Standorts nicht verfügbar.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

VPS ist in der Nähe des angegebenen Standorts verfügbar.

Die Funktion xrCheckVpsAvailabilityAsyncANDROID ist so definiert:

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

Parameterbeschreibungen

• session ist die XrSession, die für die Prüfung verwendet werden soll.
• latitude ist der Breitengrad in Grad.
• longitude ist der Längengrad in Grad.
• future ist ein Zeiger auf XrFutureEXT, der das Ergebnis des asynchronen Vorgangs enthält.

Die Verfügbarkeit des Visual Positioning Service (VPS) gibt an, ob VPS verwendet werden kann, um die räumliche Genauigkeit an einem bestimmten Ort zu verbessern.

Die Funktion xrCheckVpsAvailabilityAsyncANDROID startet eine asynchrone Prüfung der VPS-Verfügbarkeit an einem bestimmten Ort. Die Anwendung benötigt keinen XrGeospatialTrackerANDROID, um diese Funktion aufzurufen, und kann anhand des Ergebnisses dieses Vorgangs entscheiden, ob ein solcher Tracker erstellt werden soll. Wenn die Anwendung die erforderlichen Berechtigungen nicht erhalten hat, muss die Laufzeit XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben .

Gültige Nutzung (implizit)

•  Die Erweiterung XR_ANDROID_geospatial muss aktiviert werden, bevor xrCheckVpsAvailabilityAsyncANDROID aufgerufen wird.
• session muss ein gültiger XrSession-Handle sein
• latitude muss ein gültiger double-Wert sein
• longitude muss ein gültiger double-Wert sein
• future muss ein Zeiger auf einen XrFutureEXT-Wert sein.

Rückgabecodes

Erfolg

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Fehler

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

Die Funktion xrCheckVpsAvailabilityCompleteANDROID ist so definiert:

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    completion);

Parameterbeschreibungen

• session ist die XrSession, die für die Prüfung verwendet wird.
• future ist der XrFutureEXT-Wert, der von xrCheckVpsAvailabilityAsyncANDROID zurückgegeben wird .
• completion ist ein Zeiger auf XrVPSAvailabilityCheckCompletionANDROID, der das Ergebnis empfängt.

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor xrCheckVpsAvailabilityCompleteANDROID aufgerufen wird.
• session muss ein gültiger XrSession-Handle sein
• completion muss ein Zeiger auf eine XrVPSAvailabilityCheckCompletionANDROID-Struktur sein.

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_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_VALIDATION_FAILURE

Die Struktur XrVPSAvailabilityCheckCompletionANDROID ist so definiert:

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

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 Prüfvorgangs. Wenn futureResult XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID ist , kann eine Struktur in der next-Kette weitere Informationen zum Fehler liefern.
• availability ist die resultierende XrVPSAvailabilityANDROID . Die Anwendung darf dieses Feld nur lesen, wenn futureResult 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_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Gültige Nutzung (implizit)

•  Die XR_ANDROID_geospatial-Erweiterung muss aktiviert werden, bevor XrVPSAvailabilityCheckCompletionANDROID verwendet wird.
• type muss XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID sein
• next muss NULL oder ein gültiger Zeiger auf die nächste Struktur in einer Strukturkette sein.
• futureResult muss ein gültiger XrResult-Wert sein
• availability muss ein gültiger XrVPSAvailabilityANDROID-Wert sein

Beispiel

Geospatial Tracker einrichten

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

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

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

Geospatial Pose APIs aufrufen

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

Neue Objekttypen

• XrGeospatialTrackerANDROID

Neue Befehle

• xrCheckVpsAvailabilityAsyncANDROID
• xrCheckVpsAvailabilityCompleteANDROID
• xrCreateGeospatialTrackerANDROID
• xrDestroyGeospatialTrackerANDROID
• xrLocateGeospatialPoseANDROID
• xrLocateGeospatialPoseFromPoseANDROID

Neue Strukturen

• XrEventDataGeospatialTrackerStateChangedANDROID
• XrGeospatialPoseANDROID
• XrGeospatialPoseFromPoseLocateInfoANDROID
• XrGeospatialPoseLocateInfoANDROID
• XrGeospatialPoseResultANDROID
• XrGeospatialTrackerCreateInfoANDROID
• XrVPSAvailabilityCheckCompletionANDROID

• XrSystemProperties erweitern :

  • XrSystemGeospatialPropertiesANDROID

Neue Enums

• XrGeospatialPoseFlagBitsANDROID
• XrGeospatialTrackerStateANDROID
• XrVPSAvailabilityANDROID

Neue Bitmasken

• XrGeospatialPoseFlagsANDROID

Neue Enum-Konstanten

• XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
• XR_ANDROID_geospatial_SPEC_VERSION

• XrObjectType erweitern :

  • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

• XrResult erweitern :

  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

• Erweitern von XrStructureType :

  • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
  • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
  • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
  • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
  • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
  • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

Probleme

Versionsverlauf

• Revision 1, 18.12.2025 (Ben King)

  • Erste Beschreibung der Erweiterung.