XR_ANDROID_spatial_component_subsumed_by
Строка имени
XR_ANDROID_spatial_component_subsumed_by
Тип расширения
Расширение экземпляра
Зарегистрированный добавочный номер
792
Пересмотр
1
Статус ратификации
Не ратифицировано
Зависимости расширений и версий
XR_EXT_spatial_entity
и
XR_EXT_spatial_plane_tracking
Дата последнего изменения
2025-08-19
Статус IP
Известных претензий на интеллектуальную собственность нет.
Авторы
Брайан Чен, Google
Кайл Чен, Google
Левана Чен, Google
Нихав Джайн, Google
Спенсер Куин, Google
Обзор
Это расширение основано на XR_EXT_spatial_entity и предоставляет новый компонент для XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , позволяющий использовать свойство subsumed_by.
Когда среда выполнения получит достаточно информации об окружении, чтобы определить, что два отслеживаемых самолета на самом деле являются одним и тем же, компонент subsumed_by с идентификатором одного из самолетов будет прикреплен к другому.
Это расширение также вводит новый фильтр, который приложение может использовать в сочетании с XrSpatialDiscoverySnapshotCreateInfoEXT для фильтрации любых объектов, к которым прикреплен компонент subsumed_by.
Разрешения
В манифесте Android-приложений должно быть указано разрешение android.permission.SCENE_UNDERSTANDING_COARSE, поскольку это расширение отслеживает плоскости в окружающей среде. Разрешение android.permission.SCENE_UNDERSTANDING_COARSE считается опасным.
(Уровень защиты: опасный)
Поддержка во время выполнения
Если среда выполнения поддерживает subumed_by, она должна поддерживать возможность отслеживания плоскости и указывать на это путем перечисления XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT в xrEnumerateSpatialCapabilitiesEXT .
Если среда выполнения предоставляет параметр subsumed_by, она должна указать это, перечислив 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.
Приложение может запрашивать компонент subsumed_by пространственных объектов в 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 .
Если subsumedUniqueIdCount меньше, чем XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput , среда выполнения должна возвращать XR_ERROR_SIZE_INSUFFICIENT из xrQuerySpatialComponentDataEXT .
Допустимое использование (неявное)
- Расширение
XR_ANDROID_spatial_component_subsumed_byнеобходимо включить перед использованием XrSpatialComponentSubsumedByListANDROID. -
typeдолжен бытьXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID -
nextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур. -
subsumedUniqueIdsдолжен быть указателем на массив значенийsubsumedUniqueIdCountXrSpatialEntityIdEXT - Параметр
subsumedUniqueIdCountдолжен быть больше0
Конфигурация
Если в XrSpatialCapabilityComponentTypesEXT :: componentTypes для возможности XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT перечислено XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID , приложение может включить его, включив перечисление в список XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents структуры, производной от XrSpatialCapabilityConfigurationBaseHeaderEXT , которая поддерживает этот компонент.
Фильтрация включенных сущностей
Структура XrSpatialDiscoveryUniqueEntitiesFilterANDROID определяется следующим образом:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
Описание участников
-
type— это XrStructureType данной структуры. -
next— этоNULLили указатель на следующую структуру в цепочке структур.
Приложение может включить XrSpatialDiscoveryUniqueEntitiesFilterANDROID в следующую цепочку 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_ANDROID_spatial_component_subsumed_byнеобходимо включить перед использованием XrSpatialDiscoveryUniqueEntitiesFilterANDROID. -
typeдолжен бытьXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID -
nextдолжно бытьNULLили допустимым указателем на следующую структуру в цепочке структур.
Пример кода
Настройка функции отслеживания плоскости
Приведенный ниже пример кода демонстрирует, как создать пространственный контекст с возможностью XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , поддерживающей параметр subsumed_by.
// Check runtime supported capabilities
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_PLANE_TRACKING_EXT) == capabilities.end()) {
return;
}
std::vector<XrSpatialComponentTypeEXT> planeTrackingComponents {
XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
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))
Данные компонента запроса
Приведенный ниже пример кода демонстрирует, как запрашивать данные компонента subsumed_by из контекста, настроенного с помощью XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .
// Create Discovery Snapshot
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
.type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
};
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT (
spatialContext, &discoverySnapshotCreateInfo, &future));
// Poll the state till snapshot it's ready.
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 {
XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
spatialContext, &createSnapshotCompletionInfo,
&completion));
if(completion.futureResult != XR_SUCCESS) return;
// 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(
completion.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(
completion.snapshot, &queryCond, &queryResult));
std::vector<XrSpatialEntityEXT> subsumedEntities;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
// access planes[i] for merged plane id
XrSpatialEntityIdEXT entityId = queryResult.entityIds[i];
XrSpatialEntityIdEXT subsumedUniqueId = subsumedUniqueIds[i];
// create handle via entityId
XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
.type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
.entityId = entityId,
};
XrSpatialEntityEXT entity = XR_NULL_HANDLE;
xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);
subsumedEntities.push_back(entity);
}
// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);
Отфильтровать включенные сущности
Приведенный ниже пример кода демонстрирует, как отфильтровать сущности с компонентом subsumed_by, прикрепленным к снимку обнаружения, используя фильтр, а также как запросить идентификатор сущности, входящей в состав компонента subsumed_by.
// Init filter
XrSpatialDiscoveryUniqueEntitiesFilterANDROID filter {
.type = XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID,
};
// Chain filter to the snapshot create info
// WARNING: Chain 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
};
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 {
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
// Bounded2D to render subsuming planes
std::vector<XrSpatialComponentTypeEXT> queryComponents {
XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
};
XrSpatialComponentDataQueryConditionEXT queryCond {
.type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
.componentTypeCount = 1,
.componentTypes = queryComponents.data(),
};
XrSpatialComponentDataQueryResultEXT queryResult {
.type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};
CHK_XR(xrQuerySpatialComponentDataEXT(
completion.snapshot, &queryCond, &queryResult));
// Chain Bounded2D list
std::vector<XrSpatialBounded2DDataEXT> bounded2dData;
bounded2dData.resize(queryResult.entityIdCountOutput);
XrSpatialComponentBounded2DListEXT bounded2dList {
.type = XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT,
.boundCount = static_cast<uint32_t>(bounded2dData.size()),
.bounds = bounded2dData.data(),
};
// Query again
queryResult.next = &bounded2dList;
CHK_XR(xrQuerySpatialComponentDataEXT(
completion.snapshot, &queryCond, &queryResult));
std::vector<XrSpatialEntityEXT> subsumingPlanes;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
// access planes[i] for merged plane id
XrSpatialEntityIdEXT entityId = queryResult.entityIds[i];
// create handle via entityId.
XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
.type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
.entityId = entityId,
};
XrSpatialEntityEXT entity = XR_NULL_HANDLE;
xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);
subsumingPlanes.push_back(entity);
}
// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);
Новые сооружения
Расширение XrSpatialComponentDataQueryResultEXT :
Расширение XrSpatialDiscoverySnapshotCreateInfoEXT :
Новые константы перечислений
-
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.11.2025 (Брайан Чен)
- Первоначальное описание расширения.