XR_ANDROID_geospatial

Stringa del nome

XR_ANDROID_geospatial

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

790

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze da estensioni e versioni

XR_EXT_future

Data ultima modifica

2025-12-18

Stato IP

Nessuna rivendicazione di proprietà intellettuale 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 orientamento e geolocalizzazione 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 sistema di posizionamento visivo (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 una precisione di posizionamento inferiore al metro (ordini di grandezza migliore del GPS) e una precisione di 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

Per utilizzare questa estensione, le applicazioni Android devono avere l'autorizzazione android.permission.ACCESS_FINE_LOCATION elencata nel file manifest. 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)

Ispezionare 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 alla struttura XrSystemProperties quando chiama xrGetSystemProperties .

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

Utilizzo valido (implicito)

Creare un handle di monitoraggio 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 di nuovo questa funzione, altrimenti il runtime deve restituire XR_ERROR_LIMIT_REACHED . Se il tracker viene creato correttamente, inizialmente entra 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. Vedi XrEventDataGeospatialTrackerStateChangedANDROID . Se l'applicazione passa un XrGeospatialTrackerANDROID che non si trova 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 ritorno

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 tutti gli handle secondari deve essere sincronizzato esternamente

Codici di ritorno

Operazione riuscita

  • XR_SUCCESS

Errore

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

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 enumeranti hanno i seguenti valori:

Descrizione enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Il tracker geospaziale non è in esecuzione.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Il tracker geospaziale è in esecuzione e utilizzabile.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Il tracker geospaziale non è stato inizializzato 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 è 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 si è verificata la modifica dello stato.

La struttura XrEventDataGeospatialTrackerStateChangedANDROID viene inviata quando cambia lo stato del tracker geospaziale. Se l'applicazione ha un XrGeospatialTrackerANDROID valido , deve 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 in fase di runtime, lo stato deve passare a 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 cambia in XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , tutti gli ancoraggi geospaziali creati in precedenza devono interrompere definitivamente il monitoraggio e devono essere distrutti dall'applicazione. Lo stato potrebbe cambiare più volte tra XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID e XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID.

Utilizzo valido (implicito)

Posizione 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 di 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 Geospatial Pose

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 XrGeospatialPoseResultANDROID :: poseFlags di geospatialPoseResult 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, XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID non deve essere impostato.

Se la precisione è inferiore al previsto, questo potrebbe indicare che il dispositivo non utilizza la localizzazione VPS. L'applicazione può chiedere all'utente di puntare il dispositivo verso cartelli e edifici per migliorare la localizzazione.

Utilizzo valido (implicito)

Codici di ritorno

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 è lo XrSpace in cui è definito pose.
  • time è il XrTime in cui valutare pose .
  • pose è 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 è XrGeospatialPoseANDROID risultante .
  • horizontalAccuracy è l'accuratezza orizzontale stimata della posizione della postura spaziale, 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 postura spaziale, definita come la distanza in metri del livello di confidenza del 68% intorno all'altitudine specificata. In altre parole, c'è una probabilità del 68% che l'altitudine reale si trovi nell'intervallo [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • orientationYawAccuracy è l'accuratezza stimata dell'orientamento della postura geospaziale, definita come il raggio in gradi del livello di confidenza del 68% intorno all'orientamento specificato.

Utilizzo valido (implicito)

Conversione di una posa geospaziale in un XrPosef

La funzione xrLocateGeospatialPoseANDROID è definita come:

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 XrSpaceLocation :: locationFlags di location determina quali campi di output sono validi.

Utilizzo valido (implicito)

Codici di ritorno

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_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 è il XrTime in cui individuare la posa.
  • geospatialPose è XrGeospatialPoseANDROID da convertire.

Utilizzo valido (implicito)

Disponibilità di 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à di VPS.

Gli enumeranti hanno i seguenti valori:

Descrizione enum

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

VPS non è disponibile vicino alla posizione indicata.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

Il VPS è disponibile vicino alla posizione specificata.

La funzione xrCheckVpsAvailabilityAsyncANDROID è definita come:

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

Descrizioni dei parametri

  • session è l'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 posizione.

La funzione xrCheckVpsAvailabilityAsyncANDROID avvia un controllo asincrono della disponibilità di VPS in una determinata posizione. L'applicazione non ha bisogno di 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 attivata 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 ritorno

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 segue:

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

Descrizioni dei parametri

Utilizzo valido (implicito)

Codici di ritorno

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 maggiori informazioni sull'errore.
  • availability è il valore risultante di XrVPSAvailabilityANDROID . 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

Configurare il tracker geospaziale

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

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