XR_EXT_spatial_entity

Строка имени

XR_EXT_spatial_entity

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

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

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

741

Пересмотр

1

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

Ратифицирован

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

XR_EXT_future

Авторы

Нихав Джайн, Google
Джаред Финдер, Google
Натали Флери, Мета
Юичи Тагучи, Мета
Рон Бессемс, Мета
Инь Ли, Microsoft
Картик Кадаппан, Magic Leap
Джимми Алампарамбил, ByteDance
Чжипен Лю, ByteDance
Джун Ян, ByteDance

Обзор

Это расширение знакомит с концепциями и основами понимания сцены и пространственного мышления в OpenXR. Оно объединяет несколько связанных, но различных областей функциональности, которые перечислены, сконфигурированы и взаимодействуют в целом единообразно, как определено в этом расширении. Поскольку в этом расширении отсутствуют конкретные определения какой-либо из этих функциональных областей, формальный текст спецификации, как правило, несколько абстрактен. Примеры, включенные в текст спецификации этого расширения, иногда ссылаются на функциональность, определенную в готовящемся или гипотетическом связанном расширении, в целях иллюстрации, не ограничивая и не уточняя при этом такую ​​дополнительную функциональность.

Основные элементы этого расширения следующие:

  • Пространственные объекты : Функциональность сосредоточена вокруг объектов , которые сами по себе предоставляют очень мало возможностей.
  • Пространственные компоненты : Эти сущности имеют связанные с ними компоненты , которые предоставляют данные и обеспечивают определенное поведение.
  • Типы пространственных компонентов : Каждый пространственный компонент относится к определенному типу , и любой данный объект может иметь не более одного компонента любого заданного типа .
  • Пространственный контекст : Все взаимодействия с пространственными объектами происходят в контексте после фазы инициализации и конфигурации.
  • Пространственные возможности : Манипулирование пространственными объектами в основном обеспечивается возможностями . Возможность — это некоторая единица функциональности, например (без ограничений) определяемые приложением якоря, обнаружение плоскостей или отслеживание изображений. Каждая возможность обычно определяется в отдельном расширении (включается при создании экземпляра, как обычно) и активируется для конкретного контекста в момент создания.
  • Каждая возможность связана с набором типов компонентов , для которых компоненты присутствуют в каждой сущности, предоставляемой этой возможностью . Расширение, определяющее возможность, указывает, какие типы компонентов являются обязательными для этой возможности («гарантированными»), в то время как это же расширение или другие могут указывать необязательные типы компонентов, предоставляемые некоторыми потенциальными реализациями. Любое количество возможностей может предоставлять сущностям компоненты заданного типа , которые одинаково пригодны для использования независимо от возможности , которая их создала.
  • Характеристики пространственных возможностей : Кроме того, некоторые возможности требуют настройки и, следовательно, параметризуются характеристиками возможностей .

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

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

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

Пространственный объект

Пространственные объекты — это объекты, существующие в некотором пространстве и имеющие различные связанные с ними данные, организованные в компоненты. К ним могут относиться следующие объекты:

  • Физические объекты (например, плоские поверхности, такие как стены и полы, предметы, такие как стулья и книжные полки и т. д.).
  • Виртуальный (например, контент, размещенный и переданный другим приложением или пользователем),
  • Определяется приложением (например, приложение обозначает зону как «гостиную» или «кухню», или отмечает точку как место для размещения телевизора и т. д.).

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

В OpenXR пространственные объекты моделируются как система «объект-компонент» . Каждый пространственный объект имеет набор компонентов, и каждый компонент предоставляет уникальный набор данных и поведения для этого объекта.

Пространственные объекты представляются либо атомом XrSpatialEntityIdEXT , либо дескриптором XrSpatialEntityEXT , подробная информация о которых приведена в разделе «Представление пространственных объектов» .

Типы пространственных компонентов

Пространственный объект имеет один или несколько компонентов, которые предоставляют данные или поведение для этого объекта. См. раздел «Общие компоненты» для получения информации о некоторых общих компонентах, определенных этим расширением. 

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

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

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

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

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

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Компонент, предоставляющий двумерные границы для пространственного объекта. Соответствующая структура списка: XrSpatialComponentBounded2DListEXT ; соответствующая структура данных: XrSpatialBounded2DDataEXT.

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

Компонент, задающий трехмерные границы для пространственного объекта. Соответствующая структура списка: XrSpatialComponentBounded3DListEXT ; соответствующая структура данных: XrBoxf.

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

Компонент, предоставляющий XrSpatialEntityIdEXT родительского элемента для пространственной сущности. Соответствующая структура списка: XrSpatialComponentParentListEXT ; соответствующая структура данных: XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

Компонент, предоставляющий 3D-сетку для пространственного объекта. Соответствующая структура списка: XrSpatialComponentMesh3DListEXT ; соответствующая структура данных: XrSpatialMeshDataEXT.

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

Компонент, предоставляющий перечисление выравнивания плоскости для пространственного объекта. Соответствующая структура списка: XrSpatialComponentPlaneAlignmentListEXT ; соответствующая структура данных: XrSpatialPlaneAlignmentEXT (добавлено расширением XR_EXT_spatial_plane_tracking ).

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

Компонент, предоставляющий 2D-сетку для пространственного объекта. Соответствующая структура списка: XrSpatialComponentMesh2DListEXT ; соответствующая структура данных: XrSpatialMeshDataEXT (добавлено расширением XR_EXT_spatial_plane_tracking ).

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

Компонент, предоставляющий двумерный полигон границы для пространственного объекта. Соответствующая структура списка: XrSpatialComponentPolygon2DListEXT ; соответствующая структура данных: XrSpatialPolygon2DDataEXT (добавлено расширением XR_EXT_spatial_plane_tracking ).

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

Компонент, предоставляющий семантическую метку для плоскости. Соответствующая структура списка: XrSpatialComponentPlaneSemanticLabelListEXT ; соответствующая структура данных: XrSpatialPlaneSemanticLabelEXT (добавлено расширением XR_EXT_spatial_plane_tracking ).

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

Компонент, описывающий тип, идентификатор и местоположение маркера. Соответствующая структура списка: XrSpatialComponentMarkerListEXT ; соответствующая структура данных: XrSpatialMarkerDataEXT (добавлено расширением XR_EXT_spatial_marker_tracking ).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

Компонент, предоставляющий семантическую метку для сцены; соответствующая структура списка — XrSpatialComponentObjectSemanticLabelListEXT . Соответствующая структура данных — XrSpatialObjectSemanticLabelEXT . (Добавлено расширением XR_EXT_spatial_object_tracking )

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

Компонент, предоставляющий семантическую метку для клавиатуры; соответствующая структура списка — XrSpatialComponentKeyboardSemanticLabelListEXT . Соответствующая структура данных — XrSpatialKeyboardSemanticLabelEXT (добавлена ​​расширением XR_EXT_spatial_object_tracking ).

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

Компонент, предоставляющий семантическую метку для мыши; соответствующая структура списка — XrSpatialComponentMouseSemanticLabelListEXT . Соответствующая структура данных — XrSpatialMouseSemanticLabelEXT (добавлена ​​расширением XR_EXT_spatial_object_tracking ).

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

Компонент, указывающий местоположение для привязки. Соответствующая структура списка: XrSpatialComponentAnchorListEXT ; соответствующая структура данных: XrPosef (добавлена ​​расширением XR_EXT_spatial_anchor ).

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

Компонент, предоставляющий сохраняемый UUID для пространственного объекта. Соответствующая структура списка: XrSpatialComponentPersistenceListEXT ; соответствующая структура данных: XrSpatialPersistenceDataEXT (добавлена ​​расширением XR_EXT_spatial_persistence ).

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

