XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Tipo de extensión

Extensión de instancia

Número de extensión registrado

798

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

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 la IP

No hay reclamos de IP conocidos.

Colaboradores

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

Descripción general

Esta extensión proporciona anclas geoespaciales y de superficie que se basan en la extensión geoespacial básica. Las anclas geoespaciales son anclas que se posicionan en el espacio en relación con la Tierra en una latitud, longitud y altitud determinadas. Los Surface Anchors son anclajes relativos a la Tierra que se colocan en una latitud, longitud y altitud dadas en relación con una superficie, según lo que conoce el Servicio de posicionamiento visual. A medida que mejore la precisión de la posición del entorno de ejecución en relación con la Tierra, la pose del ancla se ajustará según corresponda.

Capacidad del sistema para las anclas geoespaciales

La estructura XrSystemGeospatialAnchorPropertiesANDROID se define de la siguiente manera:

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

Descripciones de los miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructuras. No se definen tales estructuras en OpenXR principal ni en esta extensión.
• maxSurfaceAnchorCount es un uint32_t que indica la cantidad máxima de anclajes 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 anclajes de superficie que admite el entorno de ejecución. En este caso, el límite debe ser mayor que 0.

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

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe estar habilitada 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 estructuras

Seguimiento de planos para anclajes

La estructura XrGeospatialTrackerAnchorTrackingInfoANDROID se define de la siguiente manera:

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

Descripciones de los miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
• shouldTrackPlanes es un XrBool32 que indica si el rastreador geoespacial hará un seguimiento de los planos para mejorar el posicionamiento de los anclajes bloqueados en la superficie.

Se puede habilitar el seguimiento de planos para mejorar el posicionamiento de los anclajes fijos en la superficie.

Si la aplicación quiere habilitar el seguimiento de planos para mejorar las poses de los anclajes 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 estar habilitada 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 estructuras

Anclajes geoespaciales

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

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

Descripciones de los 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 entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE .
• createInfo es un puntero a XrGeospatialAnchorCreateInfoANDROID que contiene parámetros de creación de anclajes.
• anchorEntityId es un puntero a XrSpatialEntityIdEXT en el que se devuelve el ID de la entidad de anclaje.

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

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe estar habilitada 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

Falla

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

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

Descripciones de los miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
• 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 estar habilitada 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 estructuras
• geospatialTracker debe ser un controlador XrGeospatialTrackerANDROID válido.
• geospatialPose debe ser una estructura XrGeospatialPoseANDROID válida.

Anclajes de superficie

Los anclajes de superficie son anclajes 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 con la que se relaciona un ancla.

Los enumeradores tienen los siguientes valores:

Descripción de enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Es el tipo de un ancla colocada en relación con el suelo.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Es el tipo de un ancla colocada en relación con la azotea 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 los 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 anclajes.
• 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 los anclajes geoespaciales estándar, el entorno de ejecución puede recuperar datos del terreno para determinar la altitud correcta. El entorno de ejecución debe devolver XR_ERROR_LIMIT_REACHED si la aplicación intenta crear más de XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount anclajes de superficie a la vez. Si el XrGeospatialTrackerANDROID especificado en XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker no está en el estado XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, el entorno de ejecución debe devolver 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 entorno de ejecución debe devolver XR_ERROR_VALIDATION_FAILURE si no se configuró XR_SPATIAL_CAPABILITY_ANCHOR_EXT para spatialContext .

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe estar habilitada 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

Falla

• 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 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 los miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
• geospatialTracker es el XrGeospatialTrackerANDROID que se usará.
• surfaceAnchorType es el XrSurfaceAnchorTypeANDROID del 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 estar habilitada 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 estructuras
• geospatialTracker debe ser un controlador XrGeospatialTrackerANDROID válido.
• surfaceAnchorType debe ser un valor de XrSurfaceAnchorTypeANDROID válido
• latitude debe ser un valor de double válido
• longitude debe ser un valor de double válido
• altitudeRelativeToSurface debe ser un valor de double válido

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

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

Descripciones de los parámetros

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

Uso válido (implícito)

• La extensión XR_ANDROID_geospatial_anchor debe estar habilitada 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

Falla

• 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 la creación de un ancla de superficie asíncrona.

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

Descripciones de los miembros

• type es el XrStructureType de esta estructura.
• next es NULL o un puntero a la siguiente estructura en una cadena de estructuras.
• 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 devolución futuros

Valores de futureResult:

Listo

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Falla

• 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 estar habilitada 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 estructuras
• 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

• Extiende XrGeospatialTrackerCreateInfoANDROID :

  • XrGeospatialTrackerAnchorTrackingInfoANDROID

• Extiende XrSystemProperties :

  • XrSystemGeospatialAnchorPropertiesANDROID

Enums nuevas

• XrSurfaceAnchorTypeANDROID

Nuevas constantes de enum

• XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
• XR_ANDROID_geospatial_anchor_SPEC_VERSION

• Extiende XrResult :

  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID

• Extiende 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, 30 de octubre de 2025 (Ben King)

  • Borrador inicial.