Android XR for OpenXR | Android Developers

Android XR SDK достиг версии Developer Preview 3 , и нам важно ваше мнение! Попробуйте и посетите нашу страницу поддержки , чтобы связаться с нами.

Эта страница переведена с помощью Cloud Translation API.

XR_ANDROID_geospatial_anchor

Строка имени

XR_ANDROID_geospatial_anchor

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

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

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

798

Пересмотр

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

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

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

XR_ANDROID_geospatial
и
XR_EXT_future
и
XR_EXT_spatial_entity
и
XR_EXT_spatial_anchor

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

2025-10-30

Статус IP

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

Авторы

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

Обзор

Это расширение предоставляет геопространственные и поверхностные якоря, которые дополняют базовое расширение Geospatial. Геопространственные якоря — это якоря, которые располагаются в пространстве относительно Земли на заданных широте, долготе и высоте. Поверхностные якоря — это якоря, расположенные относительно Земли на заданных широте, долготе и высоте относительно поверхности, известной службе визуального позиционирования. По мере повышения точности определения положения якоря относительно Земли в процессе выполнения, его положение будет соответствующим образом корректироваться.

Возможности системы для геопространственных якорей

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

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

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

type — это XrStructureType данной структуры.
next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
maxSurfaceAnchorCount — это тип uint32_t , указывающий максимальное количество поверхностных якорей, которые можно создать.

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

Если XrSystemGeospatialPropertiesANDROID :: supportsGeospatial равно XR_TRUE , то maxSurfaceAnchorCount указывает максимальное количество поверхностных якорей, поддерживаемых средой выполнения. В этом случае лимит должен быть больше 0.

Если XrSystemGeospatialPropertiesANDROID :: supportsGeospatial не равно XR_TRUE , то maxSurfaceAnchorCount должно быть равно 0.

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

Расширение XR_ANDROID_geospatial_anchor необходимо включить перед использованием XrSystemGeospatialAnchorPropertiesANDROID.
type должен быть XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID
next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.

Отслеживание плоскости для якорей

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

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

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

type — это XrStructureType данной структуры.
next — это NULL или указатель на следующую структуру в цепочке структур.
shouldTrackPlanes — это тип данных XrBool32 указывающий, будет ли геопространственный трекер отслеживать плоскости для улучшения позиционирования опорных точек, зафиксированных на поверхности.

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

Если приложение хочет включить отслеживание плоскости для улучшения позиционирования привязки к поверхности, оно может связать структуру XrGeospatialTrackerAnchorTrackingInfoANDROID со структурой XrGeospatialTrackerCreateInfoANDROID при вызове функции xrCreateGeospatialTrackerANDROID .

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

Расширение XR_ANDROID_geospatial_anchor необходимо включить перед использованием XrGeospatialTrackerAnchorTrackingInfoANDROID.
type должен быть XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.

Геопространственные якоря

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

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

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

spatialContext — это XrSpatialContextEXT , в котором создается якорь. Контекст должен быть настроен для XR_SPATIAL_CAPABILITY_ANCHOR_EXT , в противном случае среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE .
createInfo — это указатель на XrGeospatialAnchorCreateInfoANDROID , содержащий параметры создания якоря.
anchorEntityId — это указатель на XrSpatialEntityIdEXT , в котором возвращается идентификатор якорной сущности.

Если объект XrGeospatialTrackerANDROID, указанный в XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker , не находится в состоянии XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , среда выполнения должна вернуть XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

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

Расширение XR_ANDROID_geospatial_anchor необходимо включить перед вызовом функции xrCreateGeospatialAnchorANDROID.
spatialContext должен быть допустимым дескриптором XrSpatialContextEXT.
createInfo должна быть указателем на допустимую структуру XrGeospatialAnchorCreateInfoANDROID.
anchorEntityId должен быть указателем на значение XrSpatialEntityIdEXT

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

Успех

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_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

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

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

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

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

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

Расширение XR_ANDROID_geospatial_anchor необходимо включить перед использованием функции XrGeospatialAnchorCreateInfoANDROID.
type должен быть XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
geospatialTracker должен быть допустимым дескриптором XrGeospatialTrackerANDROID.
geospatialPose должен быть допустимой структурой XrGeospatialPoseANDROID.

Поверхностные анкеры

Поверхностные анкеры — это анкеры, размещаемые относительно поверхности, например, рельефа местности или крыш.

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

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

Перечисление XrSurfaceAnchorTypeANDROID указывает тип поверхности, относительно которой находится якорь.

Перечисляемые элементы имеют следующие значения:

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

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Тип анкера, устанавливаемого относительно земли.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Тип анкера, устанавливаемого относительно крыши или земли в местах, где нет зданий.

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

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

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

spatialContext — это объект XrSpatialContextEXT , в котором создается якорь.
createInfo — это указатель на XrSurfaceAnchorCreateInfoANDROID , содержащий параметры создания якоря.
future — это указатель на XrFutureEXT , который будет содержать результат асинхронной операции.

