XR_EXT_spatial_entity

Name String

XR_EXT_spatial_entity

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

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

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

741

Revision

1

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

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

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

XR_EXT_future

Авторы

Нихав Джайн (Nihav Jain), Google
Джаред Финдер (Jared Finder), Google
Натали Флери (Natalie Fleury), Meta
Юичи Тагучи (Yuichi Taguchi), Meta
Рон Бессемс (Ron Bessems), Meta
Инь Ли (Yin Li), Microsoft
Картик Кадаппан (Karthik Kadappan), Magic Leap
Джимми Алампарамбил (Jimmy Alamparambil), ByteDance
Чжипэн Лю (Zhipeng Liu), ByteDance
Цзюнь Янь (Jun Yan), 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_GEOMETRY_POINT_ANDROID = 1000803000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1 = 1000808000,
    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

Компонент, который предоставляет двухмерную сетку для пространственного объекта. Соответствующая структура списка – 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.

XR_SPATIAL_COMPONENT_TYPE_GEOMETRY_POINT_ANDROID

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

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_SCOPES_ANDROIDX1

Компонент, описывающий области хранения, в которых хранится объект. Если среда выполнения поддерживает XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT, она должна также поддерживать этот компонент. Соответствующая структура данных – XrSpatialBufferEXT . Структура соответствующего списка: XrSpatialComponentPersistenceScopeDataListANDROIDX1 . (Добавлено расширением XR_ANDROIDX1_spatial_anchor_cloud_sharing)

Возможности и настройка пространственного режима

Пространственные возможности определяют способность среды выполнения обнаруживать объекты, имеющие гарантированный набор компонентов. Приложения включают компоненты пространственной возможности при создании 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 для него.

Среда выполнения должна возвращать XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT, если capability не перечислено в xrEnumerateSpatialCapabilitiesEXT .

Среда выполнения не должна перечислять типы пространственных компонентов, расширение которых не включено для 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, выполнив следующие действия:

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

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

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

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

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

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

Чтобы обеспечить оптимальное использование системных ресурсов, среда выполнения может использовать конфигурации, указанные в массиве 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
  • XR_ERROR_TIME_INVALID (если включен параметр XR_ANDROID_spatial_annotation_tracking)

Структура 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 .

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

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

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

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

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

xrCreateSpatialContextCompleteEXT завершает асинхронную операцию, запущенную xrCreateSpatialContextAsyncEXT . Среда выполнения должна возвращать XR_ERROR_FUTURE_PENDING_EXT, если future не находится в состоянии готовности. Среда выполнения должна возвращать XR_ERROR_FUTURE_INVALID_EXT, если future уже завершено или отменено.

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

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

Выполнено

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

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

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

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrDestroySpatialContextEXT.
  • spatialContext должен быть действительным дескриптором XrSpatialContextEXT.

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

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

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

Выполнено

  • XR_SUCCESS

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Представления пространственных объектов

Идентификатор пространственного объекта

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

XrSpatialEntityIdEXT используется для представления любого типа объекта, обнаруженного средой выполнения в пространственной среде пользователя. XrSpatialEntityIdEXT действителен для XrSpatialContextEXT, в котором он обнаружен, и среда выполнения не должна повторно использовать один и тот же XrSpatialEntityIdEXT для разных объектов в одном и том же XrSpatialContextEXT . Кроме того, среда выполнения не должна повторно использовать один и тот же XrSpatialEntityIdEXT в нескольких XrSpatialContextEXT в рамках одного XrSession, независимо от того, представляет ли он один и тот же объект или разные.

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

XR_NULL_SPATIAL_ENTITY_ID_EXT – зарезервированное значение, представляющее недопустимый XrSpatialEntityIdEXT . Его можно передавать в функции API и получать из них только в том случае, если это явно разрешено.

Маркер пространственного объекта

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

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

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

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

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

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

Приложение может использовать xrCreateSpatialEntityFromIdEXT для создания дескриптора XrSpatialEntityEXT, который является ссылкой на объект, существующий в среде пользователя.

Среда выполнения должна возвращать XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT, если XrSpatialEntityFromIdCreateInfoEXT :: entityId не является действительным идентификатором для 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

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

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

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

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

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

Удалить дескриптор пространственного объекта

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

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

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

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

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrDestroySpatialEntityEXT.
  • spatialEntity должен быть действительным дескриптором XrSpatialEntityEXT.

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

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

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

Выполнено

  • XR_SUCCESS

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

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

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

Приложение может создавать пространственные снимки для обнаружения пространственных объектов или обновления информации об известных пространственных объектах. Дескриптор XrSpatialSnapshotEXT представляет неизменяемые данные для обнаруженных или обновленных пространственных объектов и подмножества их компонентов, выбранных приложением. Пространственный снимок представляет собой согласованное представление объектов и данных их компонентов. После создания снимка его данные должны оставаться неизменными, пока он действителен.

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

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

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

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

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

Приложение может обнаруживать пространственные объекты, создавая снимок обнаружения с помощью xrCreateSpatialDiscoverySnapshotAsyncEXT .

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

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

Приложение может использовать XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, чтобы отфильтровать список объектов и компонентов, данные которых среда выполнения должна включить в снимок. Если приложение предоставляет действительный список типов пространственных компонентов в XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, то среда выполнения должна включать в снимок только пространственные объекты, у которых есть хотя бы один из компонентов, указанных в XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes . Кроме того, среда выполнения должна включать данные только для тех компонентов, которые есть в снимке.

Среда выполнения должна возвращать XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT, если какие-либо из XrSpatialComponentTypeEXT в XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes не включены для пространственных возможностей, переданных в XrSpatialContextCreateInfoEXT :: capabilityConfigs при создании spatialContext .

Если приложение не предоставляет список типов пространственных компонентов в XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, среда выполнения должна включить в снимок все пространственные объекты, у которых есть набор компонентов, перечисленных в XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents для возможностей, настроенных для spatialContext . Среда выполнения должна включать данные для всех включенных компонентов возможностей, настроенных для spatialContext .

