XR_EXT_spatial_container

Name String

XR_EXT_spatial_container

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

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

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

811

Revision

1

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

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

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

OpenXR 1.0

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

2026-08-06

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

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

Авторы

Джаред Финдер (Jared Finder), Google
Андреас Лёве Сельвик (Andreas Loeve Selvik), Meta Platforms
Лаклан Форд (Lachlan Ford), Google
Касс Эверитт (Cass Everitt), Meta Platforms
Адам Гусетис (Adam Gousetis), Meta Platforms
Анкур Агравал (Ankur Agrawal), Unity Technologies
Бьорн Свенсон (Bjorn Swenson), LÖVR
Денни Рённгрен (Denny Rönngren), Varjo Technologies
Фредиа Хуя-Куадио (Fredia Huya-Kouadio), Godot Engine
Годун Жун (Guodong Rong), Meta Platforms
Якоб Борнекранц (Jakob Bornecrantz), NVIDIA
Цзянь Чжан (Jian Zhang), ByteDance
Джон Кирни (John Kearney), Meta Platforms
Джонатан Райт (Jonathan Wright), Meta Platforms
Цзюньфэн Шэ (Junfeng She), ByteDance
Кенни Веркамер (Kenny Vercaemer), Google
Кертис Эвелей (Kurtis Eveleigh), Qualcomm
Маурисио Нарваэс (Mauricio Narvaez), Meta Platforms
Натан Нубер (Nathan Nuber), Valve Corporation
Нихав Джайн (Nihav Jain), Google
Никита Луценко, Meta Platforms
Правин Бабу Дж. Д. (Praveen Babu J D), ByteDance
Райли Павлик (Rylie Pavlik), Collabora
Салар Хан (Salar Khan), Google
Шуай Лю (Shuai Liu), ByteDance
Уолтер Лу (Walter Luh), Meta Platforms
Инь Ли (Yin Li), Microsoft
Чжипэн Лю (Zhipeng Liu), ByteDance

Обзор

Это расширение определяет новый класс отображаемых объектов, называемых "пространственными контейнерами", которые аналогичны концепции "окон" в настольных 2D-оконных системах.

В OpenXR 1.x приложения полностью контролируют то, что видит пользователь, и то, как это накладывается на реальную или виртуальную среду. Среды выполнения лишь немного изменяют то, что показывается пользователям, чтобы обеспечить их безопасность. Такая модель приложения хорошо подходит для погружения пользователя в один процесс, но не позволяет одновременно выполнять несколько задач. В частности, в средах дополненной и смешанной реальности пользователи часто хотят работать с несколькими приложениями одновременно.

Пространственные контейнеры похожи на окна, расширенные до 3D. Пользователь может видеть несколько пространственных контейнеров одновременно и взаимодействовать с некоторыми из них. Видимые пространственные контейнеры могут принадлежать разным приложениям, а среды выполнения управляют их размером и размещением от имени пользователя.

Это расширение поддерживает новые типы пространственно ограниченных возможностей в дополнение к существующим иммерсивным возможностям OpenXR. В ограниченных приложениях OpenXR допускается контент с небольшим 3D-эффектом (плоские панели с незначительным смещением по глубине) или объемы, в которых размещается полностью трехмерный контент. Иммерсивные приложения OpenXR – это существующие полноэкранные иммерсивные приложения, которые поддерживаются начиная с OpenXR 1.0. Приложения могут переключаться между двумя типами контента.

Это расширение не определяет метод, с помощью которого приложение может отрисовывать свой контент. Способ отрисовки контента определяется в других расширениях: XR_EXT_spatial_container_self_rendering .

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

XrSpatialContainerEXT – это дескриптор, который представляет пространственный контейнер.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

Приложение начинает отрисовку через пространственный контейнер, выполняя следующие шаги:

  1. Создайте пространственный контейнер с помощью xrCreateSpatialContainerEXT .
  2. Измените любое состояние контейнера для начального представления, например режим границ.
  3. Запросите у среды выполнения показ контейнера с помощью xrRequestSpatialContainerVisibleEXT .
  4. Дождитесь, пока среда выполнения будет готова к показу контейнера. Когда среда выполнения готова, она ставит в очередь событие XrEventDataSpatialContainerVisibleChangedEXT, в котором для visible задано значение XR_TRUE .
  5. Начало отрисовки пространственного контейнера.

А вот как удалить пространственный контейнер:

  1. Запросите у среды выполнения скрытие контейнера с помощью xrRequestSpatialContainerVisibleEXT .
  2. Дождитесь, пока среда выполнения скроет контейнер. Когда среда выполнения полностью скроет контейнер, она поставит в очередь событие XrEventDataSpatialContainerVisibleChangedEXT, в котором для visible будет задано значение XR_FALSE .
  3. Завершение отрисовки пространственного контейнера.
  4. Удалите контейнер с помощью xrDestroySpatialContainerEXT .

Примечание

Это расширение делегирует управление видимостью и фокусом отдельным пространственным контейнерам. Поскольку сеанс в целом больше не представляет собой один видимый или сфокусированный объект, он не проходит через стандартный конечный автомат OpenXR (READY, SYNCHRONIZED, VISIBLE, FOCUSED). Вместо этого сеанс остается в состоянии XR_SESSION_STATE_IDLE на протяжении всего времени его активности, а правила в разделе Изменения состояния сеанса определяют, как основные операции OpenXR сопоставляются с этим режимом.

Как создать пространственный контейнер

Функция xrCreateSpatialContainerEXT создает новый пространственный контейнер.

XrResult xrCreateSpatialContainerEXT(
    XrSession                                   session,
    const XrSpatialContainerCreateInfoEXT*      createInfo,
    XrSpatialContainerEXT*                      spatialContainer);

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

  • session – это XrSession, который создает пространственный контейнер.
  • createInfo – указатель на XrSpatialContainerCreateInfoEXT, содержащий параметры для создания пространственного контейнера.
  • spatialContainer – указатель на дескриптор, в котором возвращается созданный XrSpatialContainerEXT.

