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

ไม่มีการอ้างสิทธิ์ 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 ที่รวมเอนทิตีปัจจุบันไว้

เมื่อรันไทม์ได้รับข้อมูลสภาพแวดล้อมเพียงพอที่จะตรวจพบว่าระนาบ 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 ที่ระบุไว้ในไฟล์ Manifest เนื่องจากส่วนขยายนี้จะติดตามระนาบในสภาพแวดล้อม สิทธิ์ 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 หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • 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 ไว้ในรายการ enabledComponents ของ XrSpatialCapabilityConfigurationBaseHeaderEXT ของโครงสร้างที่ได้จาก XrSpatialCapabilityConfigurationBaseHeaderEXT ของความสามารถที่รองรับคอมโพเนนต์นี้

กรองเอนทิตีที่รวมไว้

โครงสร้าง XrSpatialDiscoveryUniqueEntitiesFilterANDROID มีการกำหนดไว้ดังนี้

typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
    XrStructureType    type;
    const void*        next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง

แอปพลิเคชัน สามารถ รวม 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 (Brian Chen)

    • คำอธิบายส่วนขยายเริ่มต้น