XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

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

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

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

798

Revision

1

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

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

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

XR_ANDROID_geospatial
и
XR_EXT_future
и
XR_EXT_spatial_entity
и
XR_EXT_spatial_anchor

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

2025-10-30

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

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

Авторы

Джон Ульман (John Ullman), Google
Бен Кинг (Ben King), Google
Нихав Джайн (Nihav Jain), Google
Джаред Финдер (Jared Finder), 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 указывает максимальное количество привязок к поверхности, поддерживаемое средой выполнения. В этом случае лимит должен быть больше нуля.

Если 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_POSE_INVALID
• 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, если XR_SPATIAL_CAPABILITY_ANCHOR_EXT не настроен для spatialContext .

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

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

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

• xrCreateGeospatialAnchorANDROID
• xrCreateSurfaceAnchorAsyncANDROID
• xrCreateSurfaceAnchorCompleteANDROID

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

• XrGeospatialAnchorCreateInfoANDROID
• XrSurfaceAnchorCreateCompletionANDROID
• 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 октября 2025 г. (Бен Кинг)

  • Начальный вариант.