Новый созданный объект XrSpatialContainerEXT должен быть невидимым, неинтерактивным и находиться в режиме границ XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT . Приложение, которое хочет, чтобы пространственный контейнер запускался в режиме погружения, может запросить режим границ XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT перед запросом на показ пространственного контейнера.

Среды выполнения должны возвращать XR_ERROR_VALIDATION_FAILURE, если любое измерение XrSpatialContainerCreateInfoEXT :: suggestedBounds отрицательное, бесконечное или не является числом. Среды выполнения должны возвращать XR_ERROR_LIMIT_REACHED, если приложение пытается создать больше пространственных контейнеров, чем указано в XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . Если пространственные контейнеры не были включены для этого сеанса , среды выполнения должны возвращать XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

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

  • Расширение XR_EXT_spatial_container должно быть включено до вызова xrCreateSpatialContainerEXT.
  • session должен быть действительным дескриптором XrSession.
  • createInfo должен быть указателем на действительную структуру XrSpatialContainerCreateInfoEXT.
  • spatialContainer должен быть указателем на дескриптор XrSpatialContainerEXT.

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

Выполнено

  • 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_CONTAINERS_NOT_ENABLED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerCreateInfoEXT передается в xrCreateSpatialContainerEXT для создания пространственного контейнера.

typedef struct XrSpatialContainerCreateInfoEXT {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialContainerGraphicsPresentationEXT    graphicsPresentation;
    XrExtent3Df                                  suggestedBounds;
} XrSpatialContainerCreateInfoEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • graphicsPresentation – это XrSpatialContainerGraphicsPresentationEXT, описывающий, как этот пространственный контейнер представляет графику.
  • suggestedBounds – это XrExtent3Df, описывающий запрошенные размеры пространственного контейнера в метрах.

Если у приложения нет предпочтительного размера, можно задать для suggestedBounds значение {0, 0, 0}. Среда выполнения может игнорировать запрошенный suggestedBounds .

Среда выполнения, которая позволяет ограничивать пространственные контейнеры фигурами, отличными от ориентированных прямоугольников, должна использовать suggestedBounds в качестве граничной рамки вокруг других фигур. Ориентированные прямоугольники – это наиболее распространенная форма ограничивающей рамки.

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

Когда пространственный контейнер больше нельзя использовать, среды выполнения должны поставить в очередь событие XrEventDataSpatialContainerClosedEXT.

typedef struct XrEventDataSpatialContainerClosedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerClosedEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • spatialContainer – XrSpatialContainerEXT, к которому относится событие.

Событие XrEventDataSpatialContainerClosedEXT означает, что среда выполнения больше не может показывать пространственный контейнер, например потому что пользователь нажал кнопку "Закрыть" или сеанс перешел в состояние XR_SESSION_STATE_LOSS_PENDING.

После получения события XrEventDataSpatialContainerClosedEXT приложение должно прекратить использовать пространственный контейнер, удалить все связанные с ним состояния, например цикл рендеринга, и уничтожить контейнер. Среды выполнения должны возвращать XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT из всех функций, работающих с этим контейнером, кроме xrDestroySpatialContainerEXT .

Если пространственный контейнер виден, когда среда выполнения ставит в очередь событие закрытия, среда выполнения должна сначала сделать контейнер невидимым и поставить в очередь событие XrEventDataSpatialContainerVisibleChangedEXT.

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

Функция xrDestroySpatialContainerEXT удаляет существующий пространственный контейнер.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

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

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

Приложение не должно удалять видимый пространственный контейнер, так как это может привести к графическим артефактам. Вместо этого приложение должно запросить скрытие пространственного контейнера с помощью xrRequestSpatialContainerVisibleEXT, дождаться события XrEventDataSpatialContainerVisibleChangedEXT и только после этого удалить контейнер.

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

  • Расширение XR_EXT_spatial_container должно быть включено до вызова xrDestroySpatialContainerEXT.
  • spatialContainer должен быть действительным дескриптором XrSpatialContainerEXT.

Потокобезопасность

  • Доступ к spatialContainer и любым дочерним дескрипторам должен быть синхронизирован извне.

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

Выполнено

  • XR_SUCCESS

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

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

Функция xrCreateSpatialContainerSpaceEXT создает дескриптор XrSpace для пространства определенного пространственного контейнера.

XrResult xrCreateSpatialContainerSpaceEXT(
    XrSession                                   session,
    const XrSpatialContainerSpaceCreateInfoEXT* createInfo,
    XrSpace*                                    space);

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

  • session – это XrSession, который создает пространство.
  • createInfo – указатель на XrSpatialContainerSpaceCreateInfoEXT, содержащий параметры для создания пространства.
  • space – указатель на дескриптор, в котором возвращается созданный объект XrSpace.

Пространство пространственного контейнера – это система координат, начало которой находится в центре границ этого контейнера. Обычно это пространство используется в качестве базового для таких функций, как xrLocateSpace .

+X указывает на правую грань контейнера, +Y – на верхнюю, а +Z – на переднюю. Например, если контейнер выровнен по силе тяжести и находится перед пользователем, а пользователь находится в позе идентификации относительно пространства LOCAL, среды выполнения должны ориентировать пространство контейнера с ориентацией идентификации относительно пространства LOCAL . Среды выполнения могут задавать позу пространства контейнера относительно пространства LOCAL как любую произвольную позу, когда этот контейнер становится видимым.

ext spatial container space convention

Рисунок 18. Обозначение осей пространственного контейнера

Пространство пространственного контейнера – это не заблокированное в мире начало координат. Приложения, которым требуется привязка к миру в режиме погружения, могут использовать пространство с привязкой к миру, например XR_REFERENCE_SPACE_TYPE_LOCAL .