Если XrEventDataReferenceSpaceChangePending находится в очереди до завершения future и XrEventDataReferenceSpaceChangePending :: poseValid имеет значение false, то среда выполнения может либо создать XrSpatialSnapshotEXT, в котором нет объектов, либо установить XrSpatialEntityTrackingStateEXT объектов, которые больше не могут быть обнаружены в XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace в XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time, на XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT или XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . Среда выполнения не должна задавать для XrCreateSpatialContextCompletionEXT :: futureResult код ошибки из-за 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

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

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

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

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

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

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

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

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

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

xrCreateSpatialDiscoverySnapshotCompleteEXT завершает асинхронную операцию, запущенную xrCreateSpatialDiscoverySnapshotAsyncEXT . Среда выполнения должна возвращать XR_ERROR_FUTURE_PENDING_EXT, если XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future не находится в состоянии готовности. Среда выполнения должна возвращать XR_ERROR_FUTURE_INVALID_EXT, если XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future уже завершено или отменено.

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

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

Выполнено

  • 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

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

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

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • baseSpace – это XrSpace, в котором будут находиться все местоположения обнаруженного XrSpatialSnapshotEXT.
  • time – это XrTime, в котором будут находиться все местоположения обнаруженного XrSpatialSnapshotEXT.
  • future – это XrFutureEXT, полученный от xrCreateSpatialDiscoverySnapshotAsyncEXT.

Местоположения в различных компонентах данных, включенных в созданный снимок, будут представлены в baseSpace, расположенном в time .

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

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

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

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • futureResult – это XrResult операции по созданию снимка пространственного обнаружения.
  • snapshot – это XrSpatialSnapshotEXT, который можно использовать для запроса данных компонентов обнаруженных пространственных объектов.

Коды возврата в будущем

Значения в поле "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

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

Событие рекомендации в ленте рекомендаций

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

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

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

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

Приложение может получить это событие с помощью xrPollEvent . Приложение может избежать чрезмерного количества вызовов xrCreateSpatialDiscoverySnapshotAsyncEXT для обнаружения пространственных объектов, ожидая этого события. Если приложение создает несколько снимков обнаружения с одним и тем же XrSpatialDiscoverySnapshotCreateInfoEXT между двумя событиями XrEventDataSpatialDiscoveryRecommendedEXT, полученные снимки могут содержать одни и те же объекты, поэтому создание снимков и запросы данных будут неэффективными.

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

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

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

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

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

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

Данные компонента запроса

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

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

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

Приложение может использовать xrQuerySpatialComponentDataEXT, чтобы запрашивать данные компонентов объектов в снимке. Для этого нужно прикрепить структуру списка к XrSpatialComponentDataQueryResultEXT :: next, соответствующую каждому XrSpatialComponentTypeEXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Если приложение прикрепляет структуру списка к XrSpatialComponentDataQueryResultEXT :: next, которая не соответствует ни одному из компонентов, перечисленных в XrSpatialComponentDataQueryConditionEXT :: componentTypes, среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE .

Приложение может прикрепить структуры списков, соответствующие только подмножеству компонентов, перечисленных в XrSpatialComponentDataQueryConditionEXT :: componentTypes . Приложение может полностью опустить структуры списка, если ему нужно знать только идентификаторы и состояние отслеживания пространственных объектов, которые соответствуют queryCondition . Среда выполнения не должна считать ошибкой отсутствие структур списков в цепочке XrSpatialComponentDataQueryResultEXT :: next.

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

Среда выполнения должна заполнять XrSpatialComponentDataQueryResultEXT :: entityIds только объектами, у которых есть все компоненты, указанные в XrSpatialComponentDataQueryConditionEXT :: componentTypes . Если XrSpatialComponentDataQueryConditionEXT :: componentTypeCount равно 0, среда выполнения должна заполнить queryResult всеми объектами (и их состояниями отслеживания), которые есть в снимке. Если в XrSpatialComponentDataQueryConditionEXT :: next добавлены дополнительные условия запроса, среда выполнения должна обрабатывать их как оператор AND с доступностью типов компонентов, то есть среда выполнения должна заполнять XrSpatialComponentDataQueryResultEXT ::entityIds только объектами, которые соответствуют всем указанным условиям. Среда выполнения должна заполнять данные компонента в структурах списка в том же порядке, что и объекты в XrSpatialComponentDataQueryResultEXT :: entityIds, то есть данные компонента по заданному индексу в массиве структуры списка должны соответствовать объекту по тому же индексу.

Если состояние отслеживания для объекта не XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT, среда выполнения не должна изменять данные в индексе, соответствующем этому объекту в массиве, содержащемся в структурах списка, прикрепленных к 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

Например, приложение создает XrSpatialSnapshotEXT, содержащий пять объектов, где:

  • Объекты 1 и 2 содержат компоненты XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT и XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
  • Объекты 3 и 4 имеют компоненты XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT и XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT.
  • Объект 5 содержит компоненты XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT и 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

Нет

Нет

Нет

Нет

Да

Да

Да

Да

Нет

Нет Текст не в формате SVG – не удается показать

Рисунок 20. Пример сводки

Вызов xrQuerySpatialComponentDataEXT для приведенного выше снимка с XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT в условии запроса приведет к тому, что объекты 1, 2 и 5 будут возвращены приложению, и приложение сможет прикрепить массив XrSpatialBounded2DDataEXT как часть структуры XrSpatialComponentBounded2DListEXT к следующей цепочке XrSpatialComponentDataQueryResultEXT, чтобы получить данные bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

Данные для entityId #1

Данные для entit...

Данные для entityId #2

Данные для entit...

Данные для entityId #5

Данные для entit...

entityIds

entityIds

далее

далее

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

bounds

bounds

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... Текст не является SVG-файлом и не может быть показан

Рисунок 21. Пример результата запроса

Вызов xrQuerySpatialComponentDataEXT для приведенного выше снимка с компонентами XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT и XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT, указанными в условии запроса, приведет к тому, что в приложение будут возвращены объекты 3 и 4. Приложение может прикрепить массивы XrBoxf и XrSpatialMeshDataEXT как часть структур XrSpatialComponentBounded3DListEXT и XrSpatialComponentMesh3DListEXT соответственно к следующей цепочке XrSpatialComponentDataQueryResultEXT, чтобы получить данные компонента.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

Данные для entityId #3

Данные для entit...

Данные для entityId #4

Данные для entit...

Mesh3D

Mesh3D

Данные для entityId #3

