XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

Erweiterungstyp

Instanzerweiterung

Registrierte Durchwahl

790

Revision

1

Ratification Status

Nicht ratifiziert

Erweiterungs- und Versionsabhängigkeiten

XR_EXT_future

Datum der letzten Änderung

2025-12-18

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 das Geospatial-Tracking für die Geospatial API von Google, die genaue Standort- und Ausrichtungsdaten liefert und es der Anwendung ermöglicht, Inhalte in Bezug auf die Erde zu platzieren. Dazu wird eine Kombination aus Bewegungserkennung, GPS und anderen Sensoren sowie dem Visual Positioning System (VPS) von Google verwendet. Das VPS vergleicht Bilder von der Kamera eines Geräts mit Street View-Bildern, um einen genauen Standort und eine genaue Ausrichtung zu bestimmen. Die Geospatial API bietet oft eine Positionsgenauigkeit von weniger als einem Meter (um Größenordnungen besser als GPS) und eine Ausrichtungsgenauigkeit von weniger als einem Grad.

Damit die APIs in dieser Erweiterung erfolgreich verwendet werden können (außer zur Prüfung der Erweiterungsunterstützung), muss die Anwendung Authentifizierungsdaten über einen Mechanismus wie XR_ANDROID_google_cloud_auth festgelegt haben. Weitere Informationen zur Einrichtung und zu Fehlerergebnissen finden Sie in der Dokumentation zur Authentifizierungserweiterung.

Berechtigungen

Android-Apps müssen die Berechtigung „android.permission.ACCESS_FINE_LOCATION“ in ihrem Manifest enthalten, um diese Erweiterung verwenden zu können. Die Berechtigung „android.permission.ACCESS_FINE_LOCATION“ gilt als gefährliche Berechtigung. Die Anwendung muss die Berechtigung zur Laufzeit anfordern, um diese Funktionen zu verwenden:

(Schutzebene: gefährlich)

Systemkapazität 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 weder in OpenXR noch in dieser Erweiterung definiert.
  • supportsGeospatial ist ein XrBool32, der angibt, ob das aktuelle System Geofunktionen unterstützt.

Eine Anwendung kann prüfen, ob das System Geodatenfunktionen unterstützt, indem sie beim Aufruf von xrGetSystemProperties eine XrSystemGeospatialPropertiesANDROID-Struktur mit den XrSystemProperties verknüpft.

Wenn eine Laufzeit XR_FALSE für supportsGeospatial zurückgibt, unterstützt das System keine Geofunktionen und muss daher XR_ERROR_FEATURE_UNSUPPORTED von xrCreateGeospatialTrackerANDROID zurückgeben. Die Anwendung sollte keine raumbezogenen Funktionen verwenden, wenn supportsGeospatial den Wert XR_FALSE hat.

Gültige Verwendung (implizit)

Handle für Geospatial Tracker erstellen

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

Die Funktion xrCreateGeospatialTrackerANDROID ist so definiert:

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

Parameterbeschreibungen

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 nicht die erforderlichen Berechtigungen erhalten hat, muss die Laufzeit XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben. Es kann jeweils nur ein XrGeospatialTrackerANDROID für eine bestimmte XrSession existieren. Die Anwendung muss dafür sorgen, dass alle vorherigen XrGeospatialTrackerANDROID-Objekte gelöscht wurden, bevor diese Funktion wieder 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 der Status zu XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID wechselt, bevor der Tracker verwendet werden kann. Weitere Informationen finden Sie unter XrEventDataGeospatialTrackerStateChangedANDROID . Wenn die Anwendung einen XrGeospatialTrackerANDROID, der sich nicht im Status XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID befindet, an eine Funktion übergibt, 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 Verwendung (implizit)

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 Verwendung (implizit)

Die Funktion xrDestroyGeospatialTrackerANDROID ist so definiert:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Parameterbeschreibungen

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

Gültige Verwendung (implizit)

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
  • XR_ERROR_RUNTIME_FAILURE

Geospatial Tracker State

Die Aufzählung 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 Aufzählung XrGeospatialTrackerStateANDROID identifiziert die verschiedenen Zustände eines Geospatial-Trackers.

Die Enumeranten 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 kann verwendet werden.

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, an dem die Statusänderung aufgetreten 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 abfragen. Das erste Ereignis, das für einen Tracker empfangen wird, hat state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Nach einer von der Laufzeit bestimmten Zeit muss sich der Status entweder in XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID oder XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID ändern. Diese Umstellung dauert eine beliebige Zeit. 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. Das Feld initializationResult enthält dann den Fehlercode. Es kann einige Sekunden dauern, bis ein Fehler auftritt. In diesem Fall sollte die Anwendung den Tracker löschen. Wenn sich state in XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID ändert, muss das Tracking aller zuvor erstellten Georäumlichen Anker dauerhaft beendet werden und sie sollten von der Anwendung gelöscht werden. Der Status kann beliebig oft zwischen XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID und XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID wechseln.