Среды выполнения могут в любой момент изменить положение пространства пространственного контейнера, например когда пользователь перемещает или поворачивает пространственный контейнер. Среды выполнения могут также менять позу при переходе между режимами границ XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT и XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT.

Пространство пространственного контейнера должно оставаться действительным дескриптором, даже если пространственный контейнер, для которого оно предназначено, уничтожен с помощью xrDestroySpatialContainerEXT . Если пространственный контейнер не виден или уничтожен, его пространство не должно быть обнаруживаемым относительно других пространств. XrSpaceLocation :: locationFlags и XrViewState ::viewStateFlags будут равны 0.

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

  • Расширение XR_EXT_spatial_container должно быть включено до вызова xrCreateSpatialContainerSpaceEXT.
  • session должен быть действительным дескриптором XrSession.
  • createInfo должен быть указателем на действительную структуру XrSpatialContainerSpaceCreateInfoEXT.
  • space должен быть указателем на дескриптор XrSpace.

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

Выполнено

  • 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_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerSpaceCreateInfoEXT используется с xrCreateSpatialContainerSpaceEXT для создания дескриптора XrSpace.

typedef struct XrSpatialContainerSpaceCreateInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerSpaceCreateInfoEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • spatialContainer – XrSpatialContainerEXT, для которого нужно создать пространство.

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

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

Отправка содержимого пространственного контейнера в OpenXR для показа обрабатывается другими расширениями: XR_EXT_spatial_container_self_rendering .

Чтобы другие расширения могли указывать метод представления графики для пространственного контейнера, это расширение определяет перечисление XrSpatialContainerGraphicsPresentationEXT.

typedef enum XrSpatialContainerGraphicsPresentationEXT {
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT = 1000813000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT = 1000814000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1 = 1000815000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerGraphicsPresentationEXT;

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

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

Пространственный контейнер использует слои композиции OpenXR (добавлены расширением XR_EXT_spatial_container_self_rendering).

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

Пространственный контейнер создан для тестирования соответствия и не имеет пути рендеринга (добавлено расширением XR_EXT_spatial_container_conformance_automation).

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

Пространственный контейнер использует системный рендеринг OpenXR (добавлено расширением XR_EXTX1_system_renderer)

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

Состояние пространственного контейнера управляется средой выполнения на основе запросов приложения и потребностей пользователя. Поэтому каждый аспект состояния пространственного контейнера документирует следующее:

  • Когда средам выполнения разрешено менять состояние пространственного контейнера. Для большинства состояний пространственных контейнеров среды выполнения могут изменять состояние в любое время.
  • Как приложение запрашивает изменения состояния. Среда выполнения может отложить любой запрос, пока не сочтет его подходящим. Среды выполнения не ставят события в очередь, когда запрос откладывается, поэтому приложения не должны ждать такого события для несвязанной логики.
  • Какие среды выполнения событий ставятся в очередь при изменении состояния пространственного контейнера. Среды выполнения ставят в очередь события для всех изменений, включая запрошенные приложением и инициированные средой выполнения. Среды выполнения не должны ставить в очередь события изменения состояния, которые не указывают на изменение, например если приложение делает два запроса на скрытие контейнера в быстрой последовательности.
  • Какие события ставятся в очередь средами выполнения при отклонении запроса на изменение приложения. Среда выполнения может отклонить запрос по любой причине, обычно из-за системных правил, связанных с поддержанием высокого качества взаимодействия с пользователем.

Функция xrGetSpatialContainerStateEXT запрашивает текущее состояние пространственного контейнера.

XrResult xrGetSpatialContainerStateEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerStateGetInfoEXT*    getInfo,
    XrSpatialContainerStateEXT*                 state);

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

  • spatialContainer – XrSpatialContainerEXT, к которому выполняется запрос.
  • getInfo – XrSpatialContainerStateGetInfoEXT с информацией, которая используется для получения состояния пространственного контейнера.
  • state – указатель на XrSpatialContainerStateEXT, в котором возвращается состояние пространственного контейнера.

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

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

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerStateGetInfoEXT используется с xrGetSpatialContainerStateEXT для запроса XrSpatialContainerStateEXT .

typedef struct XrSpatialContainerStateGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerStateGetInfoEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.

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

typedef struct XrSpatialContainerStateEXT {
    XrStructureType                    type;
    void*                              next;
    XrBool32                           visible;
    XrBool32                           interactable;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerStateEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • visible указывает, виден ли пространственный контейнер.
  • interactable указывает, может ли пространственный контейнер в данный момент принимать входные данные любого типа. Это похоже на фокус в двумерных оконных системах для компьютеров, но с несколькими пространственными контейнерами можно взаимодействовать одновременно.
  • boundsMode – текущий режим XrSpatialContainerBoundsModeEXT пространственного контейнера.

Изменения состояния пространственного контейнера передаются через события.

Событие "Поле изменено"

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

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

Доступ

Приложения запрашивают показ или скрытие пространственного контейнера с помощью xrRequestSpatialContainerVisibleEXT .

XrResult xrRequestSpatialContainerVisibleEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerVisibleRequestInfoEXT* info);

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

Показ или скрытие пространственного контейнера – это асинхронная операция.

Приложения должны запрашивать скрытие пространственного контейнера перед его удалением, чтобы среды выполнения могли отображать плавный переход. Среды выполнения должны учитывать запросы на скрытие пространственного контейнера.

Среда выполнения может отклонять запросы на показ пространственного контейнера. В этом случае она должна поставить в очередь событие XrEventDataSpatialContainerVisibleRequestDeniedEXT. Например, некоторые среды выполнения отклоняют запрос на показ пространственного контейнера, который пользователь скрыл, нажав системную кнопку "Свернуть".

Среды выполнения не должны показывать пространственный контейнер до того, как приложение запросит его показ хотя бы один раз. После первого запроса приложения на показ пространственного контейнера среды выполнения могут изменить видимость этого контейнера независимо от запросов приложения. Это позволяет приложению управлять начальным состоянием и содержимым пространственного контейнера, а средам выполнения – предоставлять системный интерфейс, например панель задач, с помощью которого пользователь может выбирать, какие пространственные контейнеры будут видны.

