XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

790

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_EXT_future

Data ultima modifica

2025-12-18

Stato IP

Nessuna rivendicazione di PI nota.

Collaboratori

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

Panoramica

Questa estensione fornisce il monitoraggio geospaziale per l'API Geospatial di Google, che fornisce una geolocalizzazione e un orientamento precisi e consente all'applicazione di posizionare i contenuti rispetto alla Terra. A questo scopo, utilizza una combinazione di rilevamento del movimento, GPS e altri sensori, nonché il Visual Positioning System (VPS) di Google. Il VPS confronta le immagini della fotocamera di un dispositivo con le immagini di Street View per determinare una posizione esatta e un orientamento precisi. L'API Geospatial spesso fornisce un'accuratezza della posizione inferiore al metro (ordini di grandezza migliori rispetto al GPS) e un'accuratezza dell'orientamento inferiore al grado.

Per utilizzare correttamente le API in questa estensione (oltre a verificare il supporto dell'estensione), l'applicazione deve aver impostato correttamente le credenziali di autenticazione tramite un meccanismo, ad esempio XR_ANDROID_google_cloud_auth . Per ulteriori dettagli sulla configurazione e sui risultati degli errori, consulta la documentazione dell'estensione di autenticazione.

Autorizzazioni

Le app per Android devono disporre dell'autorizzazione android.permission.ACCESS_FINE_LOCATION elencata nel loro manifest per utilizzare questa estensione. L'autorizzazione android.permission.ACCESS_FINE_LOCATION è considerata pericolosa. L'applicazione deve richiedere l'autorizzazione in fase di runtime per utilizzare queste funzioni:

(livello di protezione: pericoloso)

Ispeziona la funzionalità del sistema

La struttura XrSystemGeospatialPropertiesANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • supportsGeospatial è un XrBool32 che indica se il sistema attuale supporta le funzionalità geospaziali.

Un'applicazione può verificare se il sistema supporta le funzionalità geospaziali concatenando una struttura XrSystemGeospatialPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties .

Se un runtime restituisce XR_FALSE per supportsGeospatial, il sistema non supporta le funzionalità geospaziali e pertanto deve restituire XR_ERROR_FEATURE_UNSUPPORTED da xrCreateGeospatialTrackerANDROID . L'applicazione dovrebbe evitare di utilizzare la funzionalità geospaziale quando supportsGeospatial è XR_FALSE .

Utilizzo valido (implicito)

Crea un handle del tracker geospaziale

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

La funzione xrCreateGeospatialTrackerANDROID è definita come:

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

Descrizioni dei parametri

Un'applicazione può creare un handle XrGeospatialTrackerANDROID chiamando xrCreateGeospatialTrackerANDROID . L'handle XrGeospatialTrackerANDROID restituito può essere utilizzato successivamente nelle chiamate API. Se l'applicazione non ha ottenuto le autorizzazioni richieste, il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT . Può esistere un solo XrGeospatialTrackerANDROID alla volta per una determinata XrSession . L'applicazione deve assicurarsi che tutti gli oggetti XrGeospatialTrackerANDROID precedenti siano stati eliminati prima di chiamare nuovamente questa funzione, altrimenti il runtime deve restituire XR_ERROR_LIMIT_REACHED . Se il tracker viene creato correttamente, inizialmente entrerà nello stato XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID e l'applicazione deve attendere che lo stato cambi in XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID prima di utilizzare il tracker. Consulta XrEventDataGeospatialTrackerStateChangedANDROID . Se l'applicazione passa un XrGeospatialTrackerANDROID che non è nello stato XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID a una funzione che lo richiede, il runtime deve restituire XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

L'handle XrGeospatialTrackerANDROID deve essere liberato tramite la funzione xrDestroyGeospatialTrackerANDROID.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrGeospatialTrackerCreateInfoANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.

Utilizzo valido (implicito)

La funzione xrDestroyGeospatialTrackerANDROID è definita come:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Descrizioni dei parametri

Un'applicazione può utilizzare la funzione xrDestroyGeospatialTrackerANDROID per rilasciare il tracker geospaziale e le risorse sottostanti.

Utilizzo valido (implicito)

Thread safety

  • L'accesso a geospatialTracker e a qualsiasi handle secondario deve essere sincronizzato esternamente

Codici di risposta

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Stato del tracker geospaziale

L'enumerazione XrGeospatialTrackerStateANDROID è definita come:

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;

L'enumerazione XrGeospatialTrackerStateANDROID identifica i diversi stati di un tracker geospaziale.

Gli enumeratori hanno i seguenti valori:

Descrizione enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Il Geospatial Tracker non è in esecuzione.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Il tracker geospaziale è in esecuzione e utilizzabile.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

L'inizializzazione del Geospatial Tracker non è riuscita e non sarà mai utilizzabile.

La struttura XrEventDataGeospatialTrackerStateChangedANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • geospatialTracker è l'oggetto XrGeospatialTrackerANDROID il cui stato è cambiato.
  • state è il nuovo XrGeospatialTrackerStateANDROID .
  • initializationResult è il risultato dell'errore se state è XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , altrimenti XR_SUCCESS .
  • time è il XrTime in cui è avvenuta la modifica dello stato.

La struttura XrEventDataGeospatialTrackerStateChangedANDROID viene inviata quando lo stato del tracker geospaziale cambia. Se l'applicazione ha un XrGeospatialTrackerANDROID valido, dovrebbe eseguire il polling per questo evento. Il primo evento ricevuto per un tracker avrà state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Dopo un periodo di tempo determinato dal runtime, lo stato deve cambiare in XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID o XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Questa transizione richiederà un periodo di tempo arbitrario. Se state cambia in XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID, deve essere l'ultimo evento ricevuto per questo tracker e il campo initializationResult conterrà il codice di errore. Potrebbero essere necessari diversi secondi prima che si verifichi un errore. In questo caso, l'applicazione deve eliminare il tracker. Se state diventa XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , tutte le ancora geospaziali create in precedenza devono interrompere definitivamente il monitoraggio e devono essere eliminate dall'applicazione. Lo stato può passare da XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID a XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID e viceversa un numero arbitrario di volte.

Utilizzo valido (implicito)

Posa geospaziale

La struttura XrGeospatialPoseANDROID è definita come:

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

Descrizioni dei membri

  • eastUpSouthOrientation è un XrQuaternionf che definisce l'orientamento rispetto a un sistema di coordinate in cui +X=Est, +Y=Su e +Z=Sud.
  • latitude è la latitudine in gradi, compresa tra -90 e +90.
  • longitude è la longitudine in gradi, compresa tra -180 e +180.
  • altitude è l'altitudine in metri sopra l'ellissoide WGS84.

La struttura XrGeospatialPoseANDROID rappresenta una posizione e un orientamento rispetto alla Terra utilizzando l'ellissoide WGS84.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_geospatial deve essere attivata prima di utilizzare XrGeospatialPoseANDROID
  • latitude deve essere un valore double valido
  • longitude deve essere un valore double valido
  • altitude deve essere un valore double valido

L'enumerazione XrGeospatialPoseFlagBitsANDROID è definita come:

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

L'enumerazione XrGeospatialPoseFlagBitsANDROID specifica i flag per le pose geospaziali.

I bit del flag hanno i seguenti significati:

Descrizioni dei flag

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID: indica che il membro dell'orientamento contiene dati validi
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID: indica che il membro della posizione contiene dati validi

Il tipo XrGeospatialPoseFlagsANDROID è una maschera di bit di XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Conversione di XrPosef in posa geospaziale

La funzione xrLocateGeospatialPoseFromPoseANDROID è definita come:

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

Descrizioni dei parametri

La funzione xrLocateGeospatialPoseFromPoseANDROID converte una posa in XrGeospatialPoseFromPoseLocateInfoANDROID :: space in una posa geospaziale. Se lo stato di geospatialTracker non è XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , il runtime deve restituire XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Se la funzione restituisce XR_SUCCESS , il campo poseFlags di geospatialPoseResult in XrGeospatialPoseResultANDROID determina quali campi di output sono validi. Se XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID non è impostato in XrGeospatialPoseResultANDROID :: poseFlags , l'applicazione non deve leggere i campi XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy o XrGeospatialPoseResultANDROID :: verticalAccuracy in XrGeospatialPoseResultANDROID . Se XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID non è impostato in XrGeospatialPoseResultANDROID :: poseFlags , l'applicazione non deve leggere XrGeospatialPoseANDROID :: eastUpSouthOrientation o XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Se XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID non è impostato, anche XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID non deve essere impostato.

Se la precisione è inferiore al previsto, potrebbe essere un'indicazione del fatto che il dispositivo non utilizza la localizzazione VPS. L'applicazione può chiedere all'utente di puntare il dispositivo verso cartelli ed edifici per migliorare la localizzazione.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrGeospatialPoseFromPoseLocateInfoANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • space è l'XrSpace in cui è definito pose.
  • time è il XrTime in cui valutare pose .
  • pose è l'XrPosef in space da convertire in una posa geospaziale.

Utilizzo valido (implicito)

La struttura XrGeospatialPoseResultANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • poseFlags è una maschera di bit di XrGeospatialPoseFlagsANDROID che indica la validità dei componenti della posa.
  • geospatialPose è l'oggetto XrGeospatialPoseANDROID risultante.
  • horizontalAccuracy è l'accuratezza orizzontale stimata della posizione della posa Geospatial, definita come il raggio in metri del cerchio con un livello di confidenza del 68% intorno alla latitudine e alla longitudine indicate.
  • verticalAccuracy è la precisione verticale stimata della posizione della posa Geospatial, definita come la distanza in metri del livello di confidenza del 68% intorno all'altitudine specificata. In altre parole, esiste una probabilità del 68% che l'altitudine reale sia compresa nell'intervallo [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • orientationYawAccuracy è l'accuratezza dell'imbardata stimata dell'orientamento della posa Geospatial, definita come il raggio in gradi del livello di confidenza del 68% attorno all'orientamento specificato.

Utilizzo valido (implicito)

Conversione di una posa geospaziale in un XrPosef

La funzione xrLocateGeospatialPoseANDROID è definita come segue:

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

Descrizioni dei parametri

La funzione xrLocateGeospatialPoseANDROID converte una posa geospaziale in un XrSpaceLocation . Se XrGeospatialTrackerANDROID non è in esecuzione, il runtime deve restituire XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Se la funzione restituisce XR_SUCCESS , il campo locationFlags di XrSpaceLocation :: location determina quali campi di output sono validi.

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrGeospatialPoseLocateInfoANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • space è l'XrSpace in cui verrà rappresentata la posa risultante.
  • time è la XrTime in cui individuare la posa.
  • geospatialPose è l'oggetto XrGeospatialPoseANDROID da convertire.

Utilizzo valido (implicito)

Disponibilità VPS

L'enumerazione XrVPSAvailabilityANDROID è definita come:

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

L'enumerazione XrVPSAvailabilityANDROID indica la disponibilità del VPS.

Gli enumeratori hanno i seguenti valori:

Descrizione enum

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

VPS non è disponibile vicino alla posizione specificata.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

Il VPS è disponibile nelle vicinanze della località specificata.

La funzione xrCheckVpsAvailabilityAsyncANDROID è definita come segue:

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

Descrizioni dei parametri

  • session è l'oggetto XrSession da utilizzare per il controllo.
  • latitude è la latitudine in gradi.
  • longitude è la longitudine in gradi.
  • future è un puntatore a XrFutureEXT che conterrà il risultato dell'operazione asincrona.

La disponibilità del servizio di posizionamento visivo (VPS) indica se il VPS può essere utilizzato per migliorare l'accuratezza geospaziale in una determinata località.

La funzione xrCheckVpsAvailabilityAsyncANDROID avvia un controllo asincrono della disponibilità di VPS in una determinata località. L'applicazione non richiede un XrGeospatialTrackerANDROID per chiamare questa funzione e può utilizzare il risultato di questa operazione per decidere se crearne uno. Se l'applicazione non ha ottenuto le autorizzazioni richieste, il runtime deve restituire XR_ERROR_PERMISSION_INSUFFICIENT .

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_geospatial deve essere abilitata prima di chiamare xrCheckVpsAvailabilityAsyncANDROID
  • session deve essere un handle XrSession valido
  • latitude deve essere un valore double valido
  • longitude deve essere un valore double valido
  • future deve essere un puntatore a un valore XrFutureEXT

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La funzione xrCheckVpsAvailabilityCompleteANDROID è definita come:

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

Descrizioni dei parametri

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrVPSAvailabilityCheckCompletionANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • futureResult è l'XrResult dell'operazione di controllo. Se futureResult è XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , una struttura nella catena next potrebbe fornire ulteriori informazioni sull'errore.
  • availability è il valore XrVPSAvailabilityANDROID risultante. L'applicazione non deve leggere questo campo, a meno che futureResult non sia XR_SUCCESS .

Codici di reso futuri

Valori futureResult:

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Utilizzo valido (implicito)

Esempio

Configura Geospatial Tracker

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;
      }
  }
}

Chiama le API Geospatial Pose

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.
}

Nuovi tipi di oggetti

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove maschere di bit

Nuove costanti enum

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Estensione di XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Estensione di XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • Estensione di 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

Problemi

Cronologia delle versioni

  • Revisione 1, 18/12/2025 (Ben King)

    • Descrizione iniziale dell'estensione.