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 状态
没有已知的 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。
当运行时获取足够的环境信息来检测到 2 个被跟踪的平面实际上是同一个平面时，系统会将 ID 为其中一个平面的 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 权限被视为危险权限。
（保护级别：危险）
运行时支持
如果运行时能够将一个平面包含到另一个平面中，则必须 通过在 xrEnumerateSpatialCapabilityComponentTypesEXT 中将 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 列为 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 功能的支持组件来指明这一点。
附加实体的 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 的所有组件数据必须 与包含它的实体相同。
Subsumed By 组件
组件数据
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 使用 XrSpatialEntityIdEXT 结构作为其数据，该结构表示包含实体的 ID。
用于查询数据的组件列表结构体
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_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID 添加到 XrSpatialComponentDataQueryResultEXT 的下一个链中，查询 XrSpatialSnapshotEXT 中空间实体的 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 组件。
如果 XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID 位于 XrSpatialComponentDataQueryResultEXT :: next 的下一个链中，但 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 未包含在 XrSpatialComponentDataQueryConditionEXT :: componentTypes 中，则运行时 必须 从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_VALIDATION_FAILURE。
如果 subsumedUniqueIdCount 小于 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput，则运行时 必须 从 xrQuerySpatialComponentDataEXT 返回 XR_ERROR_SIZE_INSUFFICIENT。
有效用法（隐式）
- 必须先启用
XR_ANDROID_spatial_component_subsumed_by扩展程序，然后才能使用 XrSpatialComponentSubsumedByListANDROID -
type必须 为XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID -
next必须 为NULL或指向结构链中下一个结构的有效指针 -
subsumedUniqueIds必须 是指向subsumedUniqueIdCountXrSpatialEntityIdEXT值数组的指针 -
subsumedUniqueIdCount参数 必须 大于0
配置
如果在 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 中为 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 功能枚举了 XrSpatialCapabilityComponentTypesEXT :: componentTypes，则应用可以通过在支持此组件的功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT 派生结构的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 列表中添加枚举来启用它。
过滤包含的实体
XrSpatialDiscoveryUniqueEntitiesFilterANDROID 结构的定义如下：
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
成员说明
type是此结构的 XrStructureType。next是NULL或指向结构链中下一个结构的指针。
应用可以 在 XrSpatialDiscoverySnapshotCreateInfoEXT 的 next 链中添加 XrSpatialDiscoveryUniqueEntitiesFilterANDROID，以获取包含未被其他实体包含的实照。
如果应用在 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中添加 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 组件的同时，将 XrSpatialDiscoveryUniqueEntitiesFilterANDROID 链接到 XrSpatialDiscoverySnapshotCreateInfoEXT，则运行时 必须 返回 XR_ERROR_VALIDATION_FAILURE。
如果应用将 XrSpatialDiscoveryUniqueEntitiesFilterANDROID 链接到 XrSpatialDiscoverySnapshotCreateInfoEXT，但未在 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中列出任何组件，则运行时 必须 在快照中包含所有空间实体，这些实体具有为 spatialContext 配置的功能在 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 中枚举的组件集，但具有 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 功能的空间上下文，该功能支持 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_CAPABILITY_PLANE_TRACKING_EXT 的上下文中查询 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 组件数据。
// 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 组件的实体，以及如何查询包含实体的实体 ID。
// 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_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION-
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
扩展 XrStructureType：
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
问题
版本历史记录
修订版 1，2025-11-19（Brian Chen）
- 初始扩展程序说明。