Среды выполнения должны отклонять запросы на показ пространственного контейнера в неподдерживаемом режиме границ на основе XrSystemSpatialContainerPropertiesEXT :: supportsBounded и XrSystemSpatialContainerPropertiesEXT :: supportsImmersive . Это возможно, если режим границ по умолчанию, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT, не поддерживается в определенной системе.

Примечание

В некоторых реализациях для показа или скрытия пространственного контейнера требуется связь с системными службами, и это может быть отложено до тех пор, пока пользователь не начнет взаимодействовать с системным диалоговым окном. Асинхронный дизайн запросов на изменение состояния видимости позволяет средам выполнения завершить обе эти операции.

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

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

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

Структура XrSpatialContainerVisibleRequestInfoEXT используется с функцией xrRequestSpatialContainerVisibleEXT, чтобы изменить видимость пространственного контейнера.

typedef struct XrSpatialContainerVisibleRequestInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           visible;
} XrSpatialContainerVisibleRequestInfoEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • visible – значение, указывающее, нужно ли показать или скрыть пространственный контейнер.

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

Каждый раз, когда среда выполнения меняет видимость пространственного контейнера, она должна ставить в очередь событие XrEventDataSpatialContainerVisibleChangedEXT с новым состоянием.

typedef struct XrEventDataSpatialContainerVisibleChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 visible;
} XrEventDataSpatialContainerVisibleChangedEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • spatialContainer – XrSpatialContainerEXT, к которому относится событие.
  • visible – новое видимое состояние пространственного контейнера.

Это событие заменяет XR_SESSION_STATE_VISIBLE , позволяя использовать разные значения для каждого контейнера. Событие должно быть поставлено в очередь для всех изменений, включая запрошенные приложением и инициированные во время выполнения.

Среда выполнения может отложить отрисовку контейнера на несколько кадров после постановки этого события в очередь, если для visible задано значение XR_TRUE. Это позволяет избежать показа пустого контейнера и дает приложению время на отправку начального контента. В это время XrSpatialContainerStateEXT ::visible будет иметь значение XR_TRUE . Среда выполнения не должна задерживать отрисовку контейнера более чем на 0,5 секунды.

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

Каждый раз, когда среда выполнения отклоняет запрос на показ контейнера, она должна ставить в очередь событие XrEventDataSpatialContainerVisibleRequestDeniedEXT.

typedef struct XrEventDataSpatialContainerVisibleRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerVisibleRequestDeniedEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • spatialContainer – XrSpatialContainerEXT, к которому относится событие.

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

Интерактивный

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

Каждый раз, когда среда выполнения меняет состояние интерактивности пространственного контейнера, она должна поставить в очередь событие XrEventDataSpatialContainerInteractableChangedEXT с новым состоянием.

typedef struct XrEventDataSpatialContainerInteractableChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 interactable;
} XrEventDataSpatialContainerInteractableChangedEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • spatialContainer – XrSpatialContainerEXT, к которому относится событие.
  • interactable – новое состояние интерактивности для пространственного контейнера.

Это событие заменяет XR_SESSION_STATE_FOCUSED , позволяя использовать разные значения для каждого контейнера. Событие ставится в очередь для всех изменений, включая инициированные средой выполнения.

Среды выполнения могут в любой момент включать или отключать взаимодействие с пространственным контейнером. Если среда выполнения поддерживает только один интерактивный пространственный контейнер за раз, то при смене такого контейнера среда выполнения должна поставить в очередь событие для контейнера, который перестает быть интерактивным ( interactable задано значение false), перед событием для контейнера, который становится интерактивным ( interactable задано значение true).

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

Границы

У пространственного контейнера есть режим границ и граничная рамка. Режим границ пространственного контейнера описывает, как ведут себя границы. Его граничная рамка – это то, внутри чего рисуется пространственный контейнер.

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

typedef enum XrSpatialContainerBoundsModeEXT {
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT = 1,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT = 2,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerBoundsModeEXT;

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

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

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

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

Пространственный контейнер обеспечивает эффект присутствия и не имеет границ. Пространственный контейнер отображается на весь экран.

Для пространственных контейнеров в режиме границ XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT действуют дополнительные требования:

  • Среды выполнения должны обрабатывать эти пространственные контейнеры так же, как полноэкранные приложения и приложения с эффектом присутствия, созданные без использования пространственных контейнеров, за исключением изменений в поведении, описанных в разделе Изменения в состоянии сеанса .
  • Среды выполнения могут предоставлять дополнительные расширения, которые позволяют иммерсивным пространственным контейнерам вести себя иначе, чем приложения в полноэкранном режиме и иммерсивные приложения, созданные без этого расширения.
  • Среды выполнения должны сообщать о бесконечных границах для этих пространственных контейнеров.
  • Среды выполнения могут скрывать другие пространственные контейнеры, пока виден иммерсивный пространственный контейнер. Поскольку это может отличаться в зависимости от среды выполнения, приложения не должны полагаться на автоматический показ или скрытие пространственных контейнеров в зависимости от видимости иммерсивного пространственного контейнера. Как и в случае с другими переходами между состояниями видимости, среды выполнения должны ставить в очередь событие XrEventDataSpatialContainerVisibleChangedEXT, когда пространственный контейнер скрывается из-за того, что виден иммерсивный контейнер.

Примечание

Из требований выше следует, что все среды выполнения могут реализовать путь OpenXR 1.x без этого расширения. Для этого нужно неявно создать пространственный контейнер, установить для него режим границ с эффектом присутствия и запросить его видимость.

Приложения запрашивают изменение режима границ пространственного контейнера с помощью xrRequestSpatialContainerBoundsModeEXT .

XrResult xrRequestSpatialContainerBoundsModeEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsModeRequestInfoEXT* info);

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