Gültige Verwendung (implizit)

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 dar, wobei das WGS84-Ellipsoid verwendet wird.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_geospatial muss aktiviert sein, bevor Sie XrGeospatialPoseANDROID verwenden können.
  • 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 Aufzählung 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 Aufzählung XrGeospatialPoseFlagBitsANDROID gibt Flags für raumbezogene Positionen an.

Die Flag-Bits haben die folgenden Bedeutungen:

Flag-Beschreibungen

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

Der Typ XrGeospatialPoseFlagsANDROID ist eine Bitmaske von XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

XrPosef in Geospatial Pose umwandeln

Die Funktion xrLocateGeospatialPoseFromPoseANDROID ist so definiert:

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

Parameterbeschreibungen

Die Funktion xrLocateGeospatialPoseFromPoseANDROID konvertiert eine Pose in XrGeospatialPoseFromPoseLocateInfoANDROID :: space in eine Geospatial-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 poseFlags von geospatialPoseResult in XrGeospatialPoseResultANDROID, welche Ausgabefelder gültig sind. Wenn XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID nicht in XrGeospatialPoseResultANDROID :: poseFlags 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 nicht in XrGeospatialPoseResultANDROID :: poseFlags 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 ebenfalls nicht festgelegt sein.

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

Gültige Verwendung (implizit)

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 Geopose konvertiert werden soll.

Gültige Verwendung (implizit)

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 Pose-Komponenten angibt.
  • geospatialPose ist die resultierende XrGeospatialPoseANDROID .
  • horizontalAccuracy ist die geschätzte horizontale Genauigkeit der Position der Geospatial-Pose, definiert als Radius in Metern des Kreises mit einem Konfidenzniveau von 68 % um den angegebenen Breiten- und Längengrad.
  • verticalAccuracy ist die geschätzte vertikale Genauigkeit der Position der Geospatial-Pose, definiert als die Entfernung in Metern mit einem Konfidenzniveau von 68 % um die angegebene Höhe. Mit anderen Worten: Es besteht eine Wahrscheinlichkeit von 68 %, dass die tatsächliche Höhe im Bereich [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ] liegt.
  • orientationYawAccuracy ist die geschätzte Giergenauigkeit der Ausrichtung der Geospatial-Pose, definiert als Radius in Grad mit einem Konfidenzniveau von 68 % um die angegebene Ausrichtung.

Gültige Verwendung (implizit)

Geospatial Pose in XrPosef konvertieren

Die Funktion xrLocateGeospatialPoseANDROID ist so definiert:

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

Parameterbeschreibungen

Die Funktion xrLocateGeospatialPoseANDROID konvertiert eine Geospatial-Pose in eine XrSpaceLocation . Wenn der 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 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_POSE_INVALID
  • 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 die XrTime, an der die Pose gefunden werden soll.
  • geospatialPose ist die zu konvertierende XrGeospatialPoseANDROID.

Gültige Verwendung (implizit)

VPS-Verfügbarkeit

Die Aufzählung 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 Aufzählung XrVPSAvailabilityANDROID gibt die VPS-Verfügbarkeit an.

Die Enumeranten 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 Genauigkeit der Geodaten 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 das Ergebnis dieses Vorgangs verwenden, um zu entscheiden, ob ein solcher erstellt werden soll. Wenn die Anwendung nicht die erforderlichen Berechtigungen erhalten hat, muss die Laufzeit XR_ERROR_PERMISSION_INSUFFICIENT zurückgeben.

Gültige Verwendung (implizit)

  • Die Erweiterung XR_ANDROID_geospatial muss aktiviert sein, bevor xrCheckVpsAvailabilityAsyncANDROID aufgerufen wird.
  • session muss ein gültiges 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

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_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 den Wert XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID hat, enthält eine Struktur in der next-Kette möglicherweise weitere Informationen zum Fehler.
  • availability ist die resultierende XrVPSAvailabilityANDROID . Die Anwendung darf dieses Feld nur lesen, wenn futureResult den Wert XR_SUCCESS hat.

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 Verwendung (implizit)

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

Neue Befehle

Neue Gebäude

Neue Enums

Neue Bitmasken

Neue Enum-Konstanten

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Erweiterung von XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Erweiterung von XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

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

  • Version 1, 18.12.2025 (Ben King)

    • Erste Beschreibung der Erweiterung.