XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

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

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

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

796

Revision

1

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

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

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

XR_EXT_spatial_anchor

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

2025-09-15

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

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

Авторы

YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Обзор

Функция xrCreateSpatialAnchorEXT, определенная в расширении XR_EXT_spatial_anchor, позволяет приложениям создавать пространственные привязки с дескриптором XrSpatialEntityEXT. В отличие от него, это расширение создает пространственный якорь, который представлен дескриптором XrSpace. Это полезно в случаях, когда приложение хочет:

  • Чтобы получить местоположение якоря, используйте xrLocateSpaces.
  • Определите местоположение других пространств относительно якоря.
  • Экспортируйте якорь с помощью XR_ANDROID_anchor_sharing_export .
  • Приложение разместило якоря и теперь использует только их местоположение (чтобы прикреплять виртуальный контент). Другие компоненты объектов, обнаруженных с помощью XrSpatialContextEXT, который использовался для создания якоря, не нужны, поэтому приложение может удалить пространственный контекст.

Якоря, созданные с помощью этого расширения, нельзя сохранить с помощью расширения XR_ANDROID_device_anchor_persistence. Вместо этого приложение должно использовать XR_EXT_spatial_persistence_operations. Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrPersistAnchorANDROID, если XrPersistedAnchorSpaceInfoANDROID :: anchor создается с помощью xrCreateSpatialAnchorSpaceANDROID или xrCreateSpatialAnchorSpaceFromIdANDROID .

Создание XrSpace для пространственного якоря

Создайте пространственный якорь и пространство

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

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

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

Функция xrCreateSpatialAnchorSpaceANDROID создает привязку, которая выводит XrSpatialEntityIdEXT и дескриптор XrSpace. К xrCreateSpatialAnchorSpaceANDROID предъявляются те же требования к проверке, что и к xrCreateSpatialAnchorEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialContextEXT, переданный в xrCreateSpatialAnchorSpaceANDROID, не был настроен с помощью XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

В отношении видимости созданной привязки с помощью xrCreateSpatialAnchorSpaceANDROID применяется последний абзац спецификации xrCreateSpatialAnchorEXT.

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

  • Расширение XR_ANDROID_spatial_anchor_space должно быть включено до вызова xrCreateSpatialAnchorSpaceANDROID.
  • session должен быть действительным дескриптором XrSession.
  • spatialContext должен быть действительным дескриптором XrSpatialContextEXT.
  • createInfo должен быть указателем на действительную структуру XrSpatialAnchorCreateInfoEXT.
  • anchorEntityId должен быть указателем на значение XrSpatialEntityIdEXT.
  • anchorSpace должен быть указателем на дескриптор XrSpace.
  • spatialContext должен быть создан, выделен или получен из session.

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

Выполнено

  • 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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ATTACHABLE_COMPONENT_NOT_FOUND_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Создание XrSpace на основе существующего пространственного якоря

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

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

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

Если объекты пространственных привязок уже существуют (например, из-за сохранения), приложения могут создать XrSpace на основе этих привязок, указав идентификаторы их пространственных объектов.

Функция xrCreateSpatialAnchorSpaceFromIdANDROID создает дескриптор XrSpace, предоставляя XrSpatialEntityIdEXT в поле XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialContextEXT, переданный в xrCreateSpatialAnchorSpaceFromIdANDROID, не был настроен с помощью XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

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

  • Расширение XR_ANDROID_spatial_anchor_space должно быть включено до вызова xrCreateSpatialAnchorSpaceFromIdANDROID.
  • session должен быть действительным дескриптором XrSession.
  • spatialContext должен быть действительным дескриптором XrSpatialContextEXT.
  • createInfo должен быть указателем на действительную структуру XrSpatialAnchorSpaceFromIdCreateInfoANDROID.
  • anchorSpace должен быть указателем на дескриптор XrSpace.
  • spatialContext должен быть создан, выделен или получен из session.

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

Выполнено

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID
  • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

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

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

Среда выполнения должна возвращать XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT, если XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId не является действительным идентификатором для spatialContext .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID, если XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId не является действительным идентификатором объекта для якоря.

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

Жизненный цикл якоря

Родительским элементом дескриптора XrSpace является XrSession . Это означает, что дескриптор XrSpace, представляющий привязку, остается действительным даже после уничтожения xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext или xrCreateSpatialAnchorSpaceANDROID :: spatialContext. Создание XrSpace для представления привязки пространственного объекта позволяет приложению уничтожить XrSpatialContextEXT, настроенный с помощью XR_SPATIAL_CAPABILITY_ANCHOR_EXT, и при этом продолжать получать последнюю позу привязки, используя ее XrSpace с xrLocateSpaces. То есть среда выполнения должна продолжать отслеживать привязку, пока не будут уничтожены все представляющие ее дескрипторы XrSpace.

Пример кода

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

В примере кода ниже показано, как создать пространственный якорь и вернуть его в виде XrSpace .

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

Создать XrSpace на основе идентификатора объекта привязки

В примере кода ниже показано, как создать XrSpace на основе идентификатора существующего объекта привязки.

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

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

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

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

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

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

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

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

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

Проблемы

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

  • Версия 1, 15 сентября 2025 г. (Юйшэн Чан, Кайл Чэнь)

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