XR_ANDROID_spatial_component_subsumed_by
Chuỗi tên
XR_ANDROID_spatial_component_subsumed_by
Loại tiện ích
Tiện ích thực thể
Số tiện ích đã đăng ký
792
Bản sửa đổi
1
Trạng thái phê chuẩn
Chưa phê chuẩn
Tiện ích và các phần phụ thuộc vào phiên bản
XR_EXT_spatial_entity
và
XR_EXT_spatial_plane_tracking
Ngày sửa đổi gần nhất
2025-08-19
Trạng thái IP
Không có thông báo xác nhận quyền sở hữu IP nào được biết.
Cộng tác viên
Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Tổng quan
Tiện ích này được xây dựng dựa trên XR_EXT_spatial_entity và cung cấp một thành phần mới cho XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT để hiển thị thuộc tính subsumed_by.
Khi thời gian chạy thu thập đủ thông tin về môi trường để phát hiện 2 mặt phẳng được theo dõi thực sự là giống nhau, thì thành phần subsumed_by có mã nhận dạng của một trong các mặt phẳng sẽ được đính kèm vào mặt phẳng còn lại.
Tiện ích này cũng giới thiệu một bộ lọc mới mà ứng dụng có thể liên kết với XrSpatialDiscoverySnapshotCreateInfoEXT để lọc mọi thực thể có thành phần subsumed_by được đính kèm.
Quyền
Các ứng dụng Android phải có quyền android.permission.SCENE_UNDERSTANDING_COARSE được liệt kê trong tệp kê khai của chúng vì tiện ích này theo dõi các mặt phẳng trong môi trường. Quyền android.permission.SCENE_UNDERSTANDING_COARSE được coi là một quyền nguy hiểm.
(cấp độ bảo vệ: nguy hiểm)
Hỗ trợ thời gian chạy
Nếu thời gian chạy hỗ trợ subumed_by, thì thời gian chạy phải hỗ trợ khả năng theo dõi mặt phẳng và cho biết điều này bằng cách liệt kê XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT trong xrEnumerateSpatialCapabilitiesEXT .
Nếu thời gian chạy cung cấp subsumed_by, thì thời gian chạy phải cho biết điều này bằng cách liệt kê XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dưới dạng một thành phần được hỗ trợ cho khả năng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT trong xrEnumerateSpatialCapabilityComponentTypesEXT .
Tất cả dữ liệu thành phần của thực thể được đính kèm XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID phải giống với thực thể bao trùm thực thể đó.
Thành phần được bao trùm
Dữ liệu thành phần
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID sử dụng cấu trúc XrSpatialEntityIdEXT cho dữ liệu của mình, cấu trúc này đại diện cho mã nhận dạng của thực thể bao trùm.
Cấu trúc danh sách thành phần để truy vấn dữ liệu
Cấu trúc XrSpatialComponentSubsumedByListANDROID được xác định như sau:
typedef struct XrSpatialComponentSubsumedByListANDROID {
XrStructureType type;
void* next;
uint32_t subsumedUniqueIdCount;
XrSpatialEntityIdEXT* subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;
Mô tả thành phần
typelà XrStructureType của cấu trúc này.nextlàNULLhoặc một con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.subsumedUniqueIdCountlà mộtuint32_tmô tả số lượng phần tử trong mảngsubsumedUniqueIds.subsumedUniqueIdslà một mảngXrSpatialEntityIdEXT.
Ứng dụng có thể truy vấn thành phần subsumed_by của các thực thể không gian trong XrSpatialSnapshotEXT bằng cách thêm XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID vào chuỗi tiếp theo của XrSpatialComponentDataQueryResultEXT .
Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID nằm trong chuỗi tiếp theo của XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID không được đưa vào XrSpatialComponentDataQueryConditionEXT :: componentTypes .
Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu subsumedUniqueIdCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .
Cách sử dụng hợp lệ (Ngụ ý)
- Tiện ích
XR_ANDROID_spatial_component_subsumed_byphải được bật trước khi sử dụng XrSpatialComponentSubsumedByListANDROID -
typephải làXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc -
subsumedUniqueIdsphải là một con trỏ trỏ đến một mảng gồm các giá trịsubsumedUniqueIdCountXrSpatialEntityIdEXT - Tham số
subsumedUniqueIdCountphải lớn hơn0
Cấu hình
Nếu XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho khả năng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, thì ứng dụng có thể bật tính năng này bằng cách đưa enum vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc XrSpatialCapabilityConfigurationBaseHeaderEXT dẫn xuất của khả năng hỗ trợ thành phần này.
Lọc các thực thể được bao trùm
Cấu trúc XrSpatialDiscoveryUniqueEntitiesFilterANDROID được xác định như sau:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
Mô tả thành phần
typelà XrStructureType của cấu trúc này.nextlàNULLhoặc một con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
Ứng dụng có thể đưa XrSpatialDiscoveryUniqueEntitiesFilterANDROID vào chuỗi tiếp theo của XrSpatialDiscoverySnapshotCreateInfoEXT để lấy ảnh chụp nhanh với các thực thể không được một thực thể khác bao trùm.
Nếu các ứng dụng liên kết XrSpatialDiscoveryUniqueEntitiesFilterANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT trong khi đưa thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID vào XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .
Nếu các ứng dụng liên kết XrSpatialDiscoveryUniqueEntitiesFilterANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT nhưng không liệt kê bất kỳ thành phần nào trong XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , thì thời gian chạy phải đưa tất cả các thực thể không gian vào ảnh chụp nhanh có tập hợp các thành phần được liệt kê trong XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents cho các khả năng được định cấu hình cho spatialContext, ngoại trừ các thực thể có thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Cách sử dụng hợp lệ (Ngụ ý)
- Tiện ích
XR_ANDROID_spatial_component_subsumed_byphải được bật trước khi sử dụng XrSpatialDiscoveryUniqueEntitiesFilterANDROID -
typephải làXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID -
nextphải làNULLhoặc một con trỏ hợp lệ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc
Mã ví dụ
Định cấu hình khả năng theo dõi mặt phẳng
Mã ví dụ sau đây minh hoạ cách tạo một ngữ cảnh không gian có khả năng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT hỗ trợ 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))
Truy vấn dữ liệu thành phần
Mã ví dụ sau đây minh hoạ cách truy vấn dữ liệu thành phần subsumed_by từ ngữ cảnh được định cấu hình bằng 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);
Lọc các thực thể được bao trùm
Mã ví dụ sau đây minh hoạ cách lọc các thực thể có thành phần subsumed_by được đính kèm từ ảnh chụp nhanh khám phá bằng bộ lọc, cũng như truy vấn mã nhận dạng thực thể của các thực thể bao trùm.
// 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);
Cấu trúc mới
Mở rộng XrSpatialComponentDataQueryResultEXT :
Mở rộng XrSpatialDiscoverySnapshotCreateInfoEXT :
Hằng số enum mới
XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSIONMở rộng XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
Mở rộng XrStructureType :
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
Vấn đề
Nhật ký phiên bản
Bản sửa đổi 1, 19/11/2025 (Brian Chen)
- Mô tả tiện ích ban đầu.