Данные для entit...

Данные для entityId #4

Данные для entit...

entityIds

entityIds

далее

далее

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

bounds

bounds

далее

далее

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

сетки

meshes Text is not SVG - cannot display

Рисунок 22. Пример результата запроса

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

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

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • componentTypeCount – это uint32_t, описывающий количество элементов в массиве componentTypes.
  • componentTypes – массив XrSpatialComponentTypeEXT, для которого нужно получить данные из снимка.

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

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

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 – емкость массива entityIds или 0, если нужно получить требуемую емкость.
  • entityIdCountOutput – количество XrSpatialEntityIdEXT в entityIds или требуемая емкость, если entityIdCapacityInput недостаточно.
  • entityIds – массив объектов XrSpatialEntityIdEXT . Может быть NULL, если entityIdCapacityInput равно 0.
  • entityStateCapacityInput – емкость массива entityStates или 0, если нужно получить требуемую емкость.
  • entityStateCountOutput – количество XrSpatialEntityTrackingStateEXT в entityStates или требуемая емкость, если entityStateCapacityInput недостаточно. Это значение всегда должно совпадать со значением entityIdCountOutput .
  • entityStates – это массив XrSpatialEntityTrackingStateEXT . Может быть NULL, если entityStateCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер entityIds, приведено в разделе Параметры размера буфера.

Приложение может использовать entityIds с xrCreateSpatialEntityFromIdEXT, чтобы создавать дескрипторы XrSpatialEntityEXT для объектов, по которым оно хочет регулярно получать обновления. Затем приложение может использовать эти дескрипторы XrSpatialEntityEXT с xrCreateSpatialUpdateSnapshotEXT, чтобы создать обновленный снимок, содержащий последние известные среде выполнения данные компонентов для предоставленных объектов.

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

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;

XrSpatialEntityTrackingStateEXT перечисляет возможные состояния отслеживания пространственных объектов:

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

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

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

Среда выполнения прекратила отслеживание этого объекта и больше не возобновит его.

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

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

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

Среда выполнения отслеживает этот объект, и данные его компонента действительны.

ОТСЛЕЖИВАЕМОЕ ОБЪЯВЛЕНИЕ

ПРИОСТАНОВЛЕНО

STOPPED

Рисунок 23. XrSpatialEntityTrackingStateEXT

  • Среда выполнения может изменить состояние пространственного объекта с XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT на XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT, если она приостанавливает отслеживание этого пространственного объекта, но имеет возможность возобновить его отслеживание в будущем. Например, это может произойти, если приложение теряет фокус ввода, если пространственный объект находится слишком далеко от пользователя, чтобы его можно было точно отслеживать, или если отслеживается слишком много объектов и среда выполнения хочет снизить затраты на отслеживание. XrSpatialEntityTrackingStateEXT помогает приложению изолировать себя от разных правил отслеживания каждой среды выполнения.
  • Среда выполнения может изменить состояние объекта с XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT на XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT или XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
  • Среда выполнения должна изменить состояние пространственного объекта с XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT или XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT на XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT, если пространственный объект потерян и его отслеживание не будет восстановлено или возобновлено. Например, если устройство теряет отслеживание, перезапускает сеанс отслеживания, но не может повторно локализоваться в своей среде и поэтому обрабатывает обнаруженные объекты этого сеанса отслеживания как новые объекты.
  • Если для объекта задано состояние отслеживания XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , среда выполнения не должна менять его на другое.
  • При запросе данных компонента пространственного объекта с помощью xrQuerySpatialComponentDataEXT среда выполнения должна задать действительные данные в содержимом буферов, предоставленных приложением в следующей цепочке XrSpatialComponentDataQueryResultEXT, если состояние объекта – XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . Если состояние объекта – XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT или XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , среда выполнения не должна изменять содержимое буферов.

Идиома с двумя вызовами для данных компонента

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

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

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

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

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

Для одного и того же bufferId среда выполнения должна предоставлять одни и те же данные от одного запроса данных компонента к другому, даже в разных снимках. Если значение bufferId в запросах данных компонента различается, это указывает приложению на то, что данные для этого компонента могли измениться.

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

  • Расширение XR_EXT_spatial_entity должно быть включено до использования XrSpatialBufferEXT.
  • bufferType должно быть допустимым значением XrSpatialBufferTypeEXT.

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

XrSpatialBufferIdEXT используется для представления любых данных переменного размера для пространственного компонента.

Среда выполнения должна хранить XrSpatialBufferIdEXT и его данные в памяти по крайней мере в течение жизненного цикла XrSpatialSnapshotEXT, который его содержит. Среда выполнения может хранить XrSpatialBufferIdEXT и его данные в памяти дольше, чем жизненный цикл XrSpatialSnapshotEXT, чтобы возвращать тот же идентификатор в составе снимков, созданных приложением позже. Для одного и того же XrSpatialBufferIdEXT среда выполнения должна всегда возвращать одни и те же данные через соответствующую функцию xrGetSpatialBuffer*.

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;

Перечисление XrSpatialBufferTypeEXT определяет различные типы данных буфера, представленного XrSpatialBufferIdEXT .

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

  • XR_SPATIAL_BUFFER_TYPE_STRING_EXT: XrSpatialBufferIdEXT можно передать в xrGetSpatialBufferStringEXT, чтобы получить строковый буфер.
  • XR_SPATIAL_BUFFER_TYPE_UINT8_EXT: XrSpatialBufferIdEXT можно передать в xrGetSpatialBufferUint8EXT, чтобы получить буфер uint8_t.
  • XR_SPATIAL_BUFFER_TYPE_UINT16_EXT: XrSpatialBufferIdEXT можно передать в xrGetSpatialBufferUint16EXT, чтобы получить буфер uint16_t.
  • XR_SPATIAL_BUFFER_TYPE_UINT32_EXT: XrSpatialBufferIdEXT можно передать в xrGetSpatialBufferUint32EXT, чтобы получить буфер uint32_t.
  • XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT: XrSpatialBufferIdEXT можно передать в xrGetSpatialBufferFloatEXT, чтобы получить буфер float.
  • XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT: XrSpatialBufferIdEXT можно передать в xrGetSpatialBufferVector2fEXT, чтобы получить буфер XrVector2f.
  • XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT: XrSpatialBufferIdEXT можно передать в xrGetSpatialBufferVector3fEXT, чтобы получить буфер XrVector3f.

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

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

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

  • snapshot – дескриптор XrSpatialSnapshotEXT .
  • info содержит информацию о буфере, который нужно запросить.
  • bufferCapacityInput – емкость массива или 0, если нужно получить требуемую емкость.
  • bufferCountOutput – количество символов или требуемая емкость, если bufferCapacityInput недостаточно.
  • buffer – массив объектов char . Может быть NULL, если bufferCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер buffer, приведено в разделе Параметры размера буфера.

