XR_ANDROID_geospatial_anchor

Stringa del nome

XR_ANDROID_geospatial_anchor

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

798

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze di estensione e versione

XR_ANDROID_geospatial
e
XR_EXT_future
e
XR_EXT_spatial_entity
e
XR_EXT_spatial_anchor

Data dell'ultima modifica

2025-10-30

Stato IP

Nessuna rivendicazione IP nota.

Collaboratori

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

Panoramica

Questa estensione fornisce ancore geospaziali e ancore 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 che vengono posizionate a una determinata latitudine, longitudine e altitudine rispetto a una superficie nota al servizio di posizionamento visivo. Man mano che l'accuratezza della posizione del runtime rispetto alla Terra migliora, la posa dell'ancora si adatterà di conseguenza.

Funzionalità di sistema per le ancore 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 di queste strutture è definita in OpenXR di base o in questa estensione.
  • maxSurfaceAnchorCount è un uint32_t che indica il numero massimo di ancore di superficie che possono essere create.

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 ancore di superficie supportate 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 ancore

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 traccerà i piani per migliorare il posizionamento delle ancore bloccate sulla superficie.

Il tracciamento dei piani può essere abilitato per migliorare il posizionamento delle ancore bloccate sulla superficie.

Se l'applicazione vuole abilitare il tracciamento dei piani per migliorare le pose delle ancore di superficie, può concatenare una struttura XrGeospatialTrackerAnchorTrackingInfoANDROID a XrGeospatialTrackerCreateInfoANDROID quando chiama xrCreateGeospatialTrackerANDROID .

Utilizzo valido (implicito)

Ancore 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'ancora. 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'ancora.
  • anchorEntityId è un puntatore a XrSpatialEntityIdEXT in cui viene restituito l'ID dell'entità ancora.

Se l'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 restituiti

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

Utilizzo valido (implicito)

Ancore di superficie

Le ancore di superficie sono ancore posizionate rispetto a una superficie, ad esempio un terreno o un tetto.

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 rispetto alla quale è posizionata un'ancora.

Gli enumeratori hanno i seguenti valori:

Descrizione dell'enumerazione

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Tipo di ancora posizionata rispetto al suolo.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Tipo di ancora posizionata rispetto al tetto o al terreno in cui non è presente alcun 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'ancora.
  • createInfo è un puntatore a XrSurfaceAnchorCreateInfoANDROID contenente i parametri di creazione dell'ancora.
  • future è un puntatore a XrFutureEXT che conterrà il risultato dell'operazione asincrona.

La funzione xrCreateSurfaceAnchorAsyncANDROID avvia un'operazione asincrona per creare un'ancora di superficie. A differenza delle ancore geospaziali standard, il runtime può recuperare i dati del rilievo per determinare l'altitudine corretta. Il runtime deve restituire XR_ERROR_LIMIT_REACHED se l'applicazione tenta di creare più di XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount ancore di superficie contemporaneamente. Se l'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 può non riuscire in modo asincrono con il risultato XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID se non sono presenti dati di 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 restituiti

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_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'XrGeospatialTrackerANDROID da utilizzare.
  • surfaceAnchorType è l'XrSurfaceAnchorTypeANDROID per l'ancora.
  • 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 restituiti

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'ancora 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 può fornire ulteriori informazioni sull'errore.
  • anchorEntityId è il XrSpatialEntityIdEXT dell'ancora creata o XR_NULL_SPATIAL_ENTITY_ID_EXT se futureResult non è XR_SUCCESS .

Codici restituiti futuri

Valori di futureResult:

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 ancora 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

Nuove enumerazioni

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, 2025-10-30 (Ben King)

    • Bozza iniziale.