XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

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

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

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

792

Revision

1

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

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

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

XR_EXT_spatial_entity
и
XR_EXT_spatial_plane_tracking

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

2025-08-19

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

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

Авторы

Брайан Чен (Brian Chen), Google
Кайл Чен (Kyle Chen), Google
Леван Чен (Levana Chen), Google
Нихав Джайн (Nihav Jain), Google
Спенсер Куин (Spencer Quin), Google

Обзор

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

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

Это расширение также добавляет новый фильтр, который приложение может связать с XrSpatialDiscoverySnapshotCreateInfoEXT, чтобы отфильтровать все объекты с компонентом XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Разрешения

В манифесте приложений для Android должно быть указано разрешение android.permission.SCENE_UNDERSTANDING_COARSE, поскольку это расширение отслеживает плоскости в окружающей среде. Разрешение android.permission.SCENE_UNDERSTANDING_COARSE считается опасным.

(уровень защиты: опасный)

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

Если среда выполнения способна объединять одну плоскость с другой, она должна указать это, перечислив XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID как поддерживаемый компонент для возможности XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT в xrEnumerateSpatialCapabilityComponentTypesEXT .

Все данные компонента прикрепленного объекта XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID должны быть идентичны данным объекта, который его включает.

Включено в компонент

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

В XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID используется структура XrSpatialEntityIdEXT, которая представляет идентификатор включающего объекта.

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

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

typedef struct XrSpatialComponentSubsumedByListANDROID {
    XrStructureType          type;
    void*                    next;
    uint32_t                 subsumedUniqueIdCount;
    XrSpatialEntityIdEXT*    subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;

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

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

Приложение может запрашивать компонент XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID пространственных объектов в XrSpatialSnapshotEXT, добавив XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID в следующую цепочку XrSpatialComponentDataQueryResultEXT .

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

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

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

  • Расширение XR_ANDROID_spatial_component_subsumed_by должно быть включено до использования XrSpatialComponentSubsumedByListANDROID.
  • type должно быть XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next должно быть NULL или действительным указателем на следующую структуру в цепочке структур.
  • subsumedUniqueIds должен быть указателем на массив значений subsumedUniqueIdCount XrSpatialEntityIdEXT.
  • Значение параметра subsumedUniqueIdCount должно быть больше 0.

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

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

Фильтр поглощенных объектов

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

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

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

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

Приложение может включать XrSpatialDiscoveryUniqueEntitiesFilterANDROID в цепочку next XrSpatialDiscoverySnapshotCreateInfoEXT, чтобы получить снимок с объектами, которые не включены в другой объект.

Если приложения связывают XrSpatialDiscoveryUniqueEntitiesFilterANDROID с XrSpatialDiscoverySnapshotCreateInfoEXT, включая компонент XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID в XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, среда выполнения должна возвращать XR_ERROR_VALIDATION_FAILURE .

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

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

Пример кода

Настройка функции отслеживания плоскостей

В примере кода ниже показано, как создать пространственный контекст с возможностью XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, которая поддерживает XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID .

// Check runtime supported capabilities
uint32_t capabilityCount = 0;
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_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Enumerate supported components for plane tracking capability
XrSpatialCapabilityComponentTypesEXT planeComponents{
  .type = XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT,
};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));
std::vector<XrSpatialComponentTypeEXT> planeCapabilityComponents(planeComponents.componentTypeCountOutput);
planeComponents.componentTypeCapacityInput = planeCapabilityComponents.size();
planeComponents.componentTypes = planeCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &planeComponents));

const auto supportsComponent = [&planeCapabilityComponents](XrSpatialComponentTypeEXT component) {
  return std::find(planeCapabilityComponents.begin(), planeCapabilityComponents.end(), component) != planeCapabilityComponents.end();
};


std::vector<XrSpatialComponentTypeEXT> planeTrackingComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};

if (supportsComponent(XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID)) {
  planeTrackingComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID);
}

// Create capability config for plane tracking
XrSpatialCapabilityConfigurationPlaneTrackingEXT planeTrackingConfig {
  .type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT,
  .enabledComponentCount = (uint32_t)planeTrackingComponents.size(),
  .enabledComponents = planeTrackingComponents.data(),
};

// Create spatial context
std::vector<const XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
capabilityConfigs.push_back(reinterpret_cast<const XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&planeTrackingConfig));

XrSpatialContextCreateInfoEXT contextCreateInfo {
  .type = XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT,
  .next = nullptr,
  .capabilityConfigCount = (uint32_t)capabilityConfigs.size(),
  .capabilityConfigs = capabilityConfigs.data(),
};

CHK_XR(xrCreateSpatialContextAsyncEXT(session, &contextCreateInfo, &future))

// Completes creating spatial context
XrCreateSpatialContextCompletionEXT contextCompletion{
XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialContextCompleteEXT(session, future, &contextCompletion))

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

В примере кода ниже показано, как запросить данные компонента XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID из контекста, настроенного с помощью XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .

// previously created
XrSpatialSnapshotEXT snapshot;

// Query subsumed_by components
std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
};

XrSpatialComponentDataQueryConditionEXT queryCond {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
  .componentTypeCount = 1,
  .componentTypes     = enabledComponents.data(),
};

XrSpatialComponentDataQueryResultEXT queryResult {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};

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

// Query again with allocated memory
std::vector<XrSpatialEntityIdEXT> subsumedUniqueIds;
subsumedUniqueIds.resize(queryResult.entityIdCountOutput);
XrSpatialComponentSubsumedByListANDROID subsumedByList {
  .type = XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID,
  .subsumedUniqueIdCount = static_cast<uint32_t>(subsumedUniqueIds.size()),
  .subsumedUniqueIds = subsumedUniqueIds.data(),
};

queryResult.next = &subsumedByList;
CHK_XR(xrQuerySpatialComponentDataEXT(
           snapshot, &queryCond, &queryResult));

for (uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // Plane was subsumed, remove it from processing logic
  // removeEntityFromProcessingLogic(queryResult.entityIds[i], /*replaceWith=*/ subsumedByList.subsumedUniqueIds[i]);
}

// Cleanup
xrDestroySpatialSnapshotEXT(snapshot);

Фильтрация поглощенных объектов

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

// Init filter
XrSpatialDiscoveryUniqueEntitiesFilterANDROID filter {
  .type = XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID,
};

// Chain filter to the snapshot create info
// WARNING: Chaining the filter while include subsumed_by component in the
// componentTypes is invalid
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = &filter
};

XrFutureEXT future {XR_NULL_FUTURE_EXT};
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &discoverySnapshotCreateInfo, &future))

waitUntilReady(future);

// Complete async operation.
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
  createSnapshotCompletionInfo {
    .type   = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
    .baseSpace = space,
    .time      = updateTime,
    .future    = future,
  };

XrCreateSpatialDiscoverySnapshotCompletionEXT completion {
  .type = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT,
};

CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
           spatialContext, &createSnapshotCompletionInfo,
           &completion));

if(completion.futureResult != XR_SUCCESS) return;

// Subsumed entities has already been filtered out in this snapshot,
// now query the various components of the entities.

// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);

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

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

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION

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

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

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

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Проблемы

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

  • Версия 1, 19 ноября 2025 г. (Брайан Чэнь)

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