Изменение режима границ пространственного контейнера – это асинхронная операция, и среды выполнения могут поставить в очередь событие изменения или отказа через много секунд после того, как приложение запросит изменение. Это позволяет средам выполнения показывать интерфейс, необходимый для безопасного перехода в режим погружения.

Среды выполнения должны учитывать запрос на изменение режима границ для невидимого пространственного контейнера. Если среда выполнения отклоняет запрос на режим границ для невидимого контейнера, она может отклонить или отложить запрос на показ такого пространственного контейнера. Это позволяет приложениям запускать контейнер в режиме иммерсивного просмотра. Среда выполнения может отклонять запросы на изменение режима границ видимого пространственного контейнера. В этом случае она должна поставить в очередь событие XrEventDataSpatialContainerBoundsModeRequestDeniedEXT. Например, некоторые среды выполнения отклоняют запрос на изменение режима границ видимого пространственного контейнера, с которым пользователь не взаимодействует.

Среды выполнения должны возвращать XR_ERROR_VALIDATION_FAILURE, если приложение запрашивает режим границ, который не поддерживается на основе XrSystemSpatialContainerPropertiesEXT :: supportsBounded и XrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

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

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

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialContainerBoundsModeRequestInfoEXT используется с xrRequestSpatialContainerBoundsModeEXT, чтобы изменить режим границ пространственного контейнера.

typedef struct XrSpatialContainerBoundsModeRequestInfoEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerBoundsModeRequestInfoEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • boundsMode – желаемый режим XrSpatialContainerBoundsModeEXT для пространственного контейнера.

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

Каждый раз, когда среда выполнения изменяет границы или режим границ пространственного контейнера, она должна ставить в очередь событие XrEventDataSpatialContainerBoundsChangedEXT с информацией о новых границах.

typedef struct XrEventDataSpatialContainerBoundsChangedEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerEXT              spatialContainer;
    XrExtent3Df                        bounds;
    XrBool32                           infiniteBounds;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrEventDataSpatialContainerBoundsChangedEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • spatialContainer – XrSpatialContainerEXT, к которому относится событие.
  • bounds – новые ширина, высота и глубина границ пространственного контейнера.
  • infiniteBounds – true, если у контейнера бесконечные границы.
  • boundsMode – новый режим XrSpatialContainerBoundsModeEXT пространственного контейнера.

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

Когда пользователь изменяет размер пространственного контейнера, среда выполнения должна вести себя одним из следующих способов:

  • ставить в очередь множество событий, вероятно, с частотой кадров, когда пользователь изменяет размер пространственного контейнера;
  • добавить в очередь одно событие в конце изменения размера;

Если среда выполнения ставит в очередь только одно событие в конце изменения размера, она должна продолжать сообщать старые границы из xrGetSpatialContainerBoundsEXT, пока не поставит в очередь событие изменения размера. Среды выполнения должны объединять несколько событий изменения границ, которые не были опрошены. Другими словами, если границы или режим границ изменяются, пока событие XrEventDataSpatialContainerBoundsChangedEXT все ещё находится в очереди, среды выполнения должны сообщать только об одном событии, содержащем последнее изменение границ. Поскольку приложения могут также напрямую опрашивать границы пространственного контейнера с помощью xrGetSpatialContainerBoundsEXT, количество изменений границ, полученных из событий, может отличаться от количества изменений, полученных в результате опроса. Это зависит от времени изменений границ, сгенерированных средой выполнения, вызовов xrPollEvent и xrGetSpatialContainerBoundsEXT.

При изменении границ пространственного контейнера его локальная точка отсчета может также измениться. Например, если среда выполнения позволяет пользователю изменять размер границ пространственного контейнера, перетаскивая один из его краев, то при перетаскивании одного края границы и локальное начало координат этого контейнера изменятся. В таких ситуациях среда выполнения должна одновременно изменить границы и локальное начало координат.

Среды выполнения должны задавать для infiniteBounds значение XR_TRUE, а для ширины, высоты и глубины – 0.0, чтобы обозначить бесконечные границы. Среды выполнения должны задавать для infiniteBounds значение XR_FALSE, а для ширины, высоты и глубины – конечные положительные числа для конечных границ.

Среды выполнения должны задавать bounds и infiniteBounds по тем же правилам, что и для XrSpatialContainerBoundsEXT .

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

Каждый раз, когда среда выполнения отклоняет запрос на изменение режима границ контейнера, она должна ставить в очередь событие XrEventDataSpatialContainerBoundsModeRequestDeniedEXT.

typedef struct XrEventDataSpatialContainerBoundsModeRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerBoundsModeRequestDeniedEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • spatialContainer – XrSpatialContainerEXT, к которому относится событие.

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

Структура XrSpatialContainerBoundsEXT описывает граничную рамку пространственного контейнера.

typedef struct XrSpatialContainerBoundsEXT {
    XrStructureType    type;
    void*              next;
    XrExtent3Df        bounds;
    XrBool32           infiniteBounds;
} XrSpatialContainerBoundsEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • bounds – ширина, высота и глубина границ пространственного контейнера. Границы указываются в метрах.
  • infiniteBounds – true, если у контейнера бесконечные границы.

Среды выполнения должны задавать для infiniteBounds значение XR_TRUE, а для ширины, высоты и глубины – 0.0, чтобы обозначить бесконечные границы. Среды выполнения должны задавать для infiniteBounds значение XR_FALSE, а для ширины, высоты и глубины – конечные положительные числа для конечных границ.

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

Функция xrGetSpatialContainerBoundsEXT запрашивает текущие границы пространственного контейнера.

XrResult xrGetSpatialContainerBoundsEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsGetInfoEXT*   getInfo,
    XrSpatialContainerBoundsEXT*                bounds);

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

  • spatialContainer – XrSpatialContainerEXT, к которому выполняется запрос.
  • getInfo – XrSpatialContainerBoundsGetInfoEXT с информацией, которая используется для получения состояния пространственного контейнера.
  • bounds – указатель на XrSpatialContainerBoundsEXT, в котором возвращаются границы.