Функция xrCreateSurfaceAnchorAsyncANDROID запускает асинхронную операцию для создания привязки поверхности. В отличие от стандартных геопространственных привязок, среда выполнения может получать данные о рельефе местности для определения правильной высоты. Среда выполнения должна вернуть XR_ERROR_LIMIT_REACHED если приложение пытается создать более XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount привязок поверхности одновременно. Если XrGeospatialTrackerANDROID, указанный в XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker , не находится в состоянии XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , среда выполнения должна вернуть XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Операция может завершиться асинхронно с ошибкой XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID если для заданного местоположения отсутствуют данные о поверхности. Среда выполнения должна вернуть XR_ERROR_VALIDATION_FAILURE если для spatialContext не был настроен параметр XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

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

Расширение XR_ANDROID_geospatial_anchor необходимо включить перед вызовом функции xrCreateSurfaceAnchorAsyncANDROID.
spatialContext должен быть допустимым дескриптором XrSpatialContextEXT.
createInfo должна быть указателем на допустимую структуру XrSurfaceAnchorCreateInfoANDROID.
future должен быть указателем на значение XrFutureEXT

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

Успех

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_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

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

type — это XrStructureType данной структуры.
next — это NULL или указатель на следующую структуру в цепочке структур.
geospatialTracker — это XrGeospatialTrackerANDROID, который следует использовать.
surfaceAnchorType — это XrSurfaceAnchorTypeANDROID, обозначающий якорь.
eastUpSouthOrientation — это ориентация относительно системы координат, где +X = Восток, +Y = Вверх и +Z = Юг.
latitude — это широта в градусах, находящаяся в диапазоне от -89,9 до +89,9.
longitude — это долгота в градусах, в диапазоне от -180 до +180.
altitudeRelativeToSurface — это высота в метрах относительно поверхности, указанной параметром surfaceAnchorType .

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

Расширение XR_ANDROID_geospatial_anchor необходимо включить перед использованием XrSurfaceAnchorCreateInfoANDROID.
type должен быть XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
geospatialTracker должен быть допустимым дескриптором XrGeospatialTrackerANDROID.
surfaceAnchorType должен быть допустимым значением XrSurfaceAnchorTypeANDROID.
latitude должна быть допустимым значением double
longitude должно быть допустимым значением double
altitudeRelativeToSurface должно быть допустимым значением double

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

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

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

spatialContext — это объект XrSpatialContextEXT, используемый для создания.
future — это объект XrFutureEXT , возвращаемый функцией `xrCreateSurfaceAnchorAsyncANDROID` .
completion — это указатель на XrSurfaceAnchorCreateCompletionANDROID , который получает результат.

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

Расширение XR_ANDROID_geospatial_anchor необходимо включить перед вызовом функции xrCreateSurfaceAnchorCompleteANDROID.
spatialContext должен быть допустимым дескриптором XrSpatialContextEXT.
completion должна быть указателем на структуру XrSurfaceAnchorCreateCompletionANDROID.

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

Успех

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_LIMIT_REACHED
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_SESSION_LOST
XR_ERROR_VALIDATION_FAILURE

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

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

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

type — это XrStructureType данной структуры.
next — это NULL или указатель на следующую структуру в цепочке структур.
futureResult — это XrResult операции создания. Если futureResult равен XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , структура в next цепочке может предоставить дополнительную информацию о сбое.
anchorEntityId — это XrSpatialEntityIdEXT созданного якоря, или XR_NULL_SPATIAL_ENTITY_ID_EXT, если futureResult не равен XR_SUCCESS .

Будущие коды возврата

Значения futureResult :

Успех

XR_SUCCESS
XR_SESSION_LOSS_PENDING

Отказ

XR_ERROR_RUNTIME_FAILURE
XR_ERROR_INSTANCE_LOST
XR_ERROR_SESSION_LOST
XR_ERROR_OUT_OF_MEMORY
XR_ERROR_LIMIT_REACHED
XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

Расширение XR_ANDROID_geospatial_anchor необходимо включить перед использованием XrSurfaceAnchorCreateCompletionANDROID.
type должен быть XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
next должно быть NULL или допустимым указателем на следующую структуру в цепочке структур.
futureResult должно быть допустимым значением XrResult.

Пример

Создать якорь местности

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  XrSpatialCapabilityConfigurationAnchorEXT
       anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

  XrCreateSpatialContextCompletionEXT contextCompletion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &contextCompletion));
  if (contextCompletion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

XrFuturePollInfoEXT anchorPollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT anchorPollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
anchorPollInfo.future = anchorFuture;
anchorPollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (anchorPollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &anchorPollInfo, &anchorPollResult));
}

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

Новые сооружения

XrGeospatialAnchorCreateInfoANDROID
XrSurfaceAnchorCreateCompleteANDROID
XrSurfaceAnchorCreateInfoANDROID
Расширение XrGeospatialTrackerCreateInfoANDROID :
- XrGeospatialTrackerAnchorTrackingInfoANDROID
Расширение XrSystemProperties :
- XrSystemGeospatialAnchorPropertiesANDROID

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

XrSurfaceAnchorTypeANDROID

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

XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
XR_ANDROID_geospatial_anchor_SPEC_VERSION
Расширение XrResult :
- XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
Расширение XrStructureType :
- XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
- XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
- XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
- XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
- XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Проблемы

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

Редакция 1, 30.10.2025 (Бен Кинг)
- Первоначальный вариант.