XR_ANDROID_geospatial

Строка имени

XR_ANDROID_geospatial

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

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

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

790

Пересмотр

1

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

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

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

XR_EXT_future

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

2025-12-18

Статус IP

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

Авторы

Джон Уллман, Google
Бен Кинг, Google
Нихав Джайн, Google
Джаред Финдер, Google

Обзор

Это расширение обеспечивает геопространственное отслеживание для API Google Geospatial, которое предоставляет точные географические координаты и ориентацию, а также позволяет приложению размещать контент относительно Земли. Для этого используется комбинация отслеживания движения, GPS и других датчиков, а также системы визуального позиционирования Google (VPS). VPS сравнивает изображения с камеры устройства с изображениями Street View, чтобы определить точное местоположение и ориентацию. API Geospatial часто обеспечивает точность позиционирования менее метра (на порядки лучше, чем 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 .

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

Создайте идентификатор геопространственного трекера. 

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

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

Перечисление 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

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

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Геопространственный трекер запущен и пригоден для использования.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

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

Структура 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 — указывает, что элемент позиции содержит допустимые данные.

Тип XrGeospatialPoseFlagsANDROID представляет собой битовую маску типа XrGeospatialPoseFlagBitsANDROID . 

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

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

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

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

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

Функция xrLocateGeospatialPoseFromPoseANDROID преобразует позу в space XrGeospatialPoseFromPoseLocateInfoANDROID :: в геопространственную позу. Если состояние geospatialTracker не равно XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , среда выполнения должна вернуть XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Если функция возвращает XR_SUCCESS , поле XrGeospatialPoseResultANDROID :: poseFlags объекта geospatialPoseResult определяет, какие выходные поля являются допустимыми. Если XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID не установлен в XrGeospatialPoseResultANDROID :: poseFlags , приложение не должно считывать поля XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy или XrGeospatialPoseResultANDROID :: verticalAccuracy в XrGeospatialPoseResultANDROID . Если в XrGeospatialPoseResultANDROID :: poseFlags не установлен параметр XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID , приложение не должно считывать данные из 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% вокруг заданной высоты. Другими словами, существует 68% вероятность того, что истинная высота находится в диапазоне [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • 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 , поле XrSpaceLocation :: locationFlags объекта location определяет, какие выходные поля являются допустимыми.

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

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

Успех

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

VPS недоступен в указанном месте.

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

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

Пример

Настройка геопространственного трекера 

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

Вызов 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.12.2025 (Бен Кинг)

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