Приложение может получить данные для XrSpatialBufferEXT, предоставленного компонентом, где XrSpatialBufferEXT :: bufferType – это XR_SPATIAL_BUFFER_TYPE_STRING_EXT, с помощью xrGetSpatialBufferStringEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialBufferTypeEXT для XrSpatialBufferGetInfoEXT :: bufferId не является XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, если XrSpatialBufferGetInfoEXT :: bufferId не принадлежит snapshot .

buffer, заполненный средой выполнения, должен быть строкой UTF-8 с нулевым символом в конце.

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrGetSpatialBufferStringEXT.
  • snapshot должен быть действительным дескриптором XrSpatialSnapshotEXT.
  • info должен быть указателем на действительную структуру XrSpatialBufferGetInfoEXT.
  • bufferCountOutput должен быть указателем на значение uint32_t.
  • Если bufferCapacityInput не равно 0 , buffer должен быть указателем на массив значений char bufferCapacityInput.

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

Выполнено

  • 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

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

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

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

  • snapshot – дескриптор XrSpatialSnapshotEXT .
  • info содержит информацию о буфере, который нужно запросить.
  • bufferCapacityInput – емкость массива или 0, если нужно получить требуемую емкость.
  • bufferCountOutput – количество элементов в массиве buffer или требуемая емкость, если bufferCapacityInput недостаточно.
  • buffer – массив объектов uint8_t . Может быть NULL, если bufferCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер buffer, приведено в разделе Параметры размера буфера.

Приложение может получить данные для XrSpatialBufferEXT, предоставленного компонентом, где XrSpatialBufferEXT :: bufferType – это XR_SPATIAL_BUFFER_TYPE_UINT8_EXT, с помощью xrGetSpatialBufferUint8EXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialBufferTypeEXT для XrSpatialBufferGetInfoEXT :: bufferId не является XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, если XrSpatialBufferGetInfoEXT :: bufferId не принадлежит snapshot .

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrGetSpatialBufferUint8EXT.
  • snapshot должен быть действительным дескриптором XrSpatialSnapshotEXT.
  • info должен быть указателем на действительную структуру XrSpatialBufferGetInfoEXT.
  • bufferCountOutput должен быть указателем на значение uint32_t.
  • Если bufferCapacityInput не равно 0 , buffer должен быть указателем на массив значений bufferCapacityInput uint8_t.

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

Выполнено

  • 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

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

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

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

  • snapshot – дескриптор XrSpatialSnapshotEXT .
  • info содержит информацию о буфере, который нужно запросить.
  • bufferCapacityInput – емкость массива или 0, если нужно получить требуемую емкость.
  • bufferCountOutput – количество элементов в массиве buffer или требуемая емкость, если bufferCapacityInput недостаточно.
  • buffer – массив объектов uint16_t . Может быть NULL, если bufferCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер buffer, приведено в разделе Параметры размера буфера.

Приложение может получить данные для XrSpatialBufferEXT, предоставленного компонентом, где XrSpatialBufferEXT :: bufferType – это XR_SPATIAL_BUFFER_TYPE_UINT16_EXT, с помощью xrGetSpatialBufferUint16EXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialBufferTypeEXT для XrSpatialBufferGetInfoEXT :: bufferId не является XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, если XrSpatialBufferGetInfoEXT :: bufferId не принадлежит snapshot .

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrGetSpatialBufferUint16EXT.
  • snapshot должен быть действительным дескриптором XrSpatialSnapshotEXT.
  • info должен быть указателем на действительную структуру XrSpatialBufferGetInfoEXT.
  • bufferCountOutput должен быть указателем на значение uint32_t.
  • Если bufferCapacityInput не равно 0 , buffer должен быть указателем на массив значений bufferCapacityInput uint16_t.

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

Выполнено

  • 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

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

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

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

  • snapshot – дескриптор XrSpatialSnapshotEXT .
  • info содержит информацию о буфере, который нужно запросить.
  • bufferCapacityInput – емкость массива или 0, если нужно получить требуемую емкость.
  • bufferCountOutput – количество элементов в массиве buffer или требуемая емкость, если bufferCapacityInput недостаточно.
  • buffer – массив объектов uint32_t . Может быть NULL, если bufferCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер buffer, приведено в разделе Параметры размера буфера.

Приложение может получить данные для XrSpatialBufferEXT, предоставленного компонентом, где XrSpatialBufferEXT :: bufferType – это XR_SPATIAL_BUFFER_TYPE_UINT32_EXT, с помощью xrGetSpatialBufferUint32EXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialBufferTypeEXT для XrSpatialBufferGetInfoEXT :: bufferId не является XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, если XrSpatialBufferGetInfoEXT :: bufferId не принадлежит snapshot .

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrGetSpatialBufferUint32EXT.
  • snapshot должен быть действительным дескриптором XrSpatialSnapshotEXT.
  • info должен быть указателем на действительную структуру XrSpatialBufferGetInfoEXT.
  • bufferCountOutput должен быть указателем на значение uint32_t.
  • Если bufferCapacityInput не равно 0 , buffer должен быть указателем на массив значений bufferCapacityInput uint32_t.

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

Выполнено

  • 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

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

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

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

  • snapshot – дескриптор XrSpatialSnapshotEXT .
  • info содержит информацию о буфере, который нужно запросить.
  • bufferCapacityInput – емкость массива или 0, если нужно получить требуемую емкость.
  • bufferCountOutput – количество элементов в массиве buffer или требуемая емкость, если bufferCapacityInput недостаточно.
  • buffer – массив объектов float . Может быть NULL, если bufferCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер buffer, приведено в разделе Параметры размера буфера.

