XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

Тип расширения

Расширение экземпляра

Зарегистрированный добавочный номер

790

Revision

1

Статус ратификации

Не ратифицировано

Зависимости расширений и версий

XR_EXT_future

Дата последнего изменения

2025-12-18

Статус IP-адреса

Нет известных претензий в отношении интеллектуальной собственности.

Авторы

Джон Ульман (John Ullman), Google
Бен Кинг (Ben King), Google
Нихав Джайн (Nihav Jain), Google
Джаред Финдер (Jared Finder), Google

Обзор

Это расширение обеспечивает геопространственное отслеживание для Geospatial API от Google, который предоставляет точные данные о местоположении и ориентации и позволяет приложению размещать контент относительно Земли. Для этого используются данные GPS, датчиков, системы визуального позиционирования Google и отслеживания движения. VPS сравнивает изображения с камеры устройства с изображениями Просмотра улиц, чтобы определить точное местоположение и ориентацию. Geospatial API часто обеспечивает точность позиционирования менее метра (на порядок лучше, чем GPS) и точность ориентации менее градуса.

Чтобы успешно использовать API в этом расширении (не только для проверки поддержки расширения), приложение должно успешно задать учетные данные для аутентификации с помощью какого-либо механизма, например XR_ANDROID_google_cloud_auth . Дополнительную информацию о настройке и ошибках можно найти в документации по расширению аутентификации.

Разрешения

Чтобы использовать это расширение, в манифесте приложений для Android должно быть указано разрешение android.permission.ACCESS_FINE_LOCATION. Разрешение android.permission.ACCESS_FINE_LOCATION считается опасным. Приложение должно запрашивать разрешение на использование следующих функций:

(уровень защиты: опасный)

Проверка возможностей системы

Структура XrSystemGeospatialPropertiesANDROID определяется следующим образом:

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

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • supportsGeospatial – это XrBool32, указывающий, поддерживает ли текущая система геопространственные функции.

Приложение может проверить, поддерживает ли система геопространственные функции, связав структуру XrSystemGeospatialPropertiesANDROID с XrSystemProperties при вызове xrGetSystemProperties .

Если среда выполнения возвращает XR_FALSE для supportsGeospatial, система не поддерживает геопространственные функции и поэтому должна возвращать XR_ERROR_FEATURE_UNSUPPORTED из xrCreateGeospatialTrackerANDROID . Приложение не должно использовать геопространственные функции, если supportsGeospatial имеет значение XR_FALSE .

Допустимое использование (неявное)

Создайте дескриптор Geospatial Tracker

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

Функция xrCreateGeospatialTrackerANDROID определяется следующим образом:

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

Описание параметров

  • session – это XrSession, в котором будет активен геопространственный трекер.
  • createInfo – указатель на структуру XrGeospatialTrackerCreateInfoANDROID, которая задает начальные параметры геопространственного трекера.
  • geospatialTrackerOutput – указатель на дескриптор, в котором возвращается созданный XrGeospatialTrackerANDROID.

Приложение может создать дескриптор XrGeospatialTrackerANDROID, вызвав xrCreateGeospatialTrackerANDROID . Возвращенный дескриптор XrGeospatialTrackerANDROID можно использовать в последующих вызовах API. Если приложение не получило необходимые разрешения, среда выполнения должна возвращать XR_ERROR_PERMISSION_INSUFFICIENT . Для одного XrSession может существовать только один XrGeospatialTrackerANDROID. Приложение должно убедиться, что все предыдущие объекты XrGeospatialTrackerANDROID были уничтожены, прежде чем снова вызывать эту функцию. В противном случае среда выполнения должна возвращать XR_ERROR_LIMIT_REACHED. Если трекер создан успешно, он сначала перейдет в состояние XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID, и приложение должно дождаться, пока состояние не изменится на XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, прежде чем использовать трекер. См. XrEventDataGeospatialTrackerStateChangedANDROID. Если приложение передает XrGeospatialTrackerANDROID, который не находится в состоянии XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, функции, которой он требуется, среда выполнения должна возвращать XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Дескриптор XrGeospatialTrackerANDROID должен быть в конечном итоге освобожден с помощью функции xrDestroyGeospatialTrackerANDROID.

Допустимое использование (неявное)

Коды возврата

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • 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

Структура XrGeospatialTrackerCreateInfoANDROID определяется следующим образом:

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

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.

Допустимое использование (неявное)

Функция xrDestroyGeospatialTrackerANDROID определяется следующим образом:

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

Описание параметров

Приложение может использовать функцию xrDestroyGeospatialTrackerANDROID, чтобы освободить трекер и связанные с ним ресурсы.

Допустимое использование (неявное)

Потокобезопасность

  • Доступ к geospatialTracker и любым дочерним дескрипторам должен быть синхронизирован извне.

