XR_ANDROID_geospatial_anchor

Cadena de nombre

XR_ANDROID_geospatial_anchor

Tipo de extensión

Extensión de instancia

Número de extensión registrada

798

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensión y versión

XR_ANDROID_geospatial
y
XR_EXT_future
y
XR_EXT_spatial_entity
y
XR_EXT_spatial_anchor

Fecha de la última modificación

2025-10-30

Estado de IP

No se conocen reclamos de IP.

Colaboradores

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

Descripción general

Esta extensión proporciona anclas geoespaciales y anclas de superficie que se basan en la extensión geoespacial base. Las anclas geoespaciales son anclas que se posicionan en el espacio en relación con la Tierra en una latitud, longitud y altitud determinadas. Las anclas de superficie son anclas relativas a la Tierra que se colocan en una latitud, longitud y altitud determinadas en relación con una superficie, según lo conoce el Servicio de posicionamiento visual. A medida que mejora la precisión del tiempo de ejecución de su posición en relación con la Tierra, la pose del ancla se ajustará en consecuencia.

Capacidad del sistema para anclas geoespaciales

La estructura XrSystemGeospatialAnchorPropertiesANDROID se define de la siguiente manera:

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

Descripciones de miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructura. No se definen esas estructuras en OpenXR principal ni en esta extensión.
• maxSurfaceAnchorCount es un uint32_t que indica la cantidad máxima de anclas de superficie que se pueden crear.

Una aplicación puede inspeccionar las capacidades de anclaje geoespacial del sistema encadenando una estructura XrSystemGeospatialAnchorPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties .

Si XrSystemGeospatialPropertiesANDROID :: supportsGeospatial es XR_TRUE , entonces maxSurfaceAnchorCount indica la cantidad máxima de anclas de superficie que admite el tiempo de ejecución. En este caso, el límite debe ser mayor que 0.

Si XrSystemGeospatialPropertiesANDROID :: supportsGeospatial no es XR_TRUE , entonces maxSurfaceAnchorCount debe ser 0.

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe habilitarse antes de usar XrSystemGeospatialAnchorPropertiesANDROID.
• type debe ser XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID
• next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructura

Seguimiento de planos para anclas

La estructura XrGeospatialTrackerAnchorTrackingInfoANDROID se define de la siguiente manera:

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

Descripciones de miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructura.
• shouldTrackPlanes es un XrBool32 que indica si el rastreador geoespacial rastreará planos para mejorar el posicionamiento de las anclas bloqueadas en la superficie.

Se puede habilitar el seguimiento de planos para mejorar el posicionamiento de las anclas bloqueadas en la superficie.

Si la aplicación quiere habilitar el seguimiento de planos para mejorar las poses de anclaje de superficie, puede encadenar una estructura XrGeospatialTrackerAnchorTrackingInfoANDROID a XrGeospatialTrackerCreateInfoANDROID cuando se llama a xrCreateGeospatialTrackerANDROID .

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe habilitarse antes de usar XrGeospatialTrackerAnchorTrackingInfoANDROID
• type debe ser XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
• next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructura

Anclas geoespaciales

La función xrCreateGeospatialAnchorANDROID se define de la siguiente manera:

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

Descripciones de parámetros

• spatialContext es el XrSpatialContextEXT en el que se creará el ancla. El contexto debe configurarse para XR_SPATIAL_CAPABILITY_ANCHOR_EXT. De lo contrario, el tiempo de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE.
• createInfo es un puntero a XrGeospatialAnchorCreateInfoANDROID que contiene parámetros de creación de anclas.
• anchorEntityId es un puntero a XrSpatialEntityIdEXT en el que se devuelve el ID de la entidad de ancla.

Si el XrGeospatialTrackerANDROID especificado en XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker no está en el estado XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, el tiempo de ejecución debe mostrar XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe habilitarse antes de llamar a xrCreateGeospatialAnchorANDROID.
• spatialContext debe ser un controlador XrSpatialContextEXT válido.
• createInfo debe ser un puntero a una estructura XrGeospatialAnchorCreateInfoANDROID válida.
• anchorEntityId debe ser un puntero a un valor XrSpatialEntityIdEXT.

Códigos de retorno

Listo

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errores

• 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 estructura XrGeospatialAnchorCreateInfoANDROID se define de la siguiente manera:

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

Descripciones de miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructura.
• geospatialTracker es el XrGeospatialTrackerANDROID que se usará para crear el ancla.
• geospatialPose es un puntero a XrGeospatialPoseANDROID que define la ubicación y la orientación del ancla.

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe habilitarse antes de usar XrGeospatialAnchorCreateInfoANDROID.
• type debe ser XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
• next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructura
• geospatialTracker debe ser un controlador XrGeospatialTrackerANDROID válido.
• geospatialPose debe ser una estructura XrGeospatialPoseANDROID válida.

Anclas de superficie

Las anclas de superficie son anclas que se colocan en relación con una superficie, como el terreno o los techos.

La enumeración XrSurfaceAnchorTypeANDROID se define de la siguiente manera:

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;

La enumeración XrSurfaceAnchorTypeANDROID especifica el tipo de superficie en relación con la que se encuentra un ancla.

Los enumeradores tienen los siguientes valores:

Descripción de enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Tipo de ancla colocada en relación con el suelo.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Tipo de ancla colocada en relación con el techo o el suelo donde no hay un edificio.

