XR_EXT_spatial_object_tracking

Name String

XR_EXT_spatial_object_tracking

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

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

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

745

Revision

1

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

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

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

XR_EXT_spatial_entity

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

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

Авторы

Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance
Andy Biar, Unity Technologies
Rebecca Nordhauser, Unity Technologies

Обзор

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

Поддержка среды выполнения

Если среда выполнения поддерживает отслеживание объектов, она должна указать это, перечислив XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT в xrEnumerateSpatialCapabilitiesEXT .

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

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

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

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

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

Приложения могут включить пространственную функцию XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, добавив указатель на структуру XrSpatialCapabilityConfigurationObjectTrackingEXT в XrSpatialContextCreateInfoEXT :: capabilityConfigs .

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

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

• Расширение XR_EXT_spatial_object_tracking должно быть включено до использования XrSpatialCapabilityConfigurationObjectTrackingEXT.
• type должно быть XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT
• next должен быть NULL или действительным указателем на следующую структуру в цепочке структур . См. также XrSpatialFeatureObjectSemanticLabelSubsetEXT.
• capability должно быть допустимым значением XrSpatialCapabilityEXT.
• enabledComponents должен быть указателем на массив из enabledComponentCount допустимых значений XrSpatialComponentTypeEXT.
• Значение параметра enabledComponentCount должно быть больше 0.

Гарантированные компоненты

Среда выполнения, поддерживающая XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, должна поддерживать следующие пространственные компоненты как гарантированные компоненты объектов, обнаруженных этой функцией, и должна перечислять их в xrEnumerateSpatialCapabilityComponentTypesEXT :

• XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT
• Как минимум один тип компонента, который предоставляет набор семантических ярлыков для отслеживаемых объектов. Функция отслеживания объектов не имеет смысла без компонента семантической метки. Хотя это расширение определяет XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT и XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT как возможные компоненты семантических меток для поддержки сред выполнения, другие расширения могут определять новые типы компонентов, чтобы предоставлять разные классы семантических меток, описывающих отслеживаемый объект. Подробные сведения о наборах семантических меток и типах компонентов приведены в [ext_spatial_semantic_labels_guidelines]. Среды выполнения могут не поддерживать ни XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT, ни XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT для функции отслеживания объектов, но должны поддерживать хотя бы один тип компонента, который предоставляет семантический ярлык.

Ограниченный 3D-компонент

Ограниченный 3D-компонент предоставляет центр и границы объекта, представленного объектом, на котором он находится. Подробнее об ограниченных 3D-моделях…

Дополнительные компоненты

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

Семантический ярлык объекта

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

typedef enum XrSpatialObjectSemanticLabelEXT {
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT = 2,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT = 3,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT = 4,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT = 5,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT = 6,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT = 7,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT = 8,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT = 9,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT = 10,
    XR_SPATIAL_OBJECT_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialObjectSemanticLabelEXT;

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

Для объектов с ярлыком XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT ось +Z компонента Bounded 3D должна примерно совпадать с нормалью поверхности экрана.

Для объектов с меткой XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT ось +Z компонента Bounded 3D должна совпадать с нормалью поверхности стены, на которой обнаружено произведение искусства.

Для объектов с меткой XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT ось +Z компонента Bounded 3D должна совпадать с нормалью поверхности стола.

Для всех остальных ярлыков в XrSpatialObjectSemanticLabelEXT приложение не должно делать никаких предположений о том, как XrBoxf :: center :: orientation, предоставленный компонентом Bounded 3D в объекте, соотносится с физическими атрибутами этого объекта.

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

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

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT

Среде выполнения не удалось классифицировать этот объект.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT

Объект – диван.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_BED_EXT

Объект – кровать.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CHAIR_EXT

Объект – стул.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT

Объект является таблицей.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_LAMP_EXT

Объект – лампа.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_PLANT_EXT

Объект – растение.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_DISPLAY_SCREEN_EXT

Объект является экраном, например монитором или телевизором.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_WALL_ART_EXT

Объект – настенное украшение.

XR_SPATIAL_OBJECT_SEMANTIC_LABEL_CABINET_EXT

Объект – шкаф.

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

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

typedef struct XrSpatialComponentObjectSemanticLabelListEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            semanticLabelCount;
    XrSpatialObjectSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentObjectSemanticLabelListEXT;

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

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

Чтобы запросить компонент семантического ярлыка объекта пространственных объектов в XrSpatialSnapshotEXT , включите XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавьте XrSpatialComponentObjectSemanticLabelListEXT в цепочку XrSpatialComponentDataQueryResultEXT :: next.

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

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

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

• Расширение XR_EXT_spatial_object_tracking должно быть включено до использования XrSpatialComponentObjectSemanticLabelListEXT.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• semanticLabels должен быть указателем на массив значений semanticLabelCount XrSpatialObjectSemanticLabelEXT.
• Значение параметра semanticLabelCount должно быть больше 0.

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

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

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

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

typedef struct XrSpatialFeatureObjectSemanticLabelSubsetEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  semanticLabelCount;
    const XrSpatialObjectSemanticLabelEXT*    semanticLabels;
} XrSpatialFeatureObjectSemanticLabelSubsetEXT;

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

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