Приложение может получить данные для XrSpatialBufferEXT, предоставленного компонентом, где XrSpatialBufferEXT :: bufferType – это XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT, с помощью xrGetSpatialBufferFloatEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialBufferTypeEXT для XrSpatialBufferGetInfoEXT :: bufferId не является XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, если XrSpatialBufferGetInfoEXT :: bufferId не принадлежит snapshot .

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrGetSpatialBufferFloatEXT.
  • snapshot должен быть действительным дескриптором XrSpatialSnapshotEXT.
  • info должен быть указателем на действительную структуру XrSpatialBufferGetInfoEXT.
  • bufferCountOutput должен быть указателем на значение uint32_t.
  • Если bufferCapacityInput не равно 0 , buffer должен быть указателем на массив значений bufferCapacityInput float.

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

Выполнено

  • 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

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

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

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

  • snapshot – дескриптор XrSpatialSnapshotEXT .
  • info содержит информацию о буфере, который нужно запросить.
  • bufferCapacityInput – емкость массива или 0, если нужно получить требуемую емкость.
  • bufferCountOutput – количество элементов в массиве buffer или требуемая емкость, если bufferCapacityInput недостаточно.
  • buffer – массив XrVector2f . Может быть NULL, если bufferCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер buffer, приведено в разделе Параметры размера буфера.

Приложение может получить данные для XrSpatialBufferEXT, предоставленного компонентом, где XrSpatialBufferEXT :: bufferType – это XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT, с помощью xrGetSpatialBufferVector2fEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialBufferTypeEXT для XrSpatialBufferGetInfoEXT :: bufferId не является XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, если XrSpatialBufferGetInfoEXT :: bufferId не принадлежит snapshot .

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrGetSpatialBufferVector2fEXT.
  • snapshot должен быть действительным дескриптором XrSpatialSnapshotEXT.
  • info должен быть указателем на действительную структуру XrSpatialBufferGetInfoEXT.
  • bufferCountOutput должен быть указателем на значение uint32_t.
  • Если bufferCapacityInput не равно 0 , buffer должен быть указателем на массив структур bufferCapacityInput XrVector2f.

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

Выполнено

  • 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

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

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

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

  • snapshot – дескриптор XrSpatialSnapshotEXT .
  • info содержит информацию о буфере, который нужно запросить.
  • bufferCapacityInput – емкость массива или 0, если нужно получить требуемую емкость.
  • bufferCountOutput – количество элементов в массиве buffer или требуемая емкость, если bufferCapacityInput недостаточно.
  • buffer – массив объектов XrVector3f . Может быть NULL, если bufferCapacityInput равно 0.
  • Подробное описание того, как получить нужный размер buffer, приведено в разделе Параметры размера буфера.

Приложение может получить данные для XrSpatialBufferEXT, предоставленного компонентом, где XrSpatialBufferEXT :: bufferType – это XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT, с помощью xrGetSpatialBufferVector3fEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE, если XrSpatialBufferTypeEXT для XrSpatialBufferGetInfoEXT :: bufferId не является XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT, если XrSpatialBufferGetInfoEXT :: bufferId не принадлежит snapshot .

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrGetSpatialBufferVector3fEXT.
  • snapshot должен быть действительным дескриптором XrSpatialSnapshotEXT.
  • info должен быть указателем на действительную структуру XrSpatialBufferGetInfoEXT.
  • bufferCountOutput должен быть указателем на значение uint32_t.
  • Если bufferCapacityInput не равно 0 , buffer должен быть указателем на массив структур bufferCapacityInput XrVector3f.

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

Выполнено

  • 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

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

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

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

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

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

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

XR_NULL_SPATIAL_BUFFER_ID_EXT – зарезервированное значение, которое представляет недопустимый XrSpatialBufferIdEXT . Его можно передавать в функции API и получать из них только в том случае, если это явно разрешено.

Создать снимок обновления

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

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

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

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

Приложение может использовать XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes, чтобы отфильтровать список компонентов, данные которых должны быть включены в снимок. Если приложение предоставляет действительный список типов пространственных компонентов в XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes, то среда выполнения должна включать в снимок только пространственные объекты, у которых есть хотя бы один из компонентов, указанных в XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Кроме того, среда выполнения должна включать в снимок только данные для этих компонентов.

Среда выполнения должна возвращать XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT, если какие-либо из XrSpatialComponentTypeEXT в XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes не включены для пространственных возможностей, переданных в XrSpatialContextCreateInfoEXT :: capabilityConfigs при создании spatialContext .

Если приложение не предоставляет список типов пространственных компонентов в XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes, среда выполнения должна включить в снимок все пространственные объекты, перечисленные в XrSpatialUpdateSnapshotCreateInfoEXT :: entities, и должна включить данные для всех включенных компонентов возможностей, настроенных для spatialContext .

Среда выполнения не должна включать пространственные объекты, не указанные в XrSpatialUpdateSnapshotCreateInfoEXT :: entities в snapshot .

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

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

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

Выполнено

  • 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

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

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 – это uint32_t, описывающий количество элементов в массиве entities.
  • entities – массив XrSpatialEntityEXT, для которого среда выполнения должна включить данные компонента в снимок.
  • componentTypeCount – это uint32_t, описывающий количество элементов в массиве componentTypes.
  • componentTypes – массив XrSpatialComponentTypeEXT, для которого среда выполнения должна включить данные в снимок.
  • baseSpace – это XrSpace, относительно которого будут расположены все местоположения обновленного XrSpatialSnapshotEXT.
  • time – это XrTime, в котором будут находиться все местоположения обновления XrSpatialSnapshotEXT.

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

  • Расширение XR_EXT_spatial_entity должно быть включено до использования XrSpatialUpdateSnapshotCreateInfoEXT.
  • type должно быть XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
  • next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
  • entities должен быть указателем на массив из entityCount действительных дескрипторов XrSpatialEntityEXT.
  • Если componentTypeCount не равно 0 , componentTypes должен быть указателем на массив допустимых значений componentTypeCount XrSpatialComponentTypeEXT.
  • baseSpace должен быть действительным идентификатором XrSpace.
  • Значение параметра entityCount должно быть больше 0.
  • И baseSpace, и элементы entities должны быть созданы, выделены или получены из одного и того же XrSession.

