XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

Tipo de extensión

Extensión de instancia

Número de extensión registrado

790

Revisión

1

Estado de ratificación

No ratificado

Dependencias de extensiones y versiones

XR_EXT_future

Fecha de la última modificación

2025-12-18

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 el seguimiento geoespacial para la API de Geospatial de Google, que proporciona una ubicación geográfica y una orientación precisas, y permite que la aplicación coloque contenido con respecto a la Tierra. Para ello, utiliza una combinación de seguimiento de movimiento, GPS y otros sensores, y el Sistema de posicionamiento visual (VPS) de Google. El VPS compara las imágenes de la cámara de un dispositivo con las imágenes de Street View para determinar una ubicación y orientación precisas. La API de Geospatial suele proporcionar una precisión de posición inferior a un metro (órdenes de magnitud mejores que el GPS) y una precisión de orientación inferior a un grado.

Para usar correctamente las APIs de esta extensión (además de verificar la compatibilidad con la extensión), la aplicación debe haber configurado correctamente las credenciales de autenticación a través de algún mecanismo, como XR_ANDROID_google_cloud_auth . Consulta la documentación de la extensión de autenticación para obtener más detalles sobre la configuración y los resultados de errores.

Permisos

Las aplicaciones para Android deben tener el permiso android.permission.ACCESS_FINE_LOCATION en su manifiesto para usar esta extensión. El permiso android.permission.ACCESS_FINE_LOCATION se considera peligroso. La aplicación debe solicitar el permiso durante el tiempo de ejecución para usar estas funciones:

(nivel de protección: peligroso)

Inspecciona la capacidad del sistema

La estructura XrSystemGeospatialPropertiesANDROID se define de la siguiente manera:

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

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.
  • supportsGeospatial es un XrBool32 que indica si el sistema actual admite funciones geoespaciales.

Una aplicación puede inspeccionar si el sistema admite funciones geoespaciales encadenando una estructura XrSystemGeospatialPropertiesANDROID a XrSystemProperties cuando se llama a xrGetSystemProperties .

Si un entorno de ejecución devuelve XR_FALSE para supportsGeospatial, el sistema no admite funciones geoespaciales y, por lo tanto, debe devolver XR_ERROR_FEATURE_UNSUPPORTED desde xrCreateGeospatialTrackerANDROID . La aplicación debería evitar el uso de la funcionalidad geoespacial cuando supportsGeospatial sea XR_FALSE .

Uso válido (implícito)

Crea un controlador de Geospatial Tracker

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

Descripciones de los parámetros

Una aplicación puede crear un controlador XrGeospatialTrackerANDROID llamando a xrCreateGeospatialTrackerANDROID . El controlador XrGeospatialTrackerANDROID que se muestra se puede usar posteriormente en llamadas a la API. Si la aplicación no obtuvo los permisos necesarios, el entorno de ejecución debe mostrar XR_ERROR_PERMISSION_INSUFFICIENT . Solo puede existir un XrGeospatialTrackerANDROID a la vez para un XrSession en particular. La aplicación debe asegurarse de que se hayan destruido todos los objetos XrGeospatialTrackerANDROID anteriores antes de volver a llamar a esta función. De lo contrario, el entorno de ejecución debe devolver XR_ERROR_LIMIT_REACHED. Si el rastreador se crea correctamente, ingresará inicialmente al estado XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , y la aplicación debe esperar hasta que el estado cambie a XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID antes de usar el rastreador. Consulta XrEventDataGeospatialTrackerStateChangedANDROID . Si la aplicación pasa un XrGeospatialTrackerANDROID que no está en el estado XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID a una función que lo requiere, el entorno de ejecución debe devolver XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

El controlador XrGeospatialTrackerANDROID debe liberarse con el tiempo a través de la función xrDestroyGeospatialTrackerANDROID.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

typedef struct XrGeospatialTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrGeospatialTrackerCreateInfoANDROID;

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.

Uso válido (implícito)

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Descripciones de los parámetros

Una aplicación puede usar la función xrDestroyGeospatialTrackerANDROID para liberar el rastreador geoespacial y los recursos subyacentes.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a geospatialTracker y a cualquier controlador secundario debe sincronizarse de forma externa.

Códigos de retorno

Listo

  • XR_SUCCESS