La función xrCreateSurfaceAnchorAsyncANDROID se define de la siguiente manera:

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

Descripciones de parámetros

• spatialContext es el XrSpatialContextEXT en el que se creará el ancla.
• createInfo es un puntero a XrSurfaceAnchorCreateInfoANDROID que contiene parámetros de creación de anclas.
• future es un puntero a XrFutureEXT que contendrá el resultado de la operación asíncrona.

La función xrCreateSurfaceAnchorAsyncANDROID inicia una operación asíncrona para crear un ancla de superficie. A diferencia de las anclas geoespaciales estándar, el tiempo de ejecución puede recuperar datos de terreno para determinar la altitud correcta. El tiempo de ejecución debe mostrar XR_ERROR_LIMIT_REACHED si la aplicación intenta crear más de XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount anclas de superficie a la vez. Si el XrGeospatialTrackerANDROID especificado en XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker no está en el estado XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, el tiempo de ejecución debe mostrar XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . La operación puede fallar de forma asíncrona con el resultado XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID si no hay datos de superficie para la ubicación determinada. El tiempo de ejecución debe mostrar XR_ERROR_VALIDATION_FAILURE si XR_SPATIAL_CAPABILITY_ANCHOR_EXT no se configuró para spatialContext .

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe habilitarse antes de llamar a xrCreateSurfaceAnchorAsyncANDROID
• spatialContext debe ser un controlador XrSpatialContextEXT válido.
• createInfo debe ser un puntero a una estructura XrSurfaceAnchorCreateInfoANDROID válida.
• future debe ser un puntero a un valor XrFutureEXT.

Códigos de retorno

Listo

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errores

• 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 estructura XrSurfaceAnchorCreateInfoANDROID se define de la siguiente manera:

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

Descripciones de miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructura.
• geospatialTracker es el XrGeospatialTrackerANDROID que se usará.
• surfaceAnchorType es el XrSurfaceAnchorTypeANDROID para el ancla.
• eastUpSouthOrientation es la orientación con respecto a un sistema de coordenadas en el que +X=Este, +Y=Arriba y +Z=Sur.
• latitude es la latitud en grados, entre -89.9 y +89.9.
• longitude es la longitud en grados, entre -180 y +180.
• altitudeRelativeToSurface es la altitud en metros en relación con la superficie especificada por surfaceAnchorType .

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe habilitarse antes de usar XrSurfaceAnchorCreateInfoANDROID
• type debe ser XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
• next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructura
• geospatialTracker debe ser un controlador XrGeospatialTrackerANDROID válido.
• surfaceAnchorType debe ser un valor XrSurfaceAnchorTypeANDROID válido.
• latitude debe ser un valor double válido.
• longitude debe ser un valor double válido.
• altitudeRelativeToSurface debe ser un valor double válido.

La función xrCreateSurfaceAnchorCompleteANDROID se define de la siguiente manera:

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

Descripciones de parámetros

• spatialContext es el XrSpatialContextEXT que se usa para la creación.
• future es el XrFutureEXT que muestra xrCreateSurfaceAnchorAsyncANDROID .
• completion es un puntero a XrSurfaceAnchorCreateCompletionANDROID que recibe el resultado.

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe habilitarse antes de llamar a xrCreateSurfaceAnchorCompleteANDROID.
• spatialContext debe ser un controlador XrSpatialContextEXT válido.
• completion debe ser un puntero a una estructura XrSurfaceAnchorCreateCompletionANDROID.

Códigos de retorno

Listo

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errores

• 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 estructura XrSurfaceAnchorCreateCompletionANDROID contiene el resultado de una creación de ancla de superficie asíncrona.

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

Descripciones de miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructura.
• futureResult es el XrResult de la operación de creación. Si futureResult es XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , una estructura en la cadena next puede proporcionar más información sobre la falla.
• anchorEntityId es el XrSpatialEntityIdEXT del ancla creada o XR_NULL_SPATIAL_ENTITY_ID_EXT si futureResult no es XR_SUCCESS .

Códigos de retorno futuros

Valores de futureResult:

Listo

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Errores

• 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

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe habilitarse antes de usar XrSurfaceAnchorCreateCompletionANDROID
• type debe ser XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
• next debe ser NULL o un puntero válido a la siguiente estructura en una cadena de estructura
• futureResult debe ser un valor XrResult válido.

Ejemplo

Crea un ancla de 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.
}

Comandos nuevos

• xrCreateGeospatialAnchorANDROID
• xrCreateSurfaceAnchorAsyncANDROID
• xrCreateSurfaceAnchorCompleteANDROID

Estructuras nuevas

• XrGeospatialAnchorCreateInfoANDROID
• XrSurfaceAnchorCreateCompletionANDROID
• XrSurfaceAnchorCreateInfoANDROID

• Extensión de XrGeospatialTrackerCreateInfoANDROID :

  • XrGeospatialTrackerAnchorTrackingInfoANDROID

• Extensión de XrSystemProperties :

  • XrSystemGeospatialAnchorPropertiesANDROID

Enums nuevas

• XrSurfaceAnchorTypeANDROID

Constantes de enum nuevas

• XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
• XR_ANDROID_geospatial_anchor_SPEC_VERSION

• Extensión de XrResult :

  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

• Extensión de 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

Problemas

Historial de versiones

• Revisión 1, 2025-10-30 (Ben King)

  • Borrador inicial.