Удалить снимок

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

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

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

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

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

  • Расширение XR_EXT_spatial_entity должно быть включено до вызова xrDestroySpatialSnapshotEXT.
  • snapshot должен быть действительным дескриптором XrSpatialSnapshotEXT.

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

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

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

Выполнено

  • XR_SUCCESS

Сбой

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Общие компоненты

Ограниченная 2D-модель

Данные компонента

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

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

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

  • center – это XrPosef, определяющий геометрический центр ограниченного двухмерного компонента.
  • extents – это размеры ограниченного двумерного компонента по оси X (extents.width) и оси Y (extents.height) с центром в точке center .

extents XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT – это размер объекта в плоскости x-y системы координат плоскости. Плоскость с положением {0, 0, 0}, поворотом {0, 0, 0, 1} (без поворота) и размером {1, 1} представляет собой плоскость размером 1 x 1 м с центром в точке {0, 0, 0}, нормальный вектор передней грани которой направлен в сторону +Z в пространстве компонента.

X X Y Y Z Z Высота Высота Y Y Z Z X X Вертикальная плоскость Вертикальная плоскость Горизонтальная плоскость Горизонтальная плоскость Ширина Ширина Ширина Ширина Высота Высота

Рисунок 24. Система координат компонента Bounded2D

Примечание

OpenXR использует плоскость X-Y с нормалью +Z, но другие API могут использовать плоскость X-Z с нормалью +Y. Плоскость XY можно преобразовать в плоскость XZ, повернув ее на -π/2 радиан вокруг оси +X.

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

  • Расширение XR_EXT_spatial_entity должно быть включено до использования XrSpatialBounded2DDataEXT.
Структура списка компонентов для запроса данных

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

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

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

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

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrQuerySpatialComponentDataEXT, если XrSpatialComponentBounded2DListEXT находится в следующей цепочке XrSpatialComponentDataQueryResultEXT :: next, но XrSpatialComponentDataQueryConditionEXT ::componentTypeCount не равно нулю и XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT не включено в XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если boundCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Если xrQuerySpatialComponentDataEXT :: snapshot был создан из xrCreateSpatialDiscoverySnapshotCompleteEXT , то среда выполнения должна предоставить XrSpatialBounded2DDataEXT :: center в XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace и XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Если xrQuerySpatialComponentDataEXT :: snapshot был создан из xrCreateSpatialUpdateSnapshotEXT , то среда выполнения должна предоставить XrSpatialBounded2DDataEXT :: center в XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace и XrSpatialUpdateSnapshotCreateInfoEXT :: time .

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

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

Если XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT перечислено в XrSpatialCapabilityComponentTypesEXT :: componentTypes для определенной возможности, приложение может включить ее, добавив значение перечисления в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Этот компонент не требует специальной настройки для включения в следующую цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT .

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

Данные компонента

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT использует XrBoxf для своих данных.

Структура списка компонентов для запроса данных

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

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

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

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

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrQuerySpatialComponentDataEXT, если XrSpatialComponentBounded3DListEXT находится в следующей цепочке XrSpatialComponentDataQueryResultEXT :: next, но XrSpatialComponentDataQueryConditionEXT ::componentTypeCount не равно нулю и XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT не включено в XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если boundCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Если xrQuerySpatialComponentDataEXT :: snapshot был создан из xrCreateSpatialDiscoverySnapshotCompleteEXT , то среда выполнения должна предоставить XrBoxf :: center в XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace в XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

Если xrQuerySpatialComponentDataEXT :: snapshot был создан из xrCreateSpatialUpdateSnapshotEXT , то среда выполнения должна предоставить XrBoxf :: center в XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace в XrSpatialUpdateSnapshotCreateInfoEXT :: time .

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

  • Прежде чем использовать XrSpatialComponentBounded3DListEXT, необходимо включить расширение XR_EXT_spatial_entity.
  • type должно быть XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
  • next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
  • bounds должен быть указателем на массив структур boundCount XrBoxf.
  • Значение параметра boundCount должно быть больше 0.
Конфигурация

Если XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT перечислено в XrSpatialCapabilityComponentTypesEXT :: componentTypes для определенной возможности, приложение может включить ее, добавив перечисление в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Этот компонент не требует специальной настройки для включения в следующую цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT .

Родитель

Данные компонента

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT использует XrSpatialEntityIdEXT для своих данных.

Структура списка компонентов для запроса данных

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

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

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

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

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrQuerySpatialComponentDataEXT, если XrSpatialComponentParentListEXT находится в следующей цепочке XrSpatialComponentDataQueryResultEXT :: next, но XrSpatialComponentDataQueryConditionEXT ::componentTypeCount не равно нулю и XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT не включено в XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если parentCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

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

  • Расширение XR_EXT_spatial_entity должно быть включено до использования XrSpatialComponentParentListEXT.
  • type должно быть XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
  • next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
  • parents должен быть указателем на массив значений parentCount XrSpatialEntityIdEXT.
  • Значение параметра parentCount должно быть больше 0.
Конфигурация

Если XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT перечислено в XrSpatialCapabilityComponentTypesEXT :: componentTypes для какой-либо возможности, приложение может включить ее, добавив перечисление в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Этот компонент не требует специальной настройки для включения в следующую цепочку XrSpatialCapabilityConfigurationBaseHeaderEXT .

3D-сетка

Данные компонента

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

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

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

  • origin – это XrPosef, определяющий начало сетки. Все вершины сетки должны быть связаны с этой точкой.
  • vertexBuffer – это XrSpatialBufferEXT, который предоставляет идентификатор буфера, представляющего буфер вершин объекта, на котором находится этот компонент. Положение вершин должно быть задано относительно origin .
  • indexBuffer – это XrSpatialBufferEXT, который предоставляет идентификатор буфера, представляющего массив индексов треугольников, указывающих индексы вершин сетки в vertexBuffer . Индексы треугольников должны возвращаться в порядке против часовой стрелки. Три индекса обозначают один треугольник.

Тип компонента, использующий XrSpatialMeshDataEXT, должен указывать XrSpatialBufferTypeEXT для vertexBuffer и indexBuffer .

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

  • Расширение XR_EXT_spatial_entity должно быть включено до использования XrSpatialMeshDataEXT.
  • vertexBuffer должен быть допустимой структурой XrSpatialBufferEXT.
  • indexBuffer должен быть допустимой структурой XrSpatialBufferEXT.
