XR_ANDROID_spatial_component_subsumed_by
Name String
XR_ANDROID_spatial_component_subsumed_by
Loại phần mở rộng
Tiện ích Instance
Số máy nhánh đã đăng ký
792
Bản sửa đổi
1
Trạng thái phê chuẩn
Chưa được phê chuẩn
Phần mở rộng và các phần phụ thuộc của phiên bản
XR_EXT_spatial_entity
và
XR_EXT_spatial_plane_tracking
Ngày sửa đổi gần đây 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 nào đã biết về quyền sở hữu trí tuệ.
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 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ị XrSpatialEntityIdEXT bao gồm thực thể hiện tại.
Khi thời gian chạy đã thu thập đủ thông tin về môi trường để phát hiện thấy 2 mặt phẳng được theo dõi thực sự là một, thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 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. Kể từ đó, ứng dụng chỉ cần xử lý thực thể không có thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
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 ra mọi thực thể có thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
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 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 có khả năng đưa một mặt phẳng vào một mặt phẳng khác, 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 làm 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ể XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID được đính kèm phải giống hệt với thực thể bao hàm dữ liệu đó.
Được bao gồm trong thành phần
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, đại diện cho mã nhận dạng của thực thể bao hà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;
Nội dung mô tả thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặc con 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 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 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ó trong 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 .
Sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_spatial_component_subsumed_bytrướ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ệ đến cấu trúc tiếp theo trong chuỗi cấu trúc -
subsumedUniqueIdsphải là con 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 chức năng này bằng cách đưa enum vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc phái sinh XrSpatialCapabilityConfigurationBaseHeaderEXT của khả năng hỗ trợ thành phần này.
Lọc các thực thể được bao hàm
Cấu trúc XrSpatialDiscoveryUniqueEntitiesFilterANDROID được xác định như sau:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
Nội dung mô tả thành viên
typelà XrStructureType của cấu trúc này.nextlàNULLhoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
Ứng dụng có thể bao gồm XrSpatialDiscoveryUniqueEntitiesFilterANDROID trong chuỗi next của XrSpatialDiscoverySnapshotCreateInfoEXT để lấy một ảnh chụp nhanh có các thực thể không bị một thực thể khác bao hàm.
Nếu các ứng dụng liên kết XrSpatialDiscoveryUniqueEntitiesFilterANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT trong khi bao gồm thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID trong XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .
Nếu các chuỗi ứng dụng XrSpatialDiscoveryUniqueEntitiesFilterANDROID đến 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 bao gồm tất cả các thực thể không gian trong ả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 chức 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.
Sử dụng hợp lệ (Ngầm ẩn)
- Bạn phải bật tiện ích
XR_ANDROID_spatial_component_subsumed_bytrướ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ệ đế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
Đoạn 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ợ 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))
Truy vấn dữ liệu thành phần
Đoạn mã ví dụ sau đây minh hoạ cách truy vấn dữ liệu thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID từ ngữ cảnh được định cấu hình bằng 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);
Lọc các thực thể được bao hàm
Đoạn mã ví dụ sau đây minh hoạ cách lọc các thực thể có thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID đượ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 hàm.
// 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);
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 đề
Danh sách phiên bản
Bản sửa đổi 1, ngày 19/11/2025 (Brian Chen)
- Nội dung mô tả ban đầu của tiện ích.