Если среда выполнения перечисляет XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT из xrEnumerateSpatialCapabilityComponentTypesEXT для определенной возможности, она должна также перечислять XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT из xrEnumerateSpatialCapabilityFeaturesEXT для той же возможности. Если приложение включает XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT при настройке этой функции, оно может связать XrSpatialFeatureObjectSemanticLabelSubsetEXT с соответствующей структурой конфигурации этой функции, чтобы предоставить среде выполнения подмножество ярлыков, определенных в XrSpatialObjectSemanticLabelEXT . Среда выполнения может использовать этот набор ярлыков для оптимизации конвейеров отслеживания.

Среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE из xrCreateSpatialContextAsyncEXT, если semanticLabels содержит любой ярлык, не определенный в XrSpatialObjectSemanticLabelEXT, или если semanticLabels содержит XR_SPATIAL_OBJECT_SEMANTIC_LABEL_UNCATEGORIZED_EXT .

Среда выполнения должна возвращать XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT из xrCreateSpatialContextAsyncEXT, если приложение предоставляет действительный список меток в semanticLabels, но XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT не включен в массив XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents структуры конфигурации, к которой привязана XrSpatialFeatureObjectSemanticLabelSubsetEXT.

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

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

• Расширение XR_EXT_spatial_object_tracking должно быть включено до использования XrSpatialFeatureObjectSemanticLabelSubsetEXT.
• type должно быть XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• semanticLabels должен быть указателем на массив допустимых значений semanticLabelCount XrSpatialObjectSemanticLabelEXT.
• Значение параметра semanticLabelCount должно быть больше 0.

Семантический ярлык клавиатуры

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

typedef enum XrSpatialKeyboardSemanticLabelEXT {
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT = 2,
    XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialKeyboardSemanticLabelEXT;

Перечисление XrSpatialKeyboardSemanticLabelEXT описывает семантический ярлык для клавиатуры.

Размеры и ориентация XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT, представленные компонентом Bounded 3D для того же объекта, показаны на следующем изображении (с xyz = rgb), начинающемся в центре объекта.

Рисунок 30. Ориентация клавиатуры.

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

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_UNCATEGORIZED_EXT

Среде выполнения не удалось классифицировать этот объект.

XR_SPATIAL_KEYBOARD_SEMANTIC_LABEL_KEYBOARD_EXT

Объект является клавиатурой.

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

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

typedef struct XrSpatialComponentKeyboardSemanticLabelListEXT {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              semanticLabelCount;
    XrSpatialKeyboardSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentKeyboardSemanticLabelListEXT;

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

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

Чтобы запросить компонент семантической метки клавиатуры пространственных объектов в XrSpatialSnapshotEXT , включите XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавьте XrSpatialComponentKeyboardSemanticLabelListEXT в цепочку XrSpatialComponentDataQueryResultEXT :: next.

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

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

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

• Расширение XR_EXT_spatial_object_tracking должно быть включено до использования XrSpatialComponentKeyboardSemanticLabelListEXT.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• semanticLabels должен быть указателем на массив значений semanticLabelCount XrSpatialKeyboardSemanticLabelEXT.
• Значение параметра semanticLabelCount должно быть больше 0.

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

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

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

Семантический ярлык мыши

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

typedef enum XrSpatialMouseSemanticLabelEXT {
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT = 2,
    XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialMouseSemanticLabelEXT;

Перечисление XrSpatialMouseSemanticLabelEXT описывает семантический ярлык для мыши.

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

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_UNCATEGORIZED_EXT

Среде выполнения не удалось классифицировать этот объект.

XR_SPATIAL_MOUSE_SEMANTIC_LABEL_MOUSE_EXT

Объект – мышь.

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

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

typedef struct XrSpatialComponentMouseSemanticLabelListEXT {
    XrStructureType                    type;
    void*                              next;
    uint32_t                           semanticLabelCount;
    XrSpatialMouseSemanticLabelEXT*    semanticLabels;
} XrSpatialComponentMouseSemanticLabelListEXT;

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

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

Чтобы запросить компонент семантической метки мыши для пространственных объектов в XrSpatialSnapshotEXT , включите XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT в XrSpatialComponentDataQueryConditionEXT :: componentTypes и добавьте XrSpatialComponentMouseSemanticLabelListEXT в цепочку XrSpatialComponentDataQueryResultEXT :: next.

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

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

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

• Прежде чем использовать XrSpatialComponentMouseSemanticLabelListEXT, необходимо включить расширение XR_EXT_spatial_object_tracking.
• type должно быть XR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXT
• next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
• semanticLabels должен быть указателем на массив значений semanticLabelCount XrSpatialMouseSemanticLabelEXT.
• Значение параметра semanticLabelCount должно быть больше 0.

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

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

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

Пример кода

Настроить функцию отслеживания объектов

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

// Check if object tracking capability is supported
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Enumerate supported components for object tracking capability
XrSpatialCapabilityComponentTypesEXT objectComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, &objectComponents));
std::vector<XrSpatialComponentTypeEXT> objectCapabilityComponents(objectComponents.componentTypeCountOutput);
objectComponents.componentTypeCapacityInput = objectCapabilityComponents.size();
objectComponents.componentTypes = objectCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, &objectComponents));