Компонент, описывающий тип плоского изображения. Соответствующая структура списка: XrSpatialComponentImage2DListEXT ; соответствующая структура данных: XrSpatialImageSizeEXT . (Добавлено расширением XR_EXT_spatial_image_tracking )

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

Компонент, предоставляющий нормали для 3D-сетки пространственного объекта. Соответствующая структура списка: XrSpatialComponentMesh3DNormalsListEXT ; соответствующая структура данных: XrSpatialBufferEXT (добавлено расширением XR_EXT_spatial_mesh_tracking ).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

Компонент, предоставляющий семантические метки для каждой вершины 3D-сетки пространственного объекта. Соответствующая структура списка: XrSpatialComponentMesh3DVertexSemanticLabelsListEXT ; соответствующая структура данных: XrSpatialBufferEXT ; данные внутри буфера соответствуют XrSpatialMeshSemanticLabelEXT (добавлено расширением XR_EXT_spatial_mesh_tracking ).

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

Компонент, предоставляющий семантические метки для каждой грани треугольника в 3D-сетке пространственного объекта. Соответствующая структура списка: XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT ; соответствующая структура данных: XrSpatialBufferEXT ; данные внутри буфера соответствуют XrSpatialMeshSemanticLabelEXT (добавлено расширением XR_EXT_spatial_mesh_tracking ).

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

Компонент, предоставляющий семантическую метку для объекта; соответствующая структура списка: XrSpatialComponentObjectSemanticLabelListANDROID ; соответствующая структура данных: XrSpatialObjectSemanticLabelANDROID (добавлено расширением XR_ANDROID_spatial_object_tracking ).

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Компонент, предоставляющий положение объекта, полученное в результате трассировки луча. Соответствующая структура списка: XrSpatialComponentRaycastResultListANDROID ; соответствующая структура данных: XrSpatialRaycastResultDataANDROID (добавлено расширением XR_ANDROID_spatial_discovery_raycast ).

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

Компонент, предоставляющий идентификатор сущности, которая включает в себя присоединенную сущность. Соответствующая структура списка: XrSpatialComponentSubsumedByListANDROID ; соответствующая структура данных: XrSpatialEntityIdEXT (добавлено расширением XR_ANDROID_spatial_component_subsumed_by ).

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

Компонент, предоставляющий размеры и тип помещения в коробке из-под обуви; соответствующая структура списка: XrSpatialComponentRoomListANDROIDSYS ; соответствующая структура данных: XrSpatialRoomDataANDROIDSYS (добавлено расширением XR_ANDROIDSYS_spatial_room_tracking ).

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

Компонент, предоставляющий тип материала для граничной поверхности; соответствующая структура списка: XrSpatialComponentMaterialTypeListANDROIDSYS ; соответствующая структура данных: XrSpatialMaterialTypeANDROIDSYS (добавлено расширением XR_ANDROIDSYS_spatial_room_tracking ).

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

Компонент, обеспечивающий достоверность отслеживаемого объекта; соответствующая структура списка: XrSpatialComponentConfidenceListANDROIDSYS ; соответствующая структура данных: float (добавлено расширением XR_ANDROIDSYS_spatial_room_tracking ).

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

Компонент, отображающий состояние пустого помещения; соответствующая структура списка: XrSpatialComponentRoomEmptinessListANDROIDSYS ; соответствующая структура данных: float (добавлено расширением XR_ANDROIDSYS_spatial_room_tracking ).

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

Компонент, предоставляющий информацию о сетке занятости подключенного объекта. Соответствующая структура списка: XrSpatialComponentOccupancyGridListANDROIDX1 ; соответствующая структура данных: XrSpatialOccupancyGridDataANDROIDX1 (добавлено расширением XR_ANDROIDX1_spatial_occupancy_grid ).

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Компонент, описывающий аннотацию квадрата. Соответствующая структура списка: XrSpatialComponentAnnotationQuadListANDROID ; соответствующая структура данных: XrSpatialAnnotationQuadDataANDROID (добавлено расширением XR_ANDROID_spatial_annotation_tracking ).

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

Компонент, предоставляющий метаданные для геометрии городского ландшафта; соответствующая структура списка: XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 ; соответствующая структура данных: XrSpatialStreetscapeGeometryMetadataANDROIDX2 (добавлено расширением XR_ANDROIDX2_geospatial_streetscape ).

Пространственные возможности и настройка

Пространственные возможности определяют способность среды выполнения обнаруживать объекты, для которых гарантированно задан набор компонентов. Приложения включают компоненты пространственной возможности при создании XrSpatialContextEXT , а среда выполнения, в свою очередь, должна предоставлять только включенные компоненты для обнаруженных объектов. Например, если среда выполнения сообщает, что одним из компонентов для данной возможности являются «семантические метки», это означает, что приложение может включить семантические метки через конфигурацию для этой возможности, и среда выполнения должна предоставлять компонент семантической метки только в том случае, если он настроен. 

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

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

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

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

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

Отслеживание плоскости (добавлено расширением XR_EXT_spatial_plane_tracking )

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

Возможность обнаружения и отслеживания QR-кодов. (Добавлено расширением XR_EXT_spatial_marker_tracking )

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

Возможность обнаружения и отслеживания микро-QR-кодов. (Добавлено расширением XR_EXT_spatial_marker_tracking )

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

Возможность обнаружения и отслеживания маркеров Aruco. (Добавлено расширением XR_EXT_spatial_marker_tracking )

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

Возможность обнаружения и отслеживания меток AprilTags. (Добавлено расширением XR_EXT_spatial_marker_tracking )

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

Отслеживание объектов (добавлено расширением XR_EXT_spatial_object_tracking )

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

Возможность создания пространственных якорей (добавлена ​​расширением XR_EXT_spatial_anchor )

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Возможность обнаружения и отслеживания плоских опорных изображений. (Добавлено расширением XR_EXT_spatial_image_tracking )

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

Возможность отслеживать сетку окружающей среды. (Добавлено расширением XR_EXT_spatial_mesh_tracking )

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

Отслеживание объектов (добавлено расширением XR_ANDROID_spatial_object_tracking )

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Трассировка лучей относительно буфера глубины (добавлено расширением XR_ANDROID_spatial_discovery_raycast )

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

Возможность отслеживания помещения (добавлена ​​расширением XR_ANDROIDSYS_spatial_room_tracking )

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

Возможность отслеживания границ помещения (добавлена ​​расширением XR_ANDROIDSYS_spatial_room_tracking )

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Отслеживание аннотаций (добавлено расширением XR_ANDROID_spatial_annotation_tracking )

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

Геометрия городского ландшафта (добавлена ​​расширением XR_ANDROIDX2_geospatial_streetscape )

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

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

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

  • instance — это дескриптор объекта XrInstance .
  • systemId — это XrSystemId , пространственные возможности которого будут перечислены.
  • capabilityCapacityInput — это емкость массива capabilities , или 0, указывающее на запрос на получение требуемой емкости.
  • capabilityCountOutput — это количество возможностей или требуемая мощность в случае, если capabilityCapacityInput недостаточна.
  • capabilities — это массив объектов XrSpatialCapabilityEXT . Он может быть NULL если capabilityCapacityInput равен 0.
  • Подробное описание получения необходимого размера capabilities см. в разделе « Параметры размера буфера» .

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

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

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

  • Расширение XR_EXT_spatial_entity необходимо включить перед вызовом функции xrEnumerateSpatialCapabilitiesEXT.
  • instance должен быть допустимым дескриптором XrInstance.
  • capabilityCountOutput должен быть указателем на значение типа uint32_t
  • Если capabilityCapacityInput не равно 0 , capabilities должно быть указателем на массив значений capabilityCapacityInput XrSpatialCapabilityEXT.

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

