XR_ANDROID_spatial_component_subsumed_by
מחרוזת שם
XR_ANDROID_spatial_component_subsumed_by
סוג התוסף
הרחבת המכונה
מספר שלוחה רשום
792
Revision
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 שכולל את הישות הנוכחית.
כשסביבת זמן הריצה אוספת מספיק מידע על הסביבה כדי לזהות ששני המישורים המעקב הם למעשה אותו מישור, רכיב 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 נחשבת להרשאה מסוכנת.
(רמת ההגנה: מסוכן)
תמיכה בזמן ריצה
אם סביבת זמן הריצה יכולה להכיל מישור אחד בתוך מישור אחר, חובה לציין זאת על ידי מניית 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.
האפליקציה יכולה לשלוח שאילתה לרכיב XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID של הישויות המרחביות ב-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 .
סביבת זמן הריצה חייבת להחזיר XR_ERROR_SIZE_INSUFFICIENT מ-xrQuerySpatialComponentDataEXT אם subsumedUniqueIdCount קטן מ-XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .
שימוש תקף (משתמע)
- צריך להפעיל את התוסף
XR_ANDROID_spatial_component_subsumed_byלפני שמשתמשים ב-XrSpatialComponentSubsumedByListANDROID -
typeחייב להיותXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID -
nextחייב להיותNULLאו מצביע תקין אל המבנה הבא בשרשרת המבנים -
subsumedUniqueIdsחייב להיות מצביע למערך שלsubsumedUniqueIdCountערכים שלXrSpatialEntityIdEXT - הפרמטר
subsumedUniqueIdCountחייב להיות גדול מ-0
הגדרות אישיות
אם XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID מפורט ב-XrSpatialCapabilityComponentTypesEXT :: componentTypes עבור היכולת XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, האפליקציה יכולה להפעיל אותה על ידי הכללת ה-enum ברשימה XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents של המבנה הנגזר XrSpatialCapabilityConfigurationBaseHeaderEXT של היכולת שתומכת ברכיב הזה.
סינון ישויות שנכללות בישויות אחרות
המבנה של XrSpatialDiscoveryUniqueEntitiesFilterANDROID מוגדר כך:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
תיאורים של חברי הקבוצה
-
typeהוא XrStructureType של המבנה הזה. -
nextהואNULLאו מצביע למבנה הבא בשרשרת מבנים.
האפליקציה יכולה לכלול את XrSpatialDiscoveryUniqueEntitiesFilterANDROID בשרשרת next של 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 שתומכת ב-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_COMPONENT_TYPE_SUBSUMED_BY_ANDROID מהקשר שהוגדר באמצעות 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);
סינון ישויות שנכללות בישויות אחרות
בדוגמת הקוד הבאה אפשר לראות איך מסננים ישויות עם רכיב XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID שמצורף לתמונת מצב של גילוי באמצעות המסנן, ואיך שולחים שאילתה לגבי מזהה הישות של הישויות הכלולות.
// 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);
מבנים חדשים
הרחבה של XrSpatialComponentDataQueryResultEXT :
הרחבה של XrSpatialDiscoverySnapshotCreateInfoEXT :
New Enum Constants
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, 19.11.2025 (Brian Chen)
- התיאור הראשוני של התוסף.