XR_ANDROID_spatial_anchor_space

Строка имени

XR_ANDROID_spatial_anchor_space

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

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

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

796

Пересмотр

1

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

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

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

XR_EXT_spatial_anchor

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

2025-09-15

Статус IP

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

Авторы

ЮШэн Чанг, Google
Кайл Чен, Google
Левана Чен, Google
Нихав Джайн, Google
Спенсер Куин, 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 , если anchor XrPersistedAnchorSpaceInfoANDROID :: создан с помощью 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 .

Если XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId не является допустимым идентификатором для spatialContext , среда выполнения должна вернуть XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

Если XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId не является допустимым идентификатором сущности для привязки, среда выполнения должна вернуть XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

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

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

Родительским элементом для дескриптора 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 г. (ЮШэн Чанг, Кайл Чен)

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