Успех

  • 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

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

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

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

  • instance — это дескриптор объекта XrInstance .
  • systemId — это XrSystemId , компоненты пространственных возможностей которого будут перечислены.
  • capability — это XrSpatialCapabilityEXT , для которого будут перечислены компоненты.
  • capabilityComponents — это указатель на XrSpatialCapabilityComponentTypesEXT , структуру ввода/вывода, в которую заполняется выделенный приложением массив.

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

Приложение может использовать типы компонентов, перечисленные в XrSpatialCapabilityComponentTypesEXT :: componentTypes , чтобы понять полный набор компонентов, поддерживаемых systemId для capability , и может использовать этот список для определения допустимой конфигурации для capability при создании XrSpatialContextEXT для него.

Если capability не указана в параметре xrEnumerateSpatialCapabilitiesEXT , среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

В среде выполнения не следует перечислять типы пространственных компонентов, расширение которых, instance , не включено.

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

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

Успех

  • XR_SUCCESS

Отказ

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

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

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • componentTypeCapacityInput — это емкость массива, или 0, указывающее на запрос на получение требуемой емкости.
  • componentTypeCountOutput — это количество типов компонентов или требуемая мощность в случае, если componentTypeCapacityInput недостаточен.
  • componentTypes — это массив объектов XrSpatialComponentTypeEXT . Он может быть NULL если componentTypeCapacityInput равен 0.
  • Подробное описание получения необходимого размера componentTypes см. в разделе « Параметры размера буфера» .

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

Функции пространственных возможностей 

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

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

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

Такие характеристики представлены библиотекой XrSpatialCapabilityFeatureEXT , а приложение перечисляет их с помощью библиотеки xrEnumerateSpatialCapabilityFeaturesEXT .

Для каждой функциональной возможности существует соответствующая структура конфигурации, позволяющая её активировать. Такие структуры конфигурации должны быть связаны цепочкой с XrSpatialCapabilityConfigurationBaseHeaderEXT :: next соответствующей функциональной возможности.

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

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

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

Функция, позволяющая приложениям задавать размер маркеров. Соответствующая структура конфигурации: XrSpatialMarkerSizeEXT (добавлена ​​расширением XR_EXT_spatial_marker_tracking ).

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

Функция, позволяющая приложениям указывать, являются ли маркеры статическими. Соответствующая структура конфигурации — XrSpatialMarkerStaticOptimizationEXT (добавлена ​​расширением XR_EXT_spatial_marker_tracking ).

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Пространственная функция, позволяющая приложениям указывать подмножество меток из XrSpatialObjectSemanticLabelEXT для отслеживания средой выполнения. Соответствующая структура конфигурации — XrSpatialFeatureObjectSemanticLabelSubsetEXT . (Добавлено расширением XR_EXT_spatial_object_tracking )

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

Среда выполнения поддерживает фильтр XrSpatialBoundsSpherefANDROID для XrSpatialDiscoverySnapshotCreateInfoEXT ; это не требует указания какой-либо структуры конфигурации при создании пространственного контекста. (Добавлено расширением XR_ANDROID_spatial_discovery_bounds )

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

Среда выполнения поддерживает фильтр XrSpatialBoundsBoxfANDROID для XrSpatialDiscoverySnapshotCreateInfoEXT ; это не требует указания какой-либо структуры конфигурации при создании пространственного контекста. (Добавлено расширением XR_ANDROID_spatial_discovery_bounds )

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

Среда выполнения поддерживает фильтр XrSpatialBoundsFrustumfANDROID для XrSpatialDiscoverySnapshotCreateInfoEXT ; это не требует указания какой-либо структуры конфигурации при создании пространственного контекста. (Добавлено расширением XR_ANDROID_spatial_discovery_bounds )

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

Среда выполнения поддерживает автоматическое определение физического размера обнаруженных и отслеживаемых изображений. Соответствующая структура конфигурации — XrSpatialImageSizeEXT (добавлена ​​расширением XR_EXT_spatial_image_tracking ).

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

Среда выполнения поддерживает XrSpatialImageStaticOptimizationEXT . Соответствующая структура конфигурации: XrSpatialImageStaticOptimizationEXT . (Добавлено расширением XR_EXT_spatial_image_tracking )

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

Среда выполнения поддерживает XrSpatialImageSizeEXT . Соответствующая структура конфигурации: XrSpatialImageSizeEXT (добавлена ​​расширением XR_EXT_spatial_image_tracking ).

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

Функция отслеживания герметичной сетки окружающей среды. Соответствующая структура конфигурации: XrSpatialFeatureTrackWatertightMeshEXT . (Добавлено расширением XR_EXT_spatial_mesh_tracking )

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

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

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

  • instance — это дескриптор объекта XrInstance .
  • systemId — это XrSystemId , для которого будут перечислены пространственные характеристики.
  • capability — это XrSpatialCapabilityEXT , для которого будут перечислены функции.
  • capabilityFeatureCapacityInput — это емкость массива, или 0, указывающее на запрос на получение требуемой емкости.
  • capabilityFeatureCountOutput — это количество функций или требуемая мощность в случае, если capabilityFeatureCapacityInput недостаточна.
  • capabilityFeatures — это массив объектов XrSpatialCapabilityFeatureEXT . Он может быть NULL если capabilityFeatureCapacityInput равен 0.
  • Подробное описание получения необходимого размера capabilityFeatures см. в разделе « Параметры размера буфера» .

Приложение определяет поддерживаемые данной системой функции для XrSpatialCapabilityEXT , используя xrEnumerateSpatialCapabilityFeaturesEXT .

Для возможностей, имеющих доступные функции, приложение выбирает функцию или функции для включения и предоставляет соответствующую структуру конфигурации в следующей цепочке структур конфигурации возможностей в XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Если capability не входит в список параметров xrEnumerateSpatialCapabilitiesEXT , среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

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

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

  • Расширение XR_EXT_spatial_entity необходимо включить перед вызовом функции xrEnumerateSpatialCapabilityFeaturesEXT.
  • instance должен быть допустимым дескриптором XrInstance.
  • Значение capability должно быть допустимым значением XrSpatialCapabilityEXT.
  • capabilityFeatureCountOutput должен быть указателем на значение типа uint32_t
  • Если capabilityFeatureCapacityInput не равно 0 , capabilityFeatures должен быть указателем на массив значений capabilityFeatureCapacityInput XrSpatialCapabilityFeatureEXT.

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

Успех

  • XR_SUCCESS

Отказ

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

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

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

XR_DEFINE_HANDLE(XrSpatialContextEXT)

Дескриптор XrSpatialContextEXT представляет ресурсы для обнаружения и обновления определенного количества пространственных объектов в среде пользователя. Приложение может использовать этот дескриптор для обнаружения и обновления пространственных объектов с помощью других функций этого расширения.

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

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

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

  • session — это объект XrSession, в котором будет активен пространственный контекст.
  • createInfo — это объект XrSpatialContextCreateInfoEXT, используемый для указания параметров пространственного контекста.
  • future — это указатель на объект XrFutureEXT .

Приложение может создать дескриптор XrSpatialContextEXT следующим образом:

Если значение XrSpatialContextCreateInfoEXT ::capabilityConfigCount равно 0, среда выполнения должна возвращать XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT Дескриптор пространственного контекста должен содержать как минимум одну возможность.

Если какая-либо возможность из массива XrSpatialContextCreateInfoEXT :: capabilityConfigs не перечисляется функцией xrEnumerateSpatialCapabilitiesEXT , среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT .

Если значение XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount в XrSpatialContextCreateInfoEXT :: capabilityConfigs равно 0, среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT Конфигурация возможностей считается неполной без списка типов компонентов, которые необходимо включить для данной возможности.

Если какой-либо тип компонента, указанный в XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents не перечисляется для XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability в xrEnumerateSpatialCapabilityComponentTypesEXT , среда выполнения должна вернуть XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT .

