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 חייב להיות מצביע למערך של ערכי 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_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);

מבנים חדשים

קבועי Enum חדשים

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION
  • הרחבה של XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
  • הרחבה של XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

בעיות

היסטוריית הגרסאות

  • גרסה 1, 19.11.2025 (בריאן צ'ן)

    • תיאור התוסף הראשוני.