XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

798

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_ANDROID_geospatial
e
XR_EXT_future
e
XR_EXT_spatial_entity
e
XR_EXT_spatial_anchor

Data ultima modifica

30/10/2025

Stato IP

Nessuna rivendicazione di PI nota.

Collaboratori

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

Panoramica

Questa estensione fornisce ancoraggi geospaziali e ancoraggi di superficie che si basano sull'estensione geospaziale di base. Le ancore geospaziali sono ancore posizionate nello spazio rispetto alla Terra a una determinata latitudine, longitudine e altitudine. Le ancore di superficie sono ancore relative alla Terra posizionate a una determinata latitudine, longitudine e altitudine rispetto a una superficie nota al servizio di posizionamento visivo. Man mano che la precisione della posizione del runtime rispetto alla Terra migliora, la posa dell'ancora si adatta di conseguenza.

Funzionalità di sistema per gli ancoraggi geospaziali

La struttura XrSystemGeospatialAnchorPropertiesANDROID è definita come:

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

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.
  • maxSurfaceAnchorCount è un uint32_t che indica il numero massimo di ancoraggi di superficie che possono essere creati.

Un'applicazione può ispezionare le funzionalità di ancoraggio geospaziale del sistema concatenando una struttura XrSystemGeospatialAnchorPropertiesANDROID a XrSystemProperties quando chiama xrGetSystemProperties .

Se XrSystemGeospatialPropertiesANDROID :: supportsGeospatial è XR_TRUE, maxSurfaceAnchorCount indica il numero massimo di ancoraggi di superficie supportati dal runtime. In questo caso, il limite deve essere maggiore di 0.

Se XrSystemGeospatialPropertiesANDROID :: supportsGeospatial non è XR_TRUE, maxSurfaceAnchorCount deve essere 0.

Utilizzo valido (implicito)

Tracciamento dei piani per le ancora

La struttura XrGeospatialTrackerAnchorTrackingInfoANDROID è definita come:

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • shouldTrackPlanes è un XrBool32 che indica se il tracker geospaziale monitorerà i piani per migliorare il posizionamento delle ancora bloccate sulla superficie.

Il rilevamento dei piani può essere attivato per migliorare il posizionamento delle ancora bloccate sulla superficie.

Se l'applicazione vuole attivare il rilevamento dei piani per migliorare le pose degli ancoraggi di superficie, può concatenare una struttura XrGeospatialTrackerAnchorTrackingInfoANDROID a XrGeospatialTrackerCreateInfoANDROID quando chiama xrCreateGeospatialTrackerANDROID .

Utilizzo valido (implicito)

Ancoraggi geospaziali

La funzione xrCreateGeospatialAnchorANDROID è definita come:

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

Descrizioni dei parametri

  • spatialContext è l'XrSpatialContextEXT in cui creare l'ancoraggio. Il contesto deve essere configurato per XR_SPATIAL_CAPABILITY_ANCHOR_EXT, altrimenti il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .
  • createInfo è un puntatore a XrGeospatialAnchorCreateInfoANDROID contenente i parametri di creazione dell'ancoraggio.
  • anchorEntityId è un puntatore a XrSpatialEntityIdEXT in cui viene restituito l'ID entità di ancoraggio.

Se l'elemento XrGeospatialTrackerANDROID specificato in XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker non è nello stato XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, il runtime deve restituire XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La struttura XrGeospatialAnchorCreateInfoANDROID è definita come:

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

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 da utilizzare per creare l'ancoraggio.
  • geospatialPose è un puntatore a XrGeospatialPoseANDROID che definisce la posizione e l'orientamento dell'ancoraggio.

Utilizzo valido (implicito)

Ancoraggi di superficie

Le ancora di superficie sono ancore posizionate rispetto a una superficie, come il terreno o i tetti.

L'enumerazione XrSurfaceAnchorTypeANDROID è definita come:

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

L'enumerazione XrSurfaceAnchorTypeANDROID specifica il tipo di superficie a cui è relativo un ancoraggio.

Gli enumeratori hanno i seguenti valori:

Descrizione enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Tipo di ancoraggio posizionato rispetto al suolo.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Tipo di ancoraggio posizionato rispetto al tetto o al suolo dove non è presente un edificio.

La funzione xrCreateSurfaceAnchorAsyncANDROID è definita come:

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

Descrizioni dei parametri

  • spatialContext è l'XrSpatialContextEXT in cui creare l'ancoraggio.
  • createInfo è un puntatore a XrSurfaceAnchorCreateInfoANDROID contenente i parametri di creazione dell'ancoraggio.
  • future è un puntatore a XrFutureEXT che conterrà il risultato dell'operazione asincrona.

La funzione xrCreateSurfaceAnchorAsyncANDROID avvia un'operazione asincrona per creare un ancoraggio di superficie. A differenza degli ancoraggi geospaziali standard, il runtime potrebbe recuperare i dati del terreno per determinare l'altitudine corretta. Il runtime deve restituire XR_ERROR_LIMIT_REACHED se l'applicazione tenta di creare più di XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount ancoraggi di superficie alla volta. Se XrGeospatialTrackerANDROID specificato in XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker non è nello stato XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, il runtime deve restituire XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . L'operazione potrebbe non riuscire in modo asincrono con il risultato XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID se non sono presenti dati sulla superficie per la località specificata. Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE se XR_SPATIAL_CAPABILITY_ANCHOR_EXT non è stato configurato per spatialContext .

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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La struttura XrSurfaceAnchorCreateInfoANDROID è definita come:

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

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 da utilizzare.
  • surfaceAnchorType è l'XrSurfaceAnchorTypeANDROID per l'ancoraggio.
  • eastUpSouthOrientation è l'orientamento rispetto a un sistema di coordinate in cui +X=Est, +Y=Su e +Z=Sud.
  • latitude è la latitudine in gradi, compresa tra -89,9 e +89,9.
  • longitude è la longitudine in gradi, compresa tra -180 e +180.
  • altitudeRelativeToSurface è l'altitudine in metri rispetto alla superficie specificata da surfaceAnchorType .

Utilizzo valido (implicito)

La funzione xrCreateSurfaceAnchorCompleteANDROID è definita come:

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     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_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La struttura XrSurfaceAnchorCreateCompletionANDROID contiene il risultato di una creazione asincrona di un ancoraggio di superficie.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

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 creazione. Se futureResult è XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , una struttura nella catena next potrebbe fornire ulteriori informazioni sull'errore.
  • anchorEntityId è il XrSpatialEntityIdEXT dell'ancoraggio creato o XR_NULL_SPATIAL_ENTITY_ID_EXT se futureResult non è 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_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Utilizzo valido (implicito)

Esempio

Crea un ancoraggio del terreno

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

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

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION

  • Estensione di XrResult :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

  • Estensione di XrStructureType :

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Problemi

Cronologia delle versioni

  • Revisione 1, 30/10/2025 (Ben King)

    • Bozza iniziale.