Если какая-либо из структур в следующей цепочке XrSpatialContextCreateInfoEXT :: capabilityConfigs соответствует XrSpatialCapabilityFeatureEXT , которая не перечислена для данной возможности в xrEnumerateSpatialCapabilityFeaturesEXT , среда выполнения должна игнорировать эту структуру XrSpatialCapabilityFeatureEXT .

Если структура XrSpatialContextCreateInfoEXT :: capabilityConfigs содержит несколько структур с одинаковым значением XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability , среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT .

Для обеспечения оптимального использования системных ресурсов среда выполнения может использовать конфигурации, предоставленные в массиве XrSpatialContextCreateInfoEXT, для подготовки к обработке пространственных запросов. Например, среда выполнения, поддерживающая отслеживание плоскости, может начать свой конвейер отслеживания плоскости только в том случае, если приложение создаст дескриптор пространственного контекста, содержащий возможность отслеживания плоскости. Если настроенные возможности имеют длительное время подготовки, вызовы xrCreateSpatialDiscoverySnapshotAsyncEXT могут привести к созданию пустого снимка. Приложение может дождаться завершения вызова XrEventDataSpatialDiscoveryRecommendedEXT перед использованием xrCreateSpatialDiscoverySnapshotAsyncEXT , чтобы убедиться, что базовые службы отслеживания подготовились.

Если среда выполнения использует систему разрешений для управления доступом приложения к пространственным возможностям, настраиваемым для XrSpatialContextEXT , то среда выполнения должна вернуть XR_ERROR_PERMISSION_INSUFFICIENT если эти разрешения не были предоставлены данному приложению.

Эта функция запускает асинхронную операцию и создает соответствующий объект XrFutureEXT , который можно использовать с xrPollFutureEXT и связанными функциями. Возвращаемое значение этой функции указывает только на то, были ли параметры приемлемы для планирования асинхронной операции. Соответствующая функция завершения — xrCreateSpatialContextCompleteEXT , которую можно использовать, когда объект Future из этой функции находится в состоянии READY, а выходные данные заполняются этой функцией в структуре завершения XrCreateSpatialContextCompletionEXT .

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

  • Расширение XR_EXT_spatial_entity необходимо включить перед вызовом функции xrCreateSpatialContextAsyncEXT.
  • session должна быть действительным дескриптором XrSession.
  • createInfo должна быть указателем на допустимую структуру XrSpatialContextCreateInfoEXT.
  • future должен быть указателем на значение XrFutureEXT

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

Успех

  • 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_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

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

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

Структура XrSpatialContextCreateInfoEXT описывает информацию, необходимую для создания дескриптора XrSpatialContextEXT .

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

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

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

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

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • capability представляет собой XrSpatialCapabilityEXT .
  • enabledComponentCount — это тип uint32_t , описывающий количество элементов в массиве enabledComponents .
  • enabledComponents — это указатель на массив XrSpatialComponentTypeEXT .

Если capability xrEnumerateSpatialCapabilitiesEXT не перечисляется в параметре xrEnumerateSpatialCapabilitiesEXT, среда выполнения должна вернуть XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT . Если какой-либо тип компонента, указанный в enabledComponents , не перечисляется для capability xrEnumerateSpatialCapabilityComponentTypesEXT , среда выполнения должна вернуть XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT .

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

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

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

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

Функция xrCreateSpatialContextCompleteEXT завершает асинхронную операцию, начатую функцией xrCreateSpatialContextAsyncEXT . Если future не находится в состоянии готовности, среда выполнения должна вернуть XR_ERROR_FUTURE_PENDING_EXT . Если future уже завершен или отменен, среда выполнения должна вернуть XR_ERROR_FUTURE_INVALID_EXT .

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

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

Успех

  • 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

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

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • futureResult — это объект XrResult, полученный в результате операции создания пространственного контекста.
  • spatialContext — это объект XrSpatialContextEXT , созданный с использованием данных и конфигурации в xrCreateSpatialContextAsyncEXT :: createInfo .

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

Значения 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_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

Если futureResult — код успешного выполнения, spatialContext должен быть действительным. Если spatialContext действителен, он остается таковым только в течение жизненного цикла xrCreateSpatialContextAsyncEXT :: session или до тех пор, пока приложение не уничтожит spatialContext с помощью xrDestroySpatialContextEXT , в зависимости от того, что произойдет раньше.

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

Разрушьте пространственный контекст.

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

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

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

The application can call xrDestroySpatialContextEXT function to release the spatialContext handle and the underlying resources when finished with spatial entity discovery and update tasks. If there is no other valid XrSpatialContextEXT that was created with the same spatial capabilities as spatialContext , this call serves as a suggestion to the runtime to disable the tracking services required for those capabilities to save system resources.

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

Thread Safety

  • Access to spatialContext , and any child handles, must be externally synchronized

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

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Spatial Entity Representations

Spatial Entity ID 

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT is used to represent any kind of entity discovered by the runtime in the spatial environment of the user. An XrSpatialEntityIdEXT is valid for the XrSpatialContextEXT in which it is discovered, and the runtime must not reuse the same XrSpatialEntityIdEXT for different entities within the same XrSpatialContextEXT . Also, the runtime must not reuse the same XrSpatialEntityIdEXT across multiple XrSpatialContextEXT within the same XrSession regardless of whether it represents the same entity or different ones. 

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT is a reserved value representing an invalid XrSpatialEntityIdEXT . It may be passed to and returned from API functions only when specifically allowed.

Spatial Entity Handle 

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

The XrSpatialEntityEXT handle represents a spatial entity. An application can create such a handle to express its interest in a specific entity to the runtime.

Create Spatial Entity Handle from ID

The xrCreateSpatialEntityFromIdEXT function is defined as: 

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

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

The application can use xrCreateSpatialEntityFromIdEXT to create an XrSpatialEntityEXT handle which is a reference to an entity that exists in the user's environment.

The runtime must return XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT if XrSpatialEntityFromIdCreateInfoEXT :: entityId is not a valid ID for spatialContext .

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

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

Успех

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

The XrSpatialEntityFromIdCreateInfoEXT structure is defined as: 

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • entityId is the XrSpatialEntityIdEXT of the entity that the application wants to create a handle for.

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

Destroy Spatial Entity Handle

The xrDestroySpatialEntityEXT function is defined as: 

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

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

The application can use xrDestroySpatialEntityEXT to release the spatialEntity handle when it is no longer interested in the entity referenced by this handle.

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

Thread Safety

  • Access to spatialEntity , and any child handles, must be externally synchronized

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

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Spatial Snapshot 

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

The application can create spatial snapshots for the purpose of discovering spatial entities or for updating its information about known spatial entities. The XrSpatialSnapshotEXT handle represents the immutable data for the discovered or updated spatial entities and a subset of their components as selected by the application. The spatial snapshot represents a coherent view of the entities and their component data. Once a snapshot is created, the snapshot's data must remain constant while the snapshot is valid.

The application can create any number of snapshots it wants but must be mindful of the memory being allocated for each new snapshot and must destroy the snapshots once it no longer needs them.

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

The xrCreateSpatialDiscoverySnapshotAsyncEXT function is defined as: 

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

The application can discover spatial entities by creating a discovery snapshot by using xrCreateSpatialDiscoverySnapshotAsyncEXT .

This function starts an asynchronous operation and creates a corresponding XrFutureEXT , usable with xrPollFutureEXT and related functions. The return value of this function only indicates whether the parameters were acceptable to schedule the asynchronous operation. The corresponding completion function is xrCreateSpatialDiscoverySnapshotCompleteEXT , usable when a future from this function is in the READY state, with outputs populated by that function in the completion structure XrCreateSpatialDiscoverySnapshotCompletionEXT .

