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 的 Brian Chen
Google 的 Kyle Chen
Google 的 Levana Chen
Google 的 Nihav Jain
Google 的 Spencer Quin
總覽
這項擴充功能以 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附加實體必須與 subsumes 實體完全相同。
由元件取代
元件資料
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的陣列。
應用程式可以在 XrSpatialSnapshotEXT 中查詢空間實體的 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 元件,方法是在下一個 XrSpatialComponentDataQueryResultEXT 鏈結中新增 XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_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 列舉於 XrSpatialCapabilityComponentTypesEXT :: componentTypes 的 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 功能中,應用程式可以在支援這個元件的功能的 XrSpatialCapabilityConfigurationBaseHeaderEXT 衍生結構的 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 清單中加入列舉,啟用這項功能。
篩選併入的實體
XrSpatialDiscoveryUniqueEntitiesFilterANDROID 結構體的定義如下:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
成員說明
type是這個結構的 XrStructureType。next是NULL,或是結構鏈中下一個結構的指標。
應用程式可以在 XrSpatialDiscoverySnapshotCreateInfoEXT 的 next 鏈結中加入 XrSpatialDiscoveryUniqueEntitiesFilterANDROID,取得未由其他實體併入的實體快照。
如果應用程式將 XrSpatialDiscoveryUniqueEntitiesFilterANDROID 鏈結至 XrSpatialDiscoverySnapshotCreateInfoEXT,同時在 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes 中加入 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 元件,則執行階段「必須」傳回 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_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 的 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 功能空間環境。
// 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 元件的實體,以及查詢 subsuming 實體的實體 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正在擴充 XrSpatialComponentTypeEXT:
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)
- 擴充功能說明。