Falla

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Estado del rastreador geoespacial

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

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;

La enumeración XrGeospatialTrackerStateANDROID identifica los diferentes estados de un rastreador geoespacial.

Los enumeradores tienen los siguientes valores:

Descripción de enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

El Geospatial Tracker no se está ejecutando.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

El rastreador geoespacial se está ejecutando y se puede usar.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

No se pudo inicializar el Geospatial Tracker y nunca se podrá usar.

La estructura XrEventDataGeospatialTrackerStateChangedANDROID se define de la siguiente manera:

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

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 cuyo estado cambió.
  • state es el nuevo XrGeospatialTrackerStateANDROID .
  • initializationResult es el resultado del error si state es XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID; de lo contrario, es XR_SUCCESS .
  • time es la XrTime en la que se produjo el cambio de estado.

La estructura XrEventDataGeospatialTrackerStateChangedANDROID se envía cuando cambia el estado del rastreador geoespacial. Si la aplicación tiene un XrGeospatialTrackerANDROID válido, debería sondear este evento. El primer evento recibido para un seguimiento tendrá state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Después de un período determinado por el entorno de ejecución, el estado debe cambiar a XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID o XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Esta transición tardará un tiempo arbitrario. Si state cambia a XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID, debe ser el último evento recibido para este seguimiento, y el campo initializationResult contendrá el código de error. Es posible que un error tarde varios segundos en producirse. En este caso, la aplicación debería destruir el seguimiento. Si state cambia a XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , todos los anclajes geoespaciales creados anteriormente deben dejar de seguirse de forma permanente y la aplicación debe destruirlos. El estado puede cambiar de un lado a otro entre XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID y XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID de forma arbitraria muchas veces.

Uso válido (implícito)

Posición geoespacial

La estructura XrGeospatialPoseANDROID se define de la siguiente manera:

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

Descripciones de los miembros

  • eastUpSouthOrientation es un XrQuaternionf que define 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 -90 y +90.
  • longitude es la longitud en grados, entre -180 y +180.
  • altitude es la altitud en metros sobre el elipsoide WGS84.

La estructura XrGeospatialPoseANDROID representa una posición y orientación en relación con la Tierra usando el elipsoide WGS84.

Uso válido (implícito)

  • La extensión XR_ANDROID_geospatial debe estar habilitada antes de usar XrGeospatialPoseANDROID.
  • latitude debe ser un valor de double válido
  • longitude debe ser un valor de double válido
  • altitude debe ser un valor de double válido

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

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

La enumeración XrGeospatialPoseFlagBitsANDROID especifica marcas para las poses geoespaciales.

Los bits de marca tienen los siguientes significados:

Descripciones de las marcas

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID: Indica que el miembro de orientación contiene datos válidos.
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID: Indica que el miembro de posición contiene datos válidos.

El tipo XrGeospatialPoseFlagsANDROID es una máscara de bits de XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Cómo convertir XrPosef en una posición geoespacial

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

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

Descripciones de los parámetros

La función xrLocateGeospatialPoseFromPoseANDROID convierte una pose en XrGeospatialPoseFromPoseLocateInfoANDROID :: space en una pose geoespacial. Si el estado de geospatialTracker no es XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , el entorno de ejecución debe devolver XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Si la función muestra XR_SUCCESS , el campo poseFlags de geospatialPoseResult de XrGeospatialPoseResultANDROID determina qué campos de salida son válidos. Si no se establece XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID en XrGeospatialPoseResultANDROID :: poseFlags , la aplicación no debe leer los campos XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy ni XrGeospatialPoseResultANDROID :: verticalAccuracy en XrGeospatialPoseResultANDROID . Si no se establece XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID en XrGeospatialPoseResultANDROID :: poseFlags , la aplicación no debe leer XrGeospatialPoseANDROID :: eastUpSouthOrientation ni XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Si no se establece XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID, tampoco se debe establecer XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID.

Si la precisión es menor que la esperada, puede ser un indicio de que el dispositivo no está usando la localización del VPS. La aplicación puede indicarle al usuario que apunte su dispositivo a letreros y edificios para mejorar la localización.

Uso válido (implícito)

Códigos de retorno