The application can submit multiple discovery snapshot creation requests without needing to wait for the previous one to be completed. The runtime may process and complete the snapshot creation in any order. The runtime may delay the completion of the discovery snapshot creation to throttle the application if it needs to reduce the use of system resources due to power, thermal or other policies of the device.

The application can use XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes to filter the list of entities and the components whose data the runtime must include in the snapshot. If the application provides a valid list of spatial component types in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , then the runtime must only include spatial entities in the snapshot that have at least one of the components provided in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Also, the runtime must only include data for only those components in the snapshot.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT if any of the XrSpatialComponentTypeEXT in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes are not enabled for the spatial capabilities passed to XrSpatialContextCreateInfoEXT :: capabilityConfigs when creating spatialContext .

If the application does not provide a list of spatial component types in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , the runtime must include all the spatial entities in the snapshot that have the set of components which are enumerated in XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents for the capabilities configured for spatialContext . The runtime must include the data for all the enabled components of the capabilities configured for spatialContext .

If XrEventDataReferenceSpaceChangePending is queued before the completion of future , and XrEventDataReferenceSpaceChangePending :: poseValid is false, then the runtime may either create an XrSpatialSnapshotEXT that has no entities in it or set the XrSpatialEntityTrackingStateEXT of the entities that are no longer locatable in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace at XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time to XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . The runtime must not set XrCreateSpatialContextCompletionEXT :: futureResult to an error code because of XrEventDataReferenceSpaceChangePending .

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

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

Успех

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

The XrSpatialDiscoverySnapshotCreateInfoEXT structure is defined as: 

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT .

The XrSpatialDiscoverySnapshotCreateInfoEXT structure describes the information to create an XrSpatialSnapshotEXT handle when discovering spatial entities.

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

The xrCreateSpatialDiscoverySnapshotCompleteEXT function is defined as: 

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

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

xrCreateSpatialDiscoverySnapshotCompleteEXT completes the asynchronous operation started by xrCreateSpatialDiscoverySnapshotAsyncEXT . The runtime must return XR_ERROR_FUTURE_PENDING_EXT if XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future is not in ready state. The runtime must return XR_ERROR_FUTURE_INVALID_EXT if XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future has already been completed or cancelled.

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

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

Успех

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

The XrCreateSpatialDiscoverySnapshotCompletionInfoEXT structure is defined as: 

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

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

The locations in the various component data included in the created snapshot will be represented in baseSpace , located at time .

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

The XrCreateSpatialDiscoverySnapshotCompletionEXT structure is defined as: 

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • futureResult is the XrResult of the spatial discovery snapshot creation operation.
  • snapshot is an XrSpatialSnapshotEXT which can be used to query the component data of the discovered spatial entities.

Future Return Codes

futureResult values:

Успех

  • 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

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

Discovery Recommendation Event

The XrEventDataSpatialDiscoveryRecommendedEXT structure is defined as: 

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • spatialContext is the XrSpatialContextEXT for which discovery is being recommended by the runtime.

The application can retrieve this event by using xrPollEvent . The application can avoid excessive calls to xrCreateSpatialDiscoverySnapshotAsyncEXT to discover spatial entities by waiting for this event. If the application creates multiple discovery snapshots with the same XrSpatialDiscoverySnapshotCreateInfoEXT between two XrEventDataSpatialDiscoveryRecommendedEXT events, the resultant snapshots may contain the same entities and therefore the snapshot creation and data queries would be wasteful.

Waiting for this event to create a new discovery snapshot ensures that the application is not overloading the system with discovery requests for which the runtime may not return any new data and helps avoid the risk of overusing the system resources, and getting throttled due to power or thermal policies of the device. This also helps create parity between runtimes that are discovering spatial entities on the fly with live tracking and runtimes which are providing spatial entities off of a previously recorded state (where the runtime may queue the discovery recommendation event only once for each XrSpatialContextEXT ).

The runtime must not queue this event for notifying the application about changes or adjustments made to the component data of existing spatial entities. The application can use the xrCreateSpatialUpdateSnapshotEXT to keep track of component data updates for the spatial entities it is interested in.

A runtime may queue a discovery recommendation event without waiting for the application to first call xrCreateSpatialDiscoverySnapshotAsyncEXT . For example, a runtime may base the decision of queueing the discovery recommendation event on the configuration of the XrSpatialContextEXT , its own understanding of the environment around the user (discovery of new entities or loss of existing ones), or for hinting an appropriate discovery request cadence to the application so as not to overload the system resources. The runtime may choose to never queue this event for an XrSpatialContextEXT if no entities are found in the user's environment throughout the lifetime of that XrSpatialContextEXT .

The runtime must not queue this event for a given spatialContext until the application completes its creation by using xrCreateSpatialContextCompleteEXT .

After the application calls xrDestroySpatialContextEXT , the runtime must not queue any more discovery recommendation events for that spatial context nor return any such events for that context from xrPollEvent .

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

Query Component Data

The xrQuerySpatialComponentDataEXT function is defined as: 

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

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

The application can use xrQuerySpatialComponentDataEXT to query the component data of the entities in the snapshot by attaching a list structure to XrSpatialComponentDataQueryResultEXT :: next corresponding to each XrSpatialComponentTypeEXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

If the application attaches a list structure to XrSpatialComponentDataQueryResultEXT :: next that does not correspond to any of the components listed in XrSpatialComponentDataQueryConditionEXT :: componentTypes , the runtime must return XR_ERROR_VALIDATION_FAILURE .

The application can choose to attach the list structures corresponding to only a subset of components listed in XrSpatialComponentDataQueryConditionEXT :: componentTypes . The application can choose to omit the list structures altogether if it only wishes to know the ids and tracking state of the spatial entities that satisfy the queryCondition . The runtime must not treat the absence of list structures from the XrSpatialComponentDataQueryResultEXT :: next chain as a failure.

If XrEventDataReferenceSpaceChangePending is queued and XrEventDataReferenceSpaceChangePending :: changeTime elapsed while the application is querying component data from an XrSpatialSnapshotEXT , the application may use the event data to adjust the poses accordingly.

The runtime must populate XrSpatialComponentDataQueryResultEXT :: entityIds only with entities that have all the components specified in XrSpatialComponentDataQueryConditionEXT :: componentTypes . If XrSpatialComponentDataQueryConditionEXT :: componentTypeCount is 0, the runtime must populate queryResult with all the entities (and their tracking states) that are in the snapshot. If additional query conditions are added to XrSpatialComponentDataQueryConditionEXT :: next , the runtime must treat those as an "AND" with the component types availability ie the runtime must populate XrSpatialComponentDataQueryResultEXT ::entityIds only with entities that satisfy all of the provided conditions. The runtime must populate the component data in the list structures in the same order as the entities in XrSpatialComponentDataQueryResultEXT :: entityIds ie the component data at a given index in the list structure array must correspond to the entity at the same index.

If the tracking state for an entity is not XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT , the runtime must not change the data at the index corresponding to that entity in the array contained in the list structures attached to XrSpatialComponentDataQueryResultEXT .

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

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

As an example the application creates an XrSpatialSnapshotEXT which contains 5 entities, where -

  • Entity 1 and 2 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Entity 3 and 4 have components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
  • Entity 5 has components XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

Да

Да

Да

Да

Нет

Нет

Нет

Нет

Да

Да

Родитель

Родитель

Да

Да

Да

Да

Нет

Нет

Нет

Нет

Нет

Нет

Mesh3D

Mesh3D

Нет

Нет

Нет

Нет

Да

Да

Да

Да

Да

Да

Bounded3D

Bounded3D

Нет

Нет

Нет

Нет

Да

Да

Да

Да

Нет

No Text is not SVG - cannot display

