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
קייל צ'ן, Google
לבנה צ'ן, Google
ניהב ג'יין, Google
ספנסר קווין, Google
סקירה כללית
התוסף הזה מבוסס על XR_EXT_spatial_entity ומספק רכיב חדש ל-XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT כדי לחשוף את XrSpatialEntityIdEXT שכולל את הישות הנוכחית.
כשהסביבה בזמן הריצה אוספת מספיק מידע על הסביבה כדי לזהות ש-2 מישורים במעקב הם למעשה אותו מישור, הרכיב 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חייב להיות מצביע למערך של ערכיsubsumedUniqueIdCountXrSpatialEntityIdEXT - הפרמטר
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 :
קבועי Enum חדשים
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 (בריאן צ'ן)
- תיאור התוסף הראשוני.