Коды возврата

Выполнено

  • XR_SUCCESS

Сбой

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Состояние геопространственного трекера

Перечисление XrGeospatialTrackerStateANDROID определяется следующим образом:

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;

Перечисление XrGeospatialTrackerStateANDROID определяет различные состояния геопространственного трекера.

Перечисляемые значения:

Описание перечисления

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Geospatial Tracker не запущен.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Геопространственный трекер работает и готов к использованию.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Не удалось инициализировать Geospatial Tracker. Он не будет работать.

Структура XrEventDataGeospatialTrackerStateChangedANDROID определяется следующим образом:

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

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • geospatialTracker – это XrGeospatialTrackerANDROID, состояние которого изменилось.
  • state – это новое значение XrGeospatialTrackerStateANDROID .
  • initializationResult – результат ошибки, если state равно XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID, в противном случае – XR_SUCCESS .
  • time – XrTime, когда произошло изменение состояния.

Структура XrEventDataGeospatialTrackerStateChangedANDROID отправляется при изменении состояния геопространственного трекера. Если у приложения есть действительный XrGeospatialTrackerANDROID , оно должно опрашивать это событие. Первое событие, полученное для трекера, будет иметь state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Через определенное время состояние должно измениться на XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID или XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Этот переход займет произвольное количество времени. Если значение state меняется на XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID, это должно быть последнее событие, полученное для этого трекера, а поле initializationResult будет содержать код ошибки. Ошибка может возникнуть через несколько секунд. В этом случае приложение должно удалить трекер. Если state меняется на XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , все ранее созданные пространственные привязки должны навсегда прекратить отслеживание и должны быть уничтожены приложением. Статус может меняться с XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID на XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID и обратно произвольное количество раз.

Допустимое использование (неявное)

Геопространственная поза

Структура XrGeospatialPoseANDROID определяется следующим образом:

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

Описания участников

  • eastUpSouthOrientation – это XrQuaternionf, определяющий ориентацию относительно системы координат, где +X – восток, +Y – вверх, а +Z – юг.
  • latitude – широта в градусах (от -90 до +90).
  • longitude – долгота в градусах (от -180 до +180).
  • altitude – высота в метрах над эллипсоидом WGS84.

Структура XrGeospatialPoseANDROID представляет положение и ориентацию относительно Земли с использованием эллипсоида WGS84.

Допустимое использование (неявное)

  • Расширение XR_ANDROID_geospatial должно быть включено до использования XrGeospatialPoseANDROID.
  • latitude должно быть действительным значением double.
  • longitude должно быть действительным значением double.
  • altitude должно быть действительным значением double.

Перечисление XrGeospatialPoseFlagBitsANDROID определяется следующим образом:

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

Перечисление XrGeospatialPoseFlagBitsANDROID задает флаги для геопространственных поз.

Биты флага имеют следующие значения:

Описания флагов

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID – указывает, что элемент ориентации содержит действительные данные.
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID – указывает, что элемент position содержит действительные данные.

Тип XrGeospatialPoseFlagsANDROID – это битовая маска XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Преобразование XrPosef в геопространственную позу

Функция xrLocateGeospatialPoseFromPoseANDROID определяется следующим образом:

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

Описание параметров

Функция xrLocateGeospatialPoseFromPoseANDROID преобразует позу в XrGeospatialPoseFromPoseLocateInfoANDROID :: space в геопространственную позу. Если состояние geospatialTracker не равно XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , среда выполнения должна возвращать XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Если функция возвращает XR_SUCCESS, поле poseFlags в XrGeospatialPoseResultANDROID (geospatialPoseResult) определяет, какие выходные поля действительны. Если XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID не задано в XrGeospatialPoseResultANDROID :: poseFlags , приложение не должно считывать поля XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy или XrGeospatialPoseResultANDROID :: verticalAccuracy в XrGeospatialPoseResultANDROID . Если XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID не задано в XrGeospatialPoseResultANDROID :: poseFlags , приложение не должно считывать XrGeospatialPoseANDROID :: eastUpSouthOrientation или XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Если не задано значение XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID, то значение XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID также не должно быть задано.

Если точность ниже ожидаемой, это может означать, что устройство не использует VPS. Приложение может попросить пользователя направить устройство на вывески и здания, чтобы улучшить определение местоположения.

Допустимое использование (неявное)

Коды возврата

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • 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

Структура XrGeospatialPoseFromPoseLocateInfoANDROID определяется следующим образом:

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

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • space – это XrSpace, в котором определен pose.
  • time – XrTime, для которого вычисляется pose .
  • pose – XrPosef в space, который нужно преобразовать в геопространственную позу.

Допустимое использование (неявное)