Figure 20. Example snapshot

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT listed in the query condition will result in entity #1, #2, and #5 being returned to the application and the application can attach an array of XrSpatialBounded2DDataEXT as part of the XrSpatialComponentBounded2DListEXT structure to the next chain of XrSpatialComponentDataQueryResultEXT to get the bounded2D data.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

Data for entityId #1

Data for entit...

Data for entityId #2

Data for entit...

Data for entityId #5

Data for entit...

entityIds

entityIds

следующий

следующий

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Dat...

границы

границы

XrSpatialComponent Bounded2DListEXT

XrSpatialComponent Bou... Text is not SVG - cannot display

Figure 21. Example query result

xrQuerySpatialComponentDataEXT on the above snapshot with XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT components listed in the query condition will result in entity #3 and #4 being returned to the application and the application can attach arrays of XrBoxf and XrSpatialMeshDataEXT as part of the XrSpatialComponentBounded3DListEXT and XrSpatialComponentMesh3DListEXT structures respectively to the next chain of XrSpatialComponentDataQueryResultEXT to get the component data.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Data for entityId #3

Data for entit...

Data for entityId #4

Data for entit...

Mesh3D

Mesh3D

Data for entityId #3

Data for entit...

Data for entityId #4

Data for entit...

entityIds

entityIds

следующий

следующий

XrSpatialComponent DataQueryResultEXT

XrSpatialComponent Da...

границы

границы

следующий

следующий

XrSpatialComponent Bounded3DListEXT

XrSpatialComponent Bo...

XrSpatialComponent Mesh3DListEXT

XrSpatialComponent Me...

сетки

meshes Text is not SVG - cannot display

Figure 22. Example query result

The XrSpatialComponentDataQueryConditionEXT structure is defined as: 

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT for which to get the data from the snapshot.

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

The XrSpatialComponentDataQueryResultEXT structure is defined as: 

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • entityIdCapacityInput is the capacity of the entityIds array, or 0 to indicate a request to retrieve the required capacity.
  • entityIdCountOutput is the number of XrSpatialEntityIdEXT in entityIds , or the required capacity in the case that entityIdCapacityInput is insufficient.
  • entityIds is an array of XrSpatialEntityIdEXT . It can be NULL if entityIdCapacityInput is 0.
  • entityStateCapacityInput is the capacity of the entityStates array, or 0 to indicate a request to retrieve the required capacity.
  • entityStateCountOutput is the number of XrSpatialEntityTrackingStateEXT in entityStates , or the required capacity in the case that entityStateCapacityInput is insufficient. This must always be the same as entityIdCountOutput .
  • entityStates is an array of XrSpatialEntityTrackingStateEXT . It can be NULL if entityStateCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required entityIds size.

An application can use the entityIds with xrCreateSpatialEntityFromIdEXT to create XrSpatialEntityEXT handles for the entities it is interested in getting regular updates for. The application can then use these XrSpatialEntityEXT handles with xrCreateSpatialUpdateSnapshotEXT to create an update snapshot that has the runtime's latest known data of the components for the provided entities.

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

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

The XrSpatialEntityTrackingStateEXT enumerates the possible spatial entity tracking states:

The enums have the following meanings:

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

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

The runtime has stopped tracking this entity and will never resume tracking it.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

The runtime has paused tracking this entity but may resume tracking it in the future.

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

The runtime is currently tracking this entity and its component data is valid.

ОТСЛЕЖИВАНИЕ

ПАУЗА

ОСТАНОВЛЕНО

Figure 23. XrSpatialEntityTrackingStateEXT

  • The runtime may change the state of the spatial entity from XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT if it suspends the tracking of that spatial entity but has the possibility of resuming its tracking in the future. Some examples of when the runtime may do this include (but not limited to) if the application loses input focus; or if the given spatial entity is too far from the user to be accurately tracked; or if there are too many entities being tracked and the runtime wants to reduce the cost of tracking. XrSpatialEntityTrackingStateEXT helps the application insulate itself from the different tracking policies of each runtime.
  • The runtime may change the state of an entity from XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • The runtime must change the state of the spatial entity from XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT if the spatial entity is lost and its tracking will never be recovered or resumed. An example of such a case would be if the device loses tracking, restarts its tracking session but is unable to relocalize in its environment, and therefore treats discovered entities of this tracking session as new entities.
  • Once the tracking state of an entity is set to XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , the runtime must never change it any other state.
  • When querying the component data of a spatial entity using xrQuerySpatialComponentDataEXT , the runtime must set valid data in the contents of the buffers provided by the application in the next chain of XrSpatialComponentDataQueryResultEXT if the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . If the entity state is XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT or XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , the runtime must not change the content of the buffers.

Two-call idiom for component data

The XrSpatialBufferEXT structure is defined as: 

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

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

  • bufferId the XrSpatialBufferIdEXT of the buffer data.
  • bufferType is the XrSpatialBufferTypeEXT to indicate the type of data in bufferId . The application can use bufferType to determine which function to use to retrieve the actual data of the buffer.

Some spatial components have variable-sized data and therefore require using the two-call idiom to retrieve their data. In such cases, the spatial component data structure provides an XrSpatialBufferEXT for each variable sized buffer needed in that component's data.

For the same bufferId , the runtime must provide the same data from one component data query to another, even across one snapshot to another. A different bufferId between component data query calls indicates to the application that the data for that component may have changed.

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

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT is used to represent any kind of variable sized data for a spatial component.

The runtime must keep the XrSpatialBufferIdEXT and its data in memory for at least the lifecycle of the XrSpatialSnapshotEXT that contains it. The runtime may keep the XrSpatialBufferIdEXT and its data in memory for longer than the lifecycle of the XrSpatialSnapshotEXT in order to return the same ID as part of snapshots created later on by the application. For the same XrSpatialBufferIdEXT , the runtime must always return the same data via the appropriate xrGetSpatialBuffer* function. 

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

The XrSpatialBufferTypeEXT enumeration identifies the different data types of the buffer represented XrSpatialBufferIdEXT .

Enumerant Descriptions

The xrGetSpatialBufferStringEXT function is defined as: 

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

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

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of characters, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of char . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_STRING_EXT by using xrGetSpatialBufferStringEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

buffer filled by the runtime must be a null-terminated UTF-8 string.

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

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferStringEXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput char values

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferUint8EXT function is defined as: 

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

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

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint8_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT8_EXT by using xrGetSpatialBufferUint8EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

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

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint8EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint8_t values

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferUint16EXT function is defined as: 

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

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

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint16_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT16_EXT by using xrGetSpatialBufferUint16EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

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

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint16EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint16_t values

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferUint32EXT function is defined as: 

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

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

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of uint32_t . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_UINT32_EXT by using xrGetSpatialBufferUint32EXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

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

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferUint32EXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput uint32_t values

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferFloatEXT function is defined as: 

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

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

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of float . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT by using xrGetSpatialBufferFloatEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

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

  • The XR_EXT_spatial_entity extension must be enabled prior to calling xrGetSpatialBufferFloatEXT
  • snapshot must be a valid XrSpatialSnapshotEXT handle
  • info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
  • bufferCountOutput must be a pointer to a uint32_t value
  • If bufferCapacityInput is not 0 , buffer must be a pointer to an array of bufferCapacityInput float values

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferVector2fEXT function is defined as: 

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

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

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of XrVector2f . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT by using xrGetSpatialBufferVector2fEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

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

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The xrGetSpatialBufferVector3fEXT function is defined as: 

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

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

  • snapshot is a handle to an XrSpatialSnapshotEXT .
  • info holds the information on the buffer to query.
  • bufferCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity.
  • bufferCountOutput is the number of elements in the buffer array, or the required capacity in the case that bufferCapacityInput is insufficient.
  • buffer is an array of XrVector3f . It can be NULL if bufferCapacityInput is 0.
  • See the Buffer Size Parameters section for a detailed description of retrieving the required buffer size.

