XR_ANDROID_geospatial

Cadena de nombre

XR_ANDROID_geospatial

Tipo de extensión

Extensión de la instancia

Número de extensión registrado

790

Revisión

1

Estado de ratificación

No se ratificó

Dependencias de extensiones y versiones

XR_EXT_future

Fecha de la última modificación

2025-12-18

Estado de la IP

No hay reclamos conocidos por IP.

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, usa 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 posicional inferior a un metro (órdenes de magnitud mejor que el GPS) y una precisión de orientación inferior a un grado.

Para usar correctamente las APIs de esta extensión (excepto para verificar la compatibilidad con la extensión), la aplicación debe haber establecido 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 un permiso 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 tiempo 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 debe evitar usar la funcionalidad geoespacial cuando supportsGeospatial es XR_FALSE .

Uso válido (implícito)

Crea un identificador 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 devuelve se puede usar posteriormente en las llamadas a la API. Si la aplicación no obtuvo los permisos necesarios, el tiempo de ejecución debe devolver 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 tiempo de ejecución debe devolver XR_ERROR_LIMIT_REACHED. Si el objeto de seguimiento se crea correctamente, inicialmente entrará en el estado XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , y la aplicación debe esperar a que el estado cambie a XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID antes de usar el objeto de seguimiento. 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 tiempo de ejecución debe devolver XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

El identificador XrGeospatialTrackerANDROID debe liberarse eventualmente 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 objeto de seguimiento geoespacial y los recursos subyacentes.

Uso válido (implícito)

Seguridad de subprocesos

  • El acceso a geospatialTracker y a cualquier identificador 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

Estado del dispositivo de rastreo 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 objeto de seguimiento de la ubicación geográfica.

Los enumerantes tienen los siguientes valores:

Descripción de la enumeración

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

El rastreador geoespacial 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 de error si state es XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID; de lo contrario , es XR_SUCCESS .
  • time es el XrTime en el que se produjo el cambio de estado.

La estructura XrEventDataGeospatialTrackerStateChangedANDROID se envía cuando cambia el estado del objeto de seguimiento geoespacial. Si la aplicación tiene un objeto XrGeospatialTrackerANDROID válido , debe sondear este evento. El primer evento recibido para un objeto de seguimiento tendrá state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Después de un período determinado en el tiempo 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á una cantidad de tiempo arbitraria. Si state cambia a XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , debe ser el último evento recibido para este objeto de seguimiento, y el campo initializationResult contendrá el código de error. Es posible que el error tarde varios segundos en producirse. En este caso, la aplicación debe destruir el objeto de seguimiento. Si state cambia a XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , todas las anclas geoespaciales creadas anteriormente deben dejar de realizar el seguimiento de forma permanente y la aplicación debe destruirlas. El estado puede cambiar de XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID a XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID y viceversa una cantidad arbitraria de veces.

Uso válido (implícito)

Geospatial Pose

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 una orientación relativas a la Tierra con el elipsoide WGS84.

Uso válido (implícito)

  • La extensión XR_ANDROID_geospatial debe habilitarse antes de usar XrGeospatialPoseANDROID
  • latitude debe ser un valor double válido
  • longitude debe ser un valor double válido
  • altitude debe ser un valor 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 la 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 Geospatial Pose

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 posición en XrGeospatialPoseFromPoseLocateInfoANDROID :: space en una posición geoespacial. Si el estado de geospatialTracker no es XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , el tiempo de ejecución debe devolver XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Si la función devuelve XR_SUCCESS , el campo poseFlags de XrGeospatialPoseResultANDROID :: geospatialPoseResult determina qué campos de salida son válidos. Si XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID no está configurado en XrGeospatialPoseResultANDROID :: poseFlags , la aplicación no debe leer los campos XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy o XrGeospatialPoseResultANDROID :: verticalAccuracy en XrGeospatialPoseResultANDROID . Si XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID no está configurado en XrGeospatialPoseResultANDROID :: poseFlags , la aplicación no debe leer XrGeospatialPoseANDROID :: eastUpSouthOrientation ni XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Si no se configura XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID, tampoco se debe configurar XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID.

Si la precisión es menor de lo esperado, puede ser un indicador de que el dispositivo no está utilizando la localización del VPS. La aplicación puede indicarle al usuario que apunte su dispositivo hacia señales 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 debe evaluar pose .
  • pose es el XrPosef en space que se convertirá en una posición 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 postura.
  • geospatialPose es el XrGeospatialPoseANDROID resultante .
  • horizontalAccuracy es la precisión horizontal estimada de la posición de la orientación geoespacial, definida como el radio en metros del círculo con un nivel de confianza del 68% alrededor de la latitud y la longitud proporcionadas.
  • verticalAccuracy es la precisión vertical estimada de la posición de la postura geoespacial, definida como la distancia en metros del nivel de confianza del 68% alrededor de la altitud determinada. 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 orientación de la posición geoespacial, definida como el radio en grados del nivel de confianza del 68% alrededor de la orientación determinada.

Uso válido (implícito)

Cómo convertir 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 posición geoespacial en un XrSpaceLocation . Si XrGeospatialTrackerANDROID no se está ejecutando, el tiempo de ejecución debe devolver XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Si la función devuelve XR_SUCCESS , el campo locationFlags de XrSpaceLocation :: location 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_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 postura resultante.
  • time es el XrTime en el que se ubicará la postura.
  • 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 enumerantes tienen los siguientes valores:

Descripción de la enumeración

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 el 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 el VPS se puede usar para mejorar la exactitud 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 crea uno. Si la aplicación no obtuvo los permisos necesarios, el tiempo de ejecución debe devolver XR_ERROR_PERMISSION_INSUFFICIENT .

Uso válido (implícito)

  • La extensión XR_ANDROID_geospatial debe habilitarse antes de llamar a xrCheckVpsAvailabilityAsyncANDROID
  • session debe ser un identificador de XrSession válido
  • latitude debe ser un valor double válido
  • longitude debe ser un valor 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 , es posible que una estructura en la cadena next proporcione 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 monitor geoespacial

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

Nuevas estructuras

Nuevas enumeraciones

Nuevas máscaras de bits

Nuevas constantes de enumeración

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Extensión de XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Extensión de XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • Extensión de 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, 2025-12-18 (Ben King)

    • Es la descripción inicial de la extensión.