Структура списка компонентов для запроса данных

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

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

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • meshCount – это uint32_t, описывающий количество элементов в массиве meshes.
  • meshes – массив XrSpatialMeshDataEXT .

Приложение может запрашивать 3D-компонент сетки пространственных объектов в XrSpatialSnapshotEXT, добавляя XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавляя XrSpatialComponentMesh3DListEXT в следующую цепочку указателей XrSpatialComponentDataQueryResultEXT .

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrQuerySpatialComponentDataEXT, если XrSpatialComponentMesh3DListEXT находится в следующей цепочке XrSpatialComponentDataQueryResultEXT :: next, но XrSpatialComponentDataQueryConditionEXT ::componentTypeCount не равно нулю и XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT не включено в XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT, если meshCount меньше XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Для XrSpatialMeshDataEXT, заполненного средой выполнения в массиве meshes, XrSpatialBufferEXT :: bufferType для XrSpatialMeshDataEXT :: vertexBuffer должно быть XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT, а XrSpatialBufferEXT :: bufferType для XrSpatialMeshDataEXT :: indexBuffer должно быть XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

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

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

Если XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT перечислено в XrSpatialCapabilityComponentTypesEXT :: componentTypes для определенной возможности, приложение может включить ее, добавив перечисление в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents производной структуры XrSpatialCapabilityConfigurationBaseHeaderEXT возможности, которая поддерживает этот компонент.

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

Фильтры статуса отслеживания

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

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

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

  • type – это XrStructureType этой структуры.
  • next – это NULL или указатель на следующую структуру в цепочке.
  • trackingState – это XrSpatialEntityTrackingStateEXT, к которому приложение хочет применить фильтр.

Приложение может использовать XrSpatialFilterTrackingStateEXT в следующей цепочке XrSpatialDiscoverySnapshotCreateInfoEXT, чтобы ограничить обнаружение только теми объектами, у которых статус отслеживания – trackingState .

Приложение может использовать XrSpatialFilterTrackingStateEXT в следующей цепочке XrSpatialComponentDataQueryConditionEXT, чтобы ограничить запрос данных компонента из снимка только объектами, у которых статус отслеживания – trackingState .

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

Пример кода

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

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

  • Сначала приложение перечисляет пространственные возможности системы с помощью xrEnumerateSpatialCapabilitiesEXT . Затем он проверяет возвращенный массив XrSpatialCapabilityEXT и перечисляет компоненты и функции, поддерживаемые для каждой из этих возможностей, используя xrEnumerateSpatialCapabilityComponentTypesEXT и xrEnumerateSpatialCapabilityFeaturesEXT соответственно. Это дает приложению полное представление о компонентах, которые оно может включить, и конфигурациях, которые принимает функция.
  • Затем приложение создает один или несколько дескрипторов XrSpatialContextEXT с определенными конфигурациями пространственных возможностей, в которых конфигурации включают и настраивают определенную возможность в пространственном контексте, а также включают и настраивают компоненты для этих возможностей.
  • Для каждого XrSpatialContextEXT приложение ожидает получения событий XrEventDataSpatialDiscoveryRecommendedEXT для этого XrSpatialContextEXT, прежде чем использовать xrCreateSpatialDiscoverySnapshotAsyncEXT для обнаружения пространственных объектов. После завершения этой асинхронной операции приложение получает дескриптор XrSpatialSnapshotEXT.
  • Приложение запрашивает объекты и данные компонентов, включенные в этот XrSpatialSnapshotEXT, с помощью xrQuerySpatialComponentDataEXT . Приложение считывает последние данные компонентов запрашиваемых объектов из структур, прикрепленных к следующей цепочке XrSpatialComponentDataQueryResultEXT, если состояние объекта – XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT .
  • Если приложение определяет определенные объекты как интересные и хочет получать обновления для них с течением времени, оно создает дескрипторы XrSpatialEntityEXT для этих объектов с помощью xrCreateSpatialEntityFromIdEXT . Приложение получает обновления для таких объектов с помощью xrCreateSpatialUpdateSnapshotEXT и использует ту же функцию xrQuerySpatialComponentDataEXT для вновь созданного XrSpatialSnapshotEXT, чтобы получить последние данные компонентов для этих объектов.

Как находить пространственные объекты и запрашивать данные компонентов

В примере кода ниже показано, как обнаружить пространственные объекты для функции Foo и запросить данные их компонентов.

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

Запрос данных буфера

В примере кода ниже показано, как получить данные компонента, который предоставляет 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.
  }
}

Правила в отношении расширений

  • Если расширение определяет новый тип XrSpatialComponentTypeEXT, который предоставляет дополнительные данные о пространственном объекте,

    • расширение должно также определять структуру списка для этого компонента, которая позволяет приложению передавать массив в среду выполнения для заполнения данными для каждого из пространственных объектов, удовлетворяющих xrQuerySpatialComponentDataEXT :: queryCondition . Примеры таких структур: XrSpatialComponentParentListEXT и XrSpatialComponentBounded2DListEXT . Если размер данных компонента переменный и для его запроса приложению требуется использовать идиому двух вызовов, данные компонента должны предоставлять XrSpatialBufferEXT для каждого элемента данных переменного размера в структуре списка и должны указывать XrSpatialBufferTypeEXT для каждого буфера. Затем приложение может запросить данные буфера с помощью функций, определенных в разделе Идиома двух вызовов для данных компонента . Пример такой структуры – XrSpatialMeshDataEXT, которая включена в XrSpatialComponentMesh3DListEXT .
    • Расширение может также предоставлять структуры, которые приложение может связывать с XrSpatialComponentDataQueryConditionEXT :: next, чтобы предоставлять дополнительные фильтры для запроса, относящегося к данным этого компонента.

  • Расширения могут определять структуры, которые расширяют XrSpatialDiscoverySnapshotCreateInfoEXT, чтобы предоставлять дополнительные фильтры для обнаружения. Фильтры для создания снимка не должны влиять на конфигурацию пространственного контекста. Вместо этого они должны использоваться для предоставления подсказок среде выполнения о том, какие объекты и данные должны быть включены в снимок, как это отслеживается текущей конфигурацией пространственного контекста (и, следовательно, текущей конфигурацией базовых сервисов).

  • Если расширение определяет новый XrSpatialCapabilityEXT ,

    • Оно также должно указывать список XrSpatialComponentTypeEXT, которые среды выполнения должны предоставлять объектам для этой возможности.
    • Оно должно также предоставлять структуры, производные от XrSpatialCapabilityConfigurationBaseHeaderEXT, которые позволят настроить эту возможность.

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

  • Расширение, определяющее новый XrSpatialCapabilityEXT, должно следовать этому шаблону для спецификации:

    • Обзор
    • Поддержка среды выполнения
    • Конфигурация
    • Гарантированные компоненты
    • Пример кода

  • Расширение, определяющее новый тип XrSpatialComponentTypeEXT, должно соответствовать следующему шаблону спецификации:

    • Данные компонента
    • Структура списка компонентов для запроса данных
    • Конфигурация

  • При написании API, который предоставляет приложению XrSpatialBufferIdEXT, необходимо добавить XrSpatialBufferTypeEXT, чтобы сообщить приложению тип данных буфера. Приложение может использовать подходящую функцию xrGetSpatialBuffer*, чтобы получить фактическое содержимое буфера.