The application can get the data for an XrSpatialBufferEXT provided by a component, where XrSpatialBufferEXT :: bufferType is XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT by using xrGetSpatialBufferVector3fEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE if the XrSpatialBufferTypeEXT for XrSpatialBufferGetInfoEXT :: bufferId is not XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

The runtime must return XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT if XrSpatialBufferGetInfoEXT :: bufferId does not belong to snapshot .

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

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

Успех

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
  • XR_ERROR_VALIDATION_FAILURE

The XrSpatialBufferGetInfoEXT structure is defined as: 

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • bufferId an XrSpatialBufferIdEXT for the buffer whose data to retrieve.

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

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT is a reserved value representing an invalid XrSpatialBufferIdEXT . It may be passed to and returned from API functions only when specifically allowed.

Create Update Snapshot

The xrCreateSpatialUpdateSnapshotEXT function is defined as: 

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

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

The application can use xrCreateSpatialUpdateSnapshotEXT to create a snapshot and get the latest component data for specific entities as known by the runtime. Applications can provide the XrSpatialEntityEXT handles and the component types they are interested in when creating the snapshot.

The application can use XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes to filter the list of components whose data must be included in the snapshot. If the application provides a valid list of spatial component types in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , then the runtime must only include spatial entities in the snapshot that have at least one of the components provided in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Also, the runtime must only include data for those components in the snapshot.

The runtime must return XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT if any of the XrSpatialComponentTypeEXT in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes are not enabled for the spatial capabilities passed to XrSpatialContextCreateInfoEXT :: capabilityConfigs when creating spatialContext .

If the application does not provide a list of spatial component types in XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes , the runtime must include all the spatial entities listed in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in the snapshot and it must include the data for all the enabled components of the capabilities configured for spatialContext .

The runtime must not include spatial entities that are not listed in XrSpatialUpdateSnapshotCreateInfoEXT :: entities in snapshot .

The application can create any number of snapshots it wants but must be mindful of the memory being allocated for each new snapshot and must destroy the snapshots once it no longer needs them.

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

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

Успех

  • 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_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

The XrSpatialUpdateSnapshotCreateInfoEXT structure is defined as: 

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • entityCount is a uint32_t describing the count of elements in the entities array.
  • entities is an array of XrSpatialEntityEXT for which the runtime must include the component data in the snapshot.
  • componentTypeCount is a uint32_t describing the count of elements in the componentTypes array.
  • componentTypes is an array of XrSpatialComponentTypeEXT for which the runtime must include the data in the snapshot.
  • baseSpace is the XrSpace relative to which all the locations of the update XrSpatialSnapshotEXT will be located.
  • time is the XrTime at which all the locations of the update XrSpatialSnapshotEXT will be located.

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

Destroy snapshot

The xrDestroySpatialSnapshotEXT function is defined as: 

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

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

The application can call xrDestroySpatialSnapshotEXT to destroy the XrSpatialSnapshotEXT handle and the resources associated with it.

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

Thread Safety

  • Access to snapshot , and any child handles, must be externally synchronized

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

Успех

  • XR_SUCCESS

Отказ

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Common Components

Ограниченное 2D

Component data

The XrSpatialBounded2DDataEXT structure is defined as: 

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

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

  • center is an XrPosef defining the geometric center of the bounded 2D component.
  • extents is extents of the bounded 2D component along the x-axis (extents.width), y-axis (extents.height), centered on center .

The extents of the XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT refer to the entity's size in the xy plane of the plane's coordinate system. A plane with a position of {0, 0, 0}, rotation of {0, 0, 0, 1} (no rotation), and an extent of {1, 1} refers to a 1 meter x 1 meter plane centered at {0, 0, 0} with its front face normal vector pointing towards the +Z direction in the component's space.

XXYYZZ Height Height YYZZXX Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

Figure 24. Bounded2D Component Coordinate System

Примечание

OpenXR uses an XY plane with +Z as the plane normal but other APIs may use an XZ plane with +Y as the plane normal. The XY plane can be converted to an XZ plane by rotating -π/2 radians around the +X axis.

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

Component list structure to query data

The XrSpatialComponentBounded2DListEXT structure is defined as: 

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • boundCount is a uint32_t describing the count of elements in the bounds array.
  • bounds is an array of XrSpatialBounded2DDataEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentBounded2DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if boundCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialDiscoverySnapshotCompleteEXT , then the runtime must provide XrSpatialBounded2DDataEXT :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace and XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialUpdateSnapshotEXT , then the runtime must provide XrSpatialBounded2DDataEXT :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace and XrSpatialUpdateSnapshotCreateInfoEXT :: time .

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

Конфигурация

If XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum value in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Bounded 3D

Component data

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT uses XrBoxf for its data.

Component list structure to query data

The XrSpatialComponentBounded3DListEXT structure is defined as: 

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • boundCount is a uint32_t describing the count of elements in the bounds array.
  • bounds is an array of XrBoxf .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentBounded3DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if boundCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialDiscoverySnapshotCompleteEXT , then the runtime must provide XrBoxf :: center in XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace at XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

If xrQuerySpatialComponentDataEXT :: snapshot was created from xrCreateSpatialUpdateSnapshotEXT , then the runtime must provide XrBoxf :: center in XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace at XrSpatialUpdateSnapshotCreateInfoEXT :: time .

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

Конфигурация

If XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Родитель

Component data

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT uses XrSpatialEntityIdEXT for its data.

Component list structure to query data

The XrSpatialComponentParentListEXT structure is defined as: 

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

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

  • type — это XrStructureType данной структуры.
  • next равно NULL или указателю на следующую структуру в цепочке структур. В ядре OpenXR и в этом расширении такие структуры не определены.
  • parentCount is a uint32_t describing the count of elements in the parents array.
  • parents is an array of XrSpatialEntityIdEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentParentListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if parentCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

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

Конфигурация

If XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list. This component does not require any special configuration to be included in the next chain of XrSpatialCapabilityConfigurationBaseHeaderEXT .

Mesh 3D

Component data

The XrSpatialMeshDataEXT structure is defined as: 

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

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

  • origin is an XrPosef defining the origin of the mesh. All vertices of the mesh must be relative to this origin.
  • vertexBuffer is an XrSpatialBufferEXT that provides the ID for a buffer that represents the vertex buffer of the entity this component is on. The position of vertices must be relative to origin .
  • indexBuffer is an XrSpatialBufferEXT that provides the ID for a buffer that represents an array of triangle indices, specifying the indices of the mesh vertices in the vertexBuffer . The triangle indices must be returned in counter-clockwise order and three indices denote one triangle.

The component type using XrSpatialMeshDataEXT must specify the XrSpatialBufferTypeEXT of the vertexBuffer and indexBuffer .

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

Component list structure to query data

The XrSpatialComponentMesh3DListEXT structure is defined as: 

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • meshCount is a uint32_t describing the count of elements in the meshes array.
  • meshes is an array of XrSpatialMeshDataEXT .

The application can query the mesh 3D component of the spatial entities in an XrSpatialSnapshotEXT by adding XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT in XrSpatialComponentDataQueryConditionEXT :: componentTypes and adding XrSpatialComponentMesh3DListEXT to the next pointer chain of XrSpatialComponentDataQueryResultEXT .

The runtime must return XR_ERROR_VALIDATION_FAILURE from xrQuerySpatialComponentDataEXT if XrSpatialComponentMesh3DListEXT is in the next chain of XrSpatialComponentDataQueryResultEXT :: next but XrSpatialComponentDataQueryConditionEXT ::componentTypeCount is not zero and XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT is not included in XrSpatialComponentDataQueryConditionEXT :: componentTypes .

The runtime must return XR_ERROR_SIZE_INSUFFICIENT from xrQuerySpatialComponentDataEXT if meshCount is less than XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