Ограниченный пространственный контейнер не должен иметь бесконечные границы, а иммерсивный – должен.

Среды выполнения могут в любой момент изменить границы пространственного контейнера на любое положительное конечное значение, пока пространственный контейнер ограничен. Изменения границ пространственного контейнера передаются через XrEventDataSpatialContainerBoundsChangedEXT .

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

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

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

Выполнено

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_ERROR_VALIDATION_FAILURE

Структура XrSpatialContainerBoundsGetInfoEXT является входной и предназначена для будущих расширений.

typedef struct XrSpatialContainerBoundsGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerBoundsGetInfoEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.

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

Перечисление XrSpatialContainerVolumeClippingEXT определяет разные варианты поведения при обрезке объема для пространственного контейнера.

typedef enum XrSpatialContainerVolumeClippingEXT {
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT = 0,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT = 1,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerVolumeClippingEXT;

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

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

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

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

Контент строго ограничен объемом пространственного контейнера.

В этом расширении перечисление не используется. Оно позволяет другим расширениям задавать нужное поведение при ограничении громкости. Например, приложение может нарисовать фон для ограниченного пространственного контейнера. Монокулярная кубическая карта – удобный способ задать фон, однако концептуально она расположена на бесконечности, то есть за пределами контейнера.

Возможности системы

Приложение может проверять возможности системы, связывая структуру XrSystemSpatialContainerPropertiesEXT со структурой XrSystemProperties при вызове xrGetSystemProperties .

typedef struct XrSystemSpatialContainerPropertiesEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSpatialContainerCount;
    XrBool32           supportsBounded;
    XrBool32           supportsImmersive;
} XrSystemSpatialContainerPropertiesEXT;

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке. Такие структуры не определены в ядре OpenXR или этом расширении.
  • maxSpatialContainerCount – максимальное количество пространственных контейнеров, которые можно создать.
  • supportsBounded – true, если пространственные контейнеры могут быть ограничены.
  • supportsImmersive – true, если пространственные контейнеры могут быть иммерсивными.

Среды выполнения, поддерживающие это расширение, должны поддерживать создание приложением множества пространственных контейнеров, ограниченных только выделением памяти. В среде выполнения может быть установлено другое ограничение на количество одновременно показываемых пространственных контейнеров. В этом расширении нельзя запросить количество одновременно отображаемых контейнеров, поскольку среда выполнения может ограничивать отдельные приложения в зависимости от состояния всех запущенных приложений. Предполагается, что устройства с жесткими и менее жесткими ограничениями будут иметь разные лимиты на количество одновременно отображаемых контейнеров. Устройства с жесткими ограничениями могут поддерживать только один пространственный контейнер, отображаемый за раз, а устройства с менее жесткими ограничениями могут поддерживать большое количество пространственных контейнеров, отображаемых одновременно, с учетом вычислительных ограничений рендеринга.

Среды выполнения, поддерживающие это расширение, должны поддерживать хотя бы один из ограниченных или иммерсивных пространственных контейнеров.

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

Функция xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT возвращает методы графического представления, поддерживаемые системой.

XrResult xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    graphicsPresentationCapacityInput,
    uint32_t*                                   graphicsPresentationCountOutput,
    XrSpatialContainerGraphicsPresentationEXT*  graphicsPresentations);

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

  • instance – это XrInstance, из которого был получен systemId.
  • systemId – запрашиваемый XrSystemId.
  • graphicsPresentationCapacityInput – емкость массива graphicsPresentations или 0, если нужно получить требуемую емкость.
  • graphicsPresentationCountOutput – указатель на количество записанных графических представлений или указатель на требуемую емкость, если graphicsPresentationCapacityInput равно 0.
  • graphicsPresentations – указатель на массив значений XrSpatialContainerGraphicsPresentationEXT, но может быть нулевым, если graphicsPresentationCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер graphicsPresentations, приведено в разделе Параметры размера буфера.

Среды выполнения должны всегда возвращать идентичное содержимое буфера из этого перечисления для заданного systemId и в течение времени существования экземпляра.

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

  • Расширение XR_EXT_spatial_container должно быть включено до вызова xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT.
  • instance должен быть действительным дескриптором XrInstance.
  • graphicsPresentationCountOutput должен быть указателем на значение uint32_t.
  • Если graphicsPresentationCapacityInput не равно 0 , graphicsPresentations должен быть указателем на массив значений graphicsPresentationCapacityInput XrSpatialContainerGraphicsPresentationEXT.

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

Выполнено

  • XR_SUCCESS

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Изменения в состоянии сеанса

Поддержка пространственных контейнеров включается для сеанса путем связывания XrSessionCreateInfoSpatialContainersEXT при вызове xrCreateSession .

typedef struct XrSessionCreateInfoSpatialContainersEXT {
    XrStructureType    type;
    const void*        next;
} XrSessionCreateInfoSpatialContainersEXT;

Если поддержка пространственных контейнеров включена, XrSession работает иначе. Это связано с тем, что при использовании пространственных контейнеров сеанс больше не представляет графический контент на дисплеях, вместо этого используются пространственные контейнеры. Поэтому, когда это расширение включено, сеанс фактически является "безголовым". В отличие от других расширений без интерфейса, приложения могут отправлять данные изображений через пространственные контейнеры.

Включение поддержки пространственного контейнера изменяет основные API OpenXR следующим образом.

время выполнения: потеря системы или устройства;

время выполнения: потеря системы или устройства;

xrDestroySession

xrDestroySession

IDLE
(выполняется)

НЕАКТИВНО

xrGetSystem
xrCreateSession

xrGetSystem...

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(не выполняется)

LOSS_PENDING...

xrDestroyInstance

xrDestroyInstance