Рекомендации по созданию и расширению семантических ярлыков

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

  • Если расширение определяет семантические ярлыки для любого XrSpatialCapabilityEXT, оно должно делать это, определяя новый XrSpatialComponentTypeEXT, а также новое перечисление с набором ярлыков ("набор семантических ярлыков"), которые будут данными для этого компонента.
  • Перечисление, представляющее набор семантических ярлыков, должно иметь значение, указывающее, что объект не относится ни к одному из ярлыков этого набора. Название этого перечислимого значения должно включать слово UNCATEGORIZED, например XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT. Это значение указывает приложениям, что среда выполнения распознает объект, но он также относится к другим наборам семантических ярлыков.
  • Перечисление этого нового типа XrSpatialComponentTypeEXT в xrEnumerateSpatialCapabilityComponentTypesEXT означает, что среда выполнения поддерживает набор семантических ярлыков (и, следовательно, ярлыки, определенные в наборе), соответствующие этому типу компонента.
  • Приложения выражают желание обнаруживать объекты, у которых есть ярлыки, принадлежащие этому набору семантических ярлыков, включая соответствующий XrSpatialComponentTypeEXT в массив XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents структуры конфигурации для возможности, для которой перечисляется тип компонента.
  • У одного пространственного объекта может быть несколько компонентов, каждый из которых предоставляет ему ярлык из собственного набора семантических ярлыков. Рассмотрим следующий пример с некоторыми гипотетическими наборами семантических меток – XrSpatialObjectSemanticLabel, которые могут иметь такие значения, как стул, диван, стол и т. д., XrSpatialSofaBrand (например, IKEA, Wayfair и т. д.) и XrSpatialIkeaSofa (например, названия моделей диванов IKEA). В этом сценарии один и тот же объект дивана имеет все 3 компонента (метки из всех 3 наборов семантических меток), каждый из которых дает разную степень детализации информации об объекте.
  • Если расширение определяет новый тип XrSpatialComponentTypeEXT, который предоставляет новый набор семантических меток, содержащий несколько меток в дополнение к метке UNCATEGORIZED, расширение должно рассмотреть возможность определения XrSpatialCapabilityFeatureEXT, который позволяет приложениям активировать только подмножество меток, определенных в наборе семантических меток, соответствующих этому типу компонента. Этот поднабор, указанный в следующей цепочке конфигурации возможностей, служит подсказкой для сред выполнения, чтобы оптимизировать конвейеры отслеживания и отслеживать только предоставленный поднабор. Пример такой структуры приведен ниже .
  • Расширения не должны добавлять ярлыки в существующий набор семантических ярлыков. Вместо этого необходимо определить новое перечисление, которое содержит эквивалентные перечислители с идентичной семантикой и значениями, равными значениям из другого набора, в дополнение к вновь добавленным перечислителям. Спецификация нового набора семантических ярлыков должна также устанавливать сопоставление между старым и новым наборами ярлыков. См. пример ниже.
Пример определения пространственного объекта для поднабора семантических ярлыков
// 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;

Рассмотрим приведенный выше пример, в котором расширение определяет перечисление XrSpatialExamplePlaneSemanticLabelExtensionEXT, чтобы расширить существующий XrSpatialPlaneSemanticLabelEXT значениями, представляющими двери и окна. Спецификация для нового перечисления должна включать текст следующей формы:

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
|====

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

Новые типы оснований

  • XrSpatialBufferIdEXT
  • XrSpatialEntityIdEXT

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

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

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

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

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

  • XR_EXT_SPATIAL_ENTITY_EXTENSION_NAME
  • XR_EXT_spatial_entity_SPEC_VERSION

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

Проблемы

  • Всегда ли один объект происходит исключительно из одной возможности?

    • Вопрос решен
    • Ответ. Нет. Это полностью зависит от среды выполнения, ее возможностей отслеживания и того, как она представляет обнаруженный объект. Спецификация не предписывает конкретного представления пространственного объекта, за исключением гарантированных компонентов заданной возможности, чтобы установить минимальные ожидания. Среда выполнения может объединять объекты, обнаруженные разными функциями, и представлять их как один объект с гарантированными компонентами всех функций, которые помогли его идентифицировать. Например, столы могут быть обнаружены как с помощью отслеживания плоскости, так и с помощью отслеживания объектов. При этом отслеживание плоскости предоставляет компонент XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT для объекта, а отслеживание объектов – XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT. Определенная среда выполнения может предоставлять таблицу в виде двух отдельных объектов, каждый из которых имеет собственный набор гарантированных компонентов, а некоторые среды выполнения могут предоставлять только один объект для представления таблицы и иметь как XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, так и XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT в одном объекте. Важно отметить, что у пространственного объекта может быть не более одного компонента каждого типа . Поэтому если данные компонента, созданные разными функциями, конфликтуют для определенного объекта, среда выполнения должна представить их как два отдельных объекта.

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

  • Версия 1, 12 апреля 2024 г. (Нихав Джайн, Google)

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