For the XrSpatialMeshDataEXT filled out by the runtime in the meshes array, the XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: vertexBuffer must be XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT and XrSpatialBufferEXT :: bufferType for XrSpatialMeshDataEXT :: indexBuffer must be XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

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

Конфигурация

If XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT is enumerated in XrSpatialCapabilityComponentTypesEXT :: componentTypes for some capability, the application can enable it by including the enum in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents list of the XrSpatialCapabilityConfigurationBaseHeaderEXT derived structure of the capability that supports this component.

Для включения этого компонента в следующую цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT не требуется никакой специальной конфигурации.

Tracking state filters

The XrSpatialFilterTrackingStateEXT structure is defined as: 

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

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

  • type — это XrStructureType данной структуры.
  • next — это NULL или указатель на следующую структуру в цепочке структур.
  • trackingState is the XrSpatialEntityTrackingStateEXT for which the application wants to apply the filter.

The application can use XrSpatialFilterTrackingStateEXT in the next chain of XrSpatialDiscoverySnapshotCreateInfoEXT to scope the discovery to only those entities whose tracking state is trackingState .

The application can use XrSpatialFilterTrackingStateEXT in the next chain of XrSpatialComponentDataQueryConditionEXT to scope the component data query from a snapshot only to entities whose tracking state is trackingState .

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

Пример кода

Использование приложения

Applications typically use the spatial entity extension in the following pattern:

Discover spatial entities & query component data

The following example code demonstrates how to discover spatial entities for capability "Foo" query its component data. 

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

auto waitUntilReady = [](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&fooConfig));

  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));

  waitUntilReady(createContextFuture);

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

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components.
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT future = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Query buffer data

The following example code demonstrates how to get the data of a component that provides an XrSpatialBufferEXT . 

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
queryResult.entityIdCapacityInput = entityIds.size();
queryResult.entityIds = entityIds.data();

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

CHK_XR(xrQuerySpatialComponentDataEXT(snapshot, &queryCond, &queryResult));

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

Extension guidelines

  • If an extension is defining a new XrSpatialComponentTypeEXT which provides additional data about a spatial entity,

  • Extensions can define structures that extend XrSpatialDiscoverySnapshotCreateInfoEXT to provide additional filters for discovery. The filters for creating the snapshot must not affect the configuration of the spatial context, but instead are to be used to provide hints to the runtime on what entities and data are to be included in the snapshot as tracked by the current configuration of the spatial context (and therefore the current configuration of the underlying services).

  • If an extension defines a new XrSpatialCapabilityEXT ,

  • If an extension defines a new XrSpatialCapabilityFeatureEXT , it must also define a corresponding configuration structure that can be chained to the next pointer of XrSpatialCapabilityConfigurationBaseHeaderEXT , that the application can use to enable the feature when creating an XrSpatialContextEXT .

  • An extension defining a new XrSpatialCapabilityEXT should follow this template for the specification -

    • Обзор
    • Runtime support
    • Конфигурация
    • Guaranteed components
    • Пример кода

  • An extension defining a new XrSpatialComponentTypeEXT should follow this template for the specification -

    • Component data
    • Component list structure to query data
    • Конфигурация

  • When writing an api that provides the application with a XrSpatialBufferIdEXT , it must be accompanied with a XrSpatialBufferTypeEXT to inform the application what the data type of the buffer is and the application can use an appropriate xrGetSpatialBuffer* function to retrieve the actual contents of the buffer.

Semantic Label Design & Extension Guidelines

While this extension does not define any component for conveying the semantic label information of an entity, it lays down the design rules and guidelines for any extensions that do define such a component. In the following text, " should " and " must " constrain the authors of such functionality, rather than constraining a runtime implementation or an application using the API.

  • If an extension is defining semantic labels for any XrSpatialCapabilityEXT , it should do so by defining a new XrSpatialComponentTypeEXT as well as a new enumeration with a set of labels (a "semantic label set") to be the data for that component.
  • An enumeration representing a semantic label set must have a value to indicate that the entity is not categorized into any of the labels of this set. The name of this enumerant must include 'UNCATEGORIZED', eg XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT . This value indicates to applications that the runtime does recognize this entity, but that there are other semantic label sets where this entity is categorized.
  • Enumeration of this newly defined XrSpatialComponentTypeEXT in xrEnumerateSpatialCapabilityComponentTypesEXT implies that the runtime supports the semantic label set (and therefore the labels defined in the set) corresponding to that component type.
  • Applications express their desire to discover entities that have labels belonging to this semantic label set by including the corresponding XrSpatialComponentTypeEXT in the XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents array of the configuration struct for the capability that the component type is enumerated for.
  • It is possible that a single spatial entity has multiple components on it, each providing it with a label from their own semantic label set. Consider the following example with some hypothetical semantic label sets - XrSpatialObjectSemanticLabel , which might have values like chair, sofa, table etc., XrSpatialSofaBrand , which might have values like IKEA, Wayfair, etc., and XrSpatialIkeaSofa , which might have specific IKEA model names of sofas. In this scenario, the same sofa entity has all 3 components (labels from all 3 semantic label sets) on it, each giving a different granularity of information about the entity.
  • If an extension is defining a new XrSpatialComponentTypeEXT which provides a new semantic label set containing multiple labels in addition to the UNCATEGORIZED label, the extension should consider defining an XrSpatialCapabilityFeatureEXT which allows applications to activate only a subset of the labels defined in the semantic label set corresponding to that component type. This subset, provided in the next chain of the capability configuration, acts as a hint for runtimes to optimize their tracking pipelines and only track the subset provided. An example of such a feature struct is provided below .
  • Extensions must not add labels to existing semantic label set enumeration. They must instead define a new enumeration which contains equivalent enumerants with identical semantics and with values equal to those from the other set, in addition to the newly added enumerants. The specification of the newly defined semantic label set must also establish the mapping between the old label set and the new one. See example below .
Example Spatial Feature Definition for Semantic Label Subset 
// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;
Пример расширения пространственно-семантической метки 
typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

Consider the above example where an extension defines an enumeration XrSpatialExamplePlaneSemanticLabelExtensionEXT in order to extend the existing XrSpatialPlaneSemanticLabelEXT with values to represent doors and windows. The specification for the new enumeration must include text for the following form - 

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====

Новые макросы

New Base Types

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

New Object Types

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

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

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

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

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

  • Extending XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_CONTEXT_EXT
    • XR_OBJECT_TYPE_SPATIAL_ENTITY_EXT
    • XR_OBJECT_TYPE_SPATIAL_SNAPSHOT_EXT

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

    • XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
    • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
    • XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
    • XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT

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

    • XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
    • XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
    • XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT
    • XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
    • XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
    • XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT

Проблемы

  • Does a single entity always derive from solely a single capability?

    • Решено
    • Answer: No. It is completely upto the runtime based on its own tracking capabilities and how it wants to represent a detected entity. The spec does not prescribe any particular representation of spatial entity except for the guaranteed components of a given capability to set a minimum expectation. A runtime may be able to merge entities detected by separate capabilities and represent them as a single entity with the guaranteed components of all the capabilities that helped identify it. An example of this could be that tables can be detected by both a plane tracking capability and an object tracking capability, with plane tracking providing the XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT component on the entity and object tracking providing XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT . A certain runtime may provide the table as 2 separate entities, each with their own set of guaranteed components, while certain runtimes may provide just 1 entity to represent the table, and have both XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT and XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT on the same entity. What is important to note here is that a given spatial entity can have at most a single component of any given component type . Therefore, if the component data produced by the different capabilities conflicts for a certain entity, the runtime must represent them as 2 separate entities.

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

  • Revision 1, 2024-04-12 (Nihav Jain, Google)

    • Initial extension description