Структура XrGeospatialPoseResultANDROID определяется следующим образом:

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

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • poseFlags – битовая маска XrGeospatialPoseFlagsANDROID, указывающая на действительность компонентов позы.
  • geospatialPose – это результирующий объект XrGeospatialPoseANDROID .
  • horizontalAccuracy – расчетная точность по горизонтали для геопространственной позы, определяемая как радиус в метрах круга с уровнем достоверности 68% вокруг заданной широты и долготы.
  • verticalAccuracy – расчетная точность по вертикали для пространственного положения, определяемая как расстояние в метрах с уровнем достоверности 68% вокруг заданной высоты. Другими словами, вероятность того, что истинная высота находится в диапазоне [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ], составляет 68 %.
  • orientationYawAccuracy – расчетная точность рыскания для ориентации пространственной позы, определяемая как радиус в градусах с уровнем достоверности 68% вокруг заданной ориентации.

Допустимое использование (неявное)

Преобразование геопространственной позы в XrPosef

Функция xrLocateGeospatialPoseANDROID определяется следующим образом:

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

Описание параметров

  • geospatialTracker – XrGeospatialTrackerANDROID, который будет использоваться для преобразования.
  • locateInfo – указатель на XrGeospatialPoseLocateInfoANDROID, содержащий параметры запроса.
  • location – указатель на XrSpaceLocation, который получает результирующую позу.

Функция xrLocateGeospatialPoseANDROID преобразует геопространственную позу в XrSpaceLocation . Если XrGeospatialTrackerANDROID не запущен, среда выполнения должна возвращать XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Если функция возвращает XR_SUCCESS, поле locationFlags структуры location XrSpaceLocation определяет, какие выходные поля являются допустимыми.

Допустимое использование (неявное)

Коды возврата

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • 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

Структура XrGeospatialPoseLocateInfoANDROID определяется следующим образом:

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

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • space – это XrSpace, в котором будет представлена результирующая поза.
  • time – это объект XrTime, в котором нужно разместить позу.
  • geospatialPose – объект XrGeospatialPoseANDROID, который нужно преобразовать.

Допустимое использование (неявное)

Доступность VPS

Перечисление XrVPSAvailabilityANDROID определяется следующим образом:

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

Перечисление XrVPSAvailabilityANDROID указывает на доступность VPS.

Перечисляемые значения:

Описание перечисления

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

Система визуального позиционирования недоступна рядом с указанным местоположением.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

VPS доступна рядом с указанным местоположением.

Функция xrCheckVpsAvailabilityAsyncANDROID определяется следующим образом:

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

Описание параметров

  • session – это XrSession, который будет использоваться для проверки.
  • latitude – широта в градусах.
  • longitude – долгота в градусах.
  • future – указатель на XrFutureEXT, который будет содержать результат асинхронной операции.

Доступность сервиса визуального позиционирования (VPS) указывает, можно ли использовать VPS для повышения точности геопространственных данных в определенном местоположении.

Функция xrCheckVpsAvailabilityAsyncANDROID запускает асинхронную проверку доступности VPS в заданном местоположении. Для вызова этой функции приложению не требуется XrGeospatialTrackerANDROID, и оно может использовать результат этой операции, чтобы решить, создавать ли его. Если приложение не получило необходимые разрешения, среда выполнения должна возвращать XR_ERROR_PERMISSION_INSUFFICIENT .

Допустимое использование (неявное)

  • Расширение XR_ANDROID_geospatial должно быть включено до вызова xrCheckVpsAvailabilityAsyncANDROID.
  • session должен быть действительным дескриптором XrSession.
  • latitude должно быть действительным значением double.
  • longitude должно быть действительным значением double.
  • future должен быть указателем на значение XrFutureEXT.

Коды возврата

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • 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

Функция xrCheckVpsAvailabilityCompleteANDROID определяется следующим образом:

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

Описание параметров

Допустимое использование (неявное)

Коды возврата

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • 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

Структура XrVPSAvailabilityCheckCompletionANDROID определяется следующим образом:

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

Описания участников

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • futureResult – это XrResult операции проверки. Если futureResult – это XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , то структура в цепочке next может предоставить больше информации о сбое.
  • availability – это результирующий объект XrVPSAvailabilityANDROID . Приложение не должно считывать это поле, если futureResult не равно XR_SUCCESS .

Коды возврата в будущем

Значения в поле "futureResult":

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

Допустимое использование (неявное)

Пример

Настройка 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;
      }
  }
}

Вызов Geospatial Pose API

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

Новые типы объектов

Новые команды

Новые структуры

Новые перечисления

Новые битовые маски

Новые константы перечисления

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Расширение XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Расширение XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • Расширение 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

Проблемы

История версий

  • Версия 1, 18 декабря 2025 г. (Бен Кинг)

    • Начальное описание расширения.