// Check if the object & keyboard semantic labels component is supported
const auto supportsComponent = [&objectCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(objectCapabilityComponents.begin(), objectCapabilityComponents.end(), component) != objectCapabilityComponents.end();
};

const bool supportsObjectSemanticLabel = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT);
const bool supportsKeyboardSemanticLabel = supportsComponent(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);

// Enumerate supported features for object tracking capability
uint32_t featureCount;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> features(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT, featureCount, &featureCount, features.data()));

const bool supportsObjectSemanticLabelSubsetFeature = std::find(features.begin(), features.end(), XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT) != features.end();

// Create a spatial context
XrSpatialContextEXT spatialContext{};

// Enable the guaranteed components of the object tracking capability
std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
};
// Optionally enable the supported semantic labels
if (supportsObjectSemanticLabel) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT);
}
if (supportsKeyboardSemanticLabel) {
  enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);
}

// We only want to track sofa and table.
std::vector<XrSpatialObjectSemanticLabelEXT> objectSemanticLabelSubset = {
  XR_SPATIAL_OBJECT_SEMANTIC_LABEL_SOFA_EXT,
  XR_SPATIAL_OBJECT_SEMANTIC_LABEL_TABLE_EXT
};
XrSpatialFeatureObjectSemanticLabelSubsetEXT subsetFeature{XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT};
subsetFeature.semanticLabelCount = objectSemanticLabelSubset.size();
subsetFeature.semanticLabels = objectSemanticLabelSubset.data();

XrSpatialCapabilityConfigurationObjectTrackingEXT objectTrackingConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT};
objectTrackingConfig.capability = XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT;
objectTrackingConfig.enabledComponentCount = enabledComponents.size();
objectTrackingConfig.enabledComponents = enabledComponents.data();
if (supportsObjectSemanticLabelSubsetFeature) {
  objectTrackingConfig.next = &subsetFeature;
}

std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
  reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&objectTrackingConfig),
};

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;

// ...
// Discovery entities with the spatial context
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Обнаружение пространственных объектов и запрос данных компонентов

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

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT,
};
if (supportsKeyboardSemanticLabel) {
  snapshotComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT);
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  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 semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

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

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

    std::vector<XrBoxf> bounded3D(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded3DListEXT bounded3DList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT};
    bounded3DList.boundCount = bounded3D.size();
    bounded3DList.bounds = bounded3D.data();
    queryResult.next = &bounded3DList;

    std::vector<XrSpatialKeyboardSemanticLabelEXT> semanticLabels;
    XrSpatialComponentKeyboardSemanticLabelListEXT semanticLabelsList{XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT};
    if (supportsKeyboardSemanticLabel) {
      semanticLabels.resize(queryResult.entityIdCountOutput);
      semanticLabelsList.semanticLabelCount = semanticLabels.size();
      semanticLabelsList.semanticLabels = semanticLabels.data();
      semanticLabelsList.next = queryResult.next;
      queryResult.next = &semanticLabelsList;
    }

    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) {
        continue;
      }

      // 3D bounds for entity entityIds[i] is bounded3D[i].extents centered on bounded3D[i].center.

      if (supportsKeyboardSemanticLabel) {
        // semantic label for entity entityIds[i] is semanticLabels[i].
      }
    }

    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
  // ...
}

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

• XrSpatialCapabilityConfigurationObjectTrackingEXT

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

  • XrSpatialFeatureObjectSemanticLabelSubsetEXT

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

  • XrSpatialComponentKeyboardSemanticLabelListEXT
  • XrSpatialComponentMouseSemanticLabelListEXT
  • XrSpatialComponentObjectSemanticLabelListEXT

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

• XrSpatialKeyboardSemanticLabelEXT
• XrSpatialMouseSemanticLabelEXT
• XrSpatialObjectSemanticLabelEXT

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

• XR_EXT_SPATIAL_OBJECT_TRACKING_EXTENSION_NAME
• XR_EXT_spatial_object_tracking_SPEC_VERSION

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

  • XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

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

  • XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

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

  • XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT
  • XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT
  • XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

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

  • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_OBJECT_TRACKING_EXT
  • XR_TYPE_SPATIAL_COMPONENT_KEYBOARD_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_MOUSE_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_COMPONENT_OBJECT_SEMANTIC_LABEL_LIST_EXT
  • XR_TYPE_SPATIAL_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

Проблемы

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

• Версия 1, 3 июня 2025 г. (Нихав Джайн, Google)

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