приложение: при необходимости
перезапустите XR

app: optionally...

Рисунок 19. Новый конечный автомат сеанса

  • Сеанс не переходит в состояния XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED или XR_SESSION_STATE_EXITING . Среды выполнения не должны ставить в очередь события для этих состояний. Эти состояния заменяются событиями пространственного контейнера XrEventDataSpatialContainerVisibleChangedEXT, XrEventDataSpatialContainerInteractableChangedEXT и XrEventDataSpatialContainerClosedEXT соответственно.
  • Сеанс также никогда не переходит в состояния XR_SESSION_STATE_READY , XR_SESSION_STATE_SYNCHRONIZED , XR_SESSION_STATE_STOPPING . Среды выполнения не должны ставить в очередь события для этих состояний. Замены для этих статусов нет.
  • Среды выполнения должны обрабатывать сеанс как запущенный, когда он находится в состоянии XR_SESSION_STATE_IDLE .
  • Среды выполнения должны обрабатывать сеанс как находящийся в фокусе, когда он находится в состоянии XR_SESSION_STATE_IDLE и существует хотя бы один пространственный контейнер, с которым можно взаимодействовать.
  • Функции xrBeginSession и xrEndSession больше не нужны. При вызове этих функций среды выполнения должны возвращать XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT. Другие расширения могут предоставлять замену этим функциям.
  • Функция xrRequestExitSession также больше не нужна. При вызове этой функции среды выполнения должны возвращать XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT. Приложения, которые хотят выйти из запущенного сеанса, могут вызвать xrRequestSpatialContainerVisibleEXT, чтобы скрыть свои контейнеры, и уничтожить сеанс после того, как все контейнеры перестанут быть видимыми.

  • Расширения, которые ставят в очередь дополнительные события при запуске сеанса, должны ставить их в очередь после создания сеанса. Такие расширения указаны ниже.

    Событие расширения

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

  • Функцию xrLocateViews нельзя вызвать для сеанса. Среды выполнения должны возвращать XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT из xrLocateViews . Другие расширения могут предоставлять способы поиска представлений для определенного пространственного контейнера.
  • Функция xrWaitFrame должна всегда задавать для XrFrameState :: shouldRender значение false. Другие расширения могут предоставлять способы узнать, должен ли определенный пространственный контейнер обновлять свои слои композиции.
  • Функция xrEndFrame не подходит для отправки слоев композиции. Если приложение задает для XrFrameEndInfo :: layerCount ненулевое значение, среды выполнения должны возвращать XR_ERROR_VALIDATION_FAILURE . Другие расширения могут предоставлять способы отправки слоев композиции для определенного пространственного контейнера.
  • При переходе в состояние XR_SESSION_STATE_LOSS_PENDING также закрываются все пространственные контейнеры. Среды выполнения должны ставить в очередь событие XrEventDataSpatialContainerClosedEXT для каждого активного пространственного контейнера, прежде чем ставить в очередь изменение состояния сеанса для XR_SESSION_STATE_LOSS_PENDING .
  • Функции xrCreateSession больше не требуется структура привязки графического API. Для других расширений может потребоваться привязка графики, например для пространственного контейнера, который будет отображаться с помощью графического API.

Описанное выше поведение немного отличается от поведения в XR_MND_headless . Среды выполнения не должны включать поведение сеанса без графического интерфейса из XR_MND_headless, если для этого сеанса включена поддержка пространственного контейнера.

Примечание

Когда пространственные контейнеры включены, сеанс переходит только между двумя состояниями: XR_SESSION_STATE_IDLE (выполняется) и XR_SESSION_STATE_LOSS_PENDING (не выполняется). В результате среды выполнения больше не возвращают XR_ERROR_SESSION_RUNNING или XR_ERROR_SESSION_NOT_RUNNING . Вместо этого, когда сеанс не запущен, среды выполнения возвращают XR_ERROR_SESSION_LOST или XR_SESSION_LOSS_PENDING в соответствии с правилами OpenXR core. Кроме того, xrBeginSession, единственная функция, которая возвращает XR_ERROR_SESSION_RUNNING, теперь всегда будет возвращать XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT .

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

Записи манифеста Android

Среды выполнения на основе AOSP могут иметь настраиваемое поведение, основанное на начальном состоянии пространственного контейнера, которое запускается до выполнения любого кода приложения. Например, среда выполнения может изменить ресурсы, выделенные для действия, запустить анимацию или показать заставку. Для этого используются следующие свойства: Они заменяют тег <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, который приложения на основе пространственных контейнеров не должны указывать, за исключением случаев, когда это необходимо для совместимости с более ранними средами выполнения на основе AOSP.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
          android:value="list of modes" />

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

Для этого атрибута допустимы следующие строки: Несколько значений разделяются символом | , например "bounded|immersive" .

Значение

Описание

"2d_panel"

Для отображения действий используется фреймворк Android для 2D-представлений.

"bounded"

В этом упражнении используется XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT .

"immersive"

В этом упражнении используется XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT .

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
          android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED" />

Это свойство указывает средам выполнения начальный режим XrSpatialContainerBoundsModeEXT действия при его создании. По умолчанию это строка XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, которая означает, что подсказка отсутствует.

Среды выполнения не должны требовать от приложений наличия этих свойств, чтобы вести себя в соответствии с этой спецификацией. Среды выполнения не должны изменять видимое поведение приложения на основе этих свойств. Все такие метаданные должны быть указаны на уровне <activity> или <application>. Если атрибут указан на уровне <application>, он применяется ко всем действиям в приложении, для которых не заданы собственные значения.

Пример кода

В следующем коде показано, как использовать это расширение для сценариев, в которых требуется только распознавание без отрисовки.

XrInstance instance;    // Already initialized


// Create the session with spatial containers enabled
XrSession session;