Listo

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falla

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

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

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.
  • space es el XrSpace en el que se define pose.
  • time es el XrTime en el que se evaluará pose .
  • pose es el XrPosef en space que se convertirá en una pose geoespacial.

Uso válido (implícito)

La estructura XrGeospatialPoseResultANDROID se define de la siguiente manera:

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

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.
  • poseFlags es una máscara de bits de XrGeospatialPoseFlagsANDROID que indica la validez de los componentes de la pose.
  • geospatialPose es el XrGeospatialPoseANDROID resultante.
  • horizontalAccuracy es la precisión horizontal estimada de la posición de la pose geoespacial, definida como el radio en metros del círculo con un nivel de confianza del 68% alrededor de la latitud y la longitud dadas.
  • verticalAccuracy es la precisión vertical estimada de la posición de la pose geoespacial, definida como la distancia en metros del nivel de confianza del 68% alrededor de la altitud dada. En otras palabras, hay un 68% de probabilidades de que la altitud real se encuentre en el rango [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • orientationYawAccuracy es la precisión estimada de la guiñada de la orientación de la pose geoespacial, definida como el radio en grados del nivel de confianza del 68% en torno a la orientación dada.

Uso válido (implícito)

Convierte una posición geoespacial en un XrPosef

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

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

Descripciones de los parámetros

La función xrLocateGeospatialPoseANDROID convierte una pose geoespacial en un XrSpaceLocation . Si XrGeospatialTrackerANDROID no se está ejecutando, el entorno de ejecución debe devolver XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Si la función muestra XR_SUCCESS , el campo locationFlags de location de XrSpaceLocation :: determina qué campos de salida son válidos.

Uso válido (implícito)

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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrGeospatialPoseLocateInfoANDROID se define de la siguiente manera:

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

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.
  • space es el XrSpace en el que se representará la pose resultante.
  • time es el XrTime en el que se ubicará la pose.
  • geospatialPose es el XrGeospatialPoseANDROID que se convertirá.

Uso válido (implícito)

Disponibilidad de VPS

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

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

La enumeración XrVPSAvailabilityANDROID indica la disponibilidad del VPS.

Los enumeradores tienen los siguientes valores:

Descripción de enum

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

El VPS no está disponible cerca de la ubicación proporcionada.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

El VPS está disponible cerca de la ubicación proporcionada.

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

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

Descripciones de los parámetros

  • session es la XrSession que se usará para la verificación.
  • latitude es la latitud en grados.
  • longitude es la longitud en grados.
  • future es un puntero a XrFutureEXT que contendrá el resultado de la operación asíncrona.

La disponibilidad del servicio de posicionamiento visual (VPS) indica si este se puede usar para mejorar la precisión geoespacial en una ubicación determinada.

La función xrCheckVpsAvailabilityAsyncANDROID inicia una verificación asíncrona de la disponibilidad del VPS en una ubicación determinada. La aplicación no necesita un XrGeospatialTrackerANDROID para llamar a esta función y puede usar el resultado de esta operación para decidir si crear uno. Si la aplicación no obtuvo los permisos necesarios, el entorno de ejecución debe mostrar XR_ERROR_PERMISSION_INSUFFICIENT .

Uso válido (implícito)

  • La extensión XR_ANDROID_geospatial debe estar habilitada antes de llamar a xrCheckVpsAvailabilityAsyncANDROID.
  • session debe ser un controlador XrSession válido
  • latitude debe ser un valor de double válido
  • longitude debe ser un valor de double válido
  • 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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

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

Descripciones de los parámetros

Uso válido (implícito)

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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

La estructura XrVPSAvailabilityCheckCompletionANDROID se define de la siguiente manera:

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

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 verificació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.
  • availability es el XrVPSAvailabilityANDROID resultante. La aplicación no debe leer este campo, a menos que futureResult sea 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_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Uso válido (implícito)

Ejemplo

Configura el Geospatial Tracker

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

Llama a las APIs de 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.
}

Nuevos tipos de objetos

Comandos nuevos

Estructuras nuevas

Enums nuevas

Máscaras de bits nuevas

Nuevas constantes de enum

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Extiende XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Extiende XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • Extiende 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

Problemas

Historial de versiones

  • Revisión 1, 18 de diciembre de 2025 (Ben King)

    • Descripción inicial de la extensión.