XrSessionCreateInfoSpatialContainersEXT spatialContainerCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT,
};
XrSessionCreateInfo sessionCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO,
  .next = &spatialContainerCreateInfo,   // Enable spatial containers
};
(void)sessionCreateInfo.systemId;                             // Other create fields set in usual way

CHK_XR(xrCreateSession(instance, &sessionCreateInfo, &session));


// Because spatial containers are enabled, the session is considered
// running. App is able to query perception data such as head poses and hand
// poses.


// Based on app logic or when a system lost event happens, destroy the
// session
CHK_XR(xrDestroySession(session));

Новые типы объектов

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

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

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

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

  • XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
  • XR_EXT_spatial_container_SPEC_VERSION

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

    • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

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

    • XR_ERROR_COMPATIBLE_SPATIAL_CONTAINER_MISSING_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT

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

    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
    • XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
    • XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
    • XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT

Проблемы

  • Как обрабатываются несколько видимых запросов? Должно ли приложение получить одно изменение/отказ или несколько? Если вызовы выполняются в нескольких фреймах, ответ может быть другим. Ответ также может быть другим, если несколько запросов приводят к отсутствию операции, например запрос на то, чтобы пространственный контейнер был видимым, а затем невидимым для контейнера, который изначально не виден.

    • Решено. Разные варианты для событий изменения и отклонения. Запросы Noop не ставят в очередь событие изменения, а только создают шум для разработчика приложения, который легко отфильтровать в среде выполнения. Если отклонено несколько видимых запросов, среды выполнения должны сгенерировать соответствующее событие отказа.

  • Как должно быть определено расширение автоматизации соответствия, чтобы весь необязательный текст спецификации для поведения политики по-прежнему можно было протестировать с помощью CTS?

    • Решено. Отдельное тестовое расширение. Для CTS будет реализована тестовая среда выполнения расширений, которая позволит CTS управлять всеми системными правилами.

  • Нужно ли нам событие для изменения положения пространственного контейнера?

    • Решено. Нет. Пространство пространственного контейнера не привязано к миру, и другие подобные пространства, такие как XR_REFERENCE_SPACE_TYPE_VIEW, не имеют событий при изменении.

  • Как работает xrSyncActions, если есть несколько пространственных контейнеров?

    • Решено. Изменения не требуются. xrSyncActions будет применяться ко всем пространственным контейнерам в сеансе. Если приложение хочет направить действия ввода в определенный пространственный контейнер, оно может посмотреть на интерактивное состояние каждого контейнера, чтобы выбрать, какие контейнеры являются допустимыми целями. Если приложение хочет синхронизировать состояние действия ввода только для одного пространственного контейнера, потребуется дополнительное расширение. Однако мы планируем сосредоточиться на расширении, которое позволит приложениям полностью работать на основе событий и избавит от необходимости вызывать xrSyncActions в цикле кадров.

  • Как приложения, которые редко обновляются, обрабатывают входные данные?

    • Решено. Изменения не требуются. Это полезно не только для EXT_spatial_container, но и для других контейнеров. Это можно сделать с помощью расширения канала событий, которое работает в обоих случаях. Для пространственных контейнеров мы добавим дополнительные способы фильтрации событий.

  • Нужно ли нам ждать, чтобы ограничить или контролировать время цикла ввода для приложений с разделенными циклами ввода и рендеринга?

    • Решено. Изменения не требуются. Для этого используются канал событий и расширения запросов. Расширение Present Request позволяет выполнять рендеринг на основе событий и независимо от цикла кадров.

  • Может ли пространственный контейнер получить свою позу относительно других пространственных контейнеров? Основные мысли: есть ли у нас пример использования для этого? Если да, то как пространства пространственных контейнеров связаны с LOCAL?

    • Решено. Да. Это уже возможно для пространственных контейнеров в рамках одного сеанса через XR_REFERENCE_SPACE_TYPE_VIEW, и желательно поддерживать контент, зависящий от представления. Чтобы передавать позы пространственных контейнеров между сеансами (например, в другой процесс), рекомендуется использовать XR_EXT_spatial_anchor и существующие в нем шаблоны сохранения и передачи.

  • Можно ли определить местоположение пространства пространственного контейнера, если оно невидимо?

    • Решено. Нет. Пространство пространственного контейнера невозможно найти, когда пространственный контейнер не виден. Это означает, что у него нет пространственного звука и приложение не может "разогреть" контент, зависящий от представления, когда spatial_container не виден. Оба варианта допустимы, поскольку, когда пространственный контейнер не виден, приложение должно прекратить любую нагрузку на ЦП или графический процессор, которая используется для этого пространственного контейнера.

  • Где в пространственном контейнере должно находиться пространство пространственного контейнера? Предложения были центром или минимальной точкой (minX, minY, minZ).

    • Решено. В центре. Нет места, которое не перемещается большинством способов, ожидаемых от UX изменения размера пространственного контейнера (перемещение краев). Центр часто используется в других частях OpenXR. Мы не стали выравнивать окна по минимальной координате, как это делается в 2D-вычислениях, поскольку в программах для просмотра 3D-моделей это правило часто не соблюдается.

  • Когда среда выполнения должна создавать ресурсы, лежащие в основе пространственного контейнера? Иногда для этого требуется межпроцессное взаимодействие с системными службами.

    • Решено. Синхронно в рамках xrCreateSpatialContainerEXT . Хотя при этом может использоваться IPC, создание контейнера обычно не требует больших ресурсов. У некоторых поставщиков есть глобальные блокировки, связанные с управлением контейнерами, но обычно они не приводят к длительному ожиданию. Проблемы с конфликтами блокировок – это ошибки, характерные для конкретных поставщиков, которые должны быть устранены каждым из них.

  • Нужен ли нам сигнал о том, что XrSession создаст пространственные контейнеры и поэтому не будет поддерживать устаревший путь рендеринга?

    • Решено. Да. Мы фундаментально меняем конечный автомат сеанса.

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

  • Версия 1, 06.08.2026 (Джаред Финдер, Google)

    • Описание расширения