XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

Loại phần mở rộng

Tiện ích Instance

Số máy nhánh đã đăng ký

792

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần mở rộng và các phần phụ thuộc của phiên bản

XR_EXT_spatial_entity

XR_EXT_spatial_plane_tracking

Ngày sửa đổi gần đây nhất

2025-08-19

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu nào đã biết về quyền sở hữu trí tuệ.

Cộng tác viên

Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Tổng quan

Tiện ích này dựa trên XR_EXT_spatial_entity và cung cấp một thành phần mới cho XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT để hiển thị XrSpatialEntityIdEXT bao gồm thực thể hiện tại.

Khi thời gian chạy đã thu thập đủ thông tin về môi trường để phát hiện thấy 2 mặt phẳng được theo dõi thực sự là một, thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID có mã nhận dạng của một trong các mặt phẳng sẽ được đính kèm vào mặt phẳng còn lại. Kể từ đó, ứng dụng chỉ cần xử lý thực thể không có thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Tiện ích này cũng giới thiệu một bộ lọc mới mà ứng dụng có thể liên kết với XrSpatialDiscoverySnapshotCreateInfoEXT để lọc ra mọi thực thể có thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Quyền

Các ứng dụng Android phải có quyền android.permission.SCENE_UNDERSTANDING_COARSE được liệt kê trong tệp kê khai vì tiện ích này theo dõi các mặt phẳng trong môi trường. Quyền android.permission.SCENE_UNDERSTANDING_COARSE được coi là một quyền nguy hiểm.

(cấp độ bảo vệ: nguy hiểm)

Hỗ trợ thời gian chạy

Nếu thời gian chạy có khả năng đưa một mặt phẳng vào một mặt phẳng khác, thì thời gian chạy phải cho biết điều này bằng cách liệt kê XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID làm thành phần được hỗ trợ cho khả năng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT trong xrEnumerateSpatialCapabilityComponentTypesEXT .

Tất cả dữ liệu thành phần của thực thể XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID được đính kèm phải giống hệt với thực thể bao hàm dữ liệu đó.

Được bao gồm trong thành phần

Dữ liệu thành phần

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID sử dụng cấu trúc XrSpatialEntityIdEXT cho dữ liệu của mình, đại diện cho mã nhận dạng của thực thể bao hàm.

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentSubsumedByListANDROID được xác định như sau:

typedef struct XrSpatialComponentSubsumedByListANDROID {
    XrStructureType          type;
    void*                    next;
    uint32_t                 subsumedUniqueIdCount;
    XrSpatialEntityIdEXT*    subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;

Nội dung mô tả thành viên

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • subsumedUniqueIdCount là một uint32_t mô tả số lượng phần tử trong mảng subsumedUniqueIds.
  • subsumedUniqueIds là một mảng XrSpatialEntityIdEXT .

Ứng dụng có thể truy vấn thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID của các thực thể không gian trong XrSpatialSnapshotEXT bằng cách thêm XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID vào chuỗi tiếp theo của XrSpatialComponentDataQueryResultEXT .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID nằm trong chuỗi tiếp theo của XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu subsumedUniqueIdCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Sử dụng hợp lệ (Ngầm ẩn)

  • Bạn phải bật tiện ích XR_ANDROID_spatial_component_subsumed_by trước khi sử dụng XrSpatialComponentSubsumedByListANDROID
  • type phảiXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next phảiNULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
  • subsumedUniqueIds phải là con trỏ đến một mảng gồm các giá trị subsumedUniqueIdCount XrSpatialEntityIdEXT
  • Tham số subsumedUniqueIdCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho khả năng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, thì ứng dụng có thể bật chức năng này bằng cách đưa enum vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc phái sinh XrSpatialCapabilityConfigurationBaseHeaderEXT của khả năng hỗ trợ thành phần này.

Lọc các thực thể được bao hàm

Cấu trúc XrSpatialDiscoveryUniqueEntitiesFilterANDROID được xác định như sau:

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

Nội dung mô tả thành viên

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.

Ứng dụng có thể bao gồm XrSpatialDiscoveryUniqueEntitiesFilterANDROID trong chuỗi next của XrSpatialDiscoverySnapshotCreateInfoEXT để lấy một ảnh chụp nhanh có các thực thể không bị một thực thể khác bao hàm.

Nếu các ứng dụng liên kết XrSpatialDiscoveryUniqueEntitiesFilterANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT trong khi bao gồm thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID trong XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .

Nếu các chuỗi ứng dụng XrSpatialDiscoveryUniqueEntitiesFilterANDROID đến XrSpatialDiscoverySnapshotCreateInfoEXT nhưng không liệt kê bất kỳ thành phần nào trong XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , thì thời gian chạy phải bao gồm tất cả các thực thể không gian trong ảnh chụp nhanh có tập hợp các thành phần được liệt kê trong XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents cho các chức năng được định cấu hình cho spatialContext , ngoại trừ các thực thể có thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Sử dụng hợp lệ (Ngầm ẩn)

Mã ví dụ

Định cấu hình khả năng theo dõi mặt phẳng

Đoạn mã ví dụ sau đây minh hoạ cách tạo một ngữ cảnh không gian có khả năng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT hỗ trợ 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))

Truy vấn dữ liệu thành phần

Đoạn mã ví dụ sau đây minh hoạ cách truy vấn dữ liệu thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID từ ngữ cảnh được định cấu hình bằng 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);

Lọc các thực thể được bao hàm

Đoạn mã ví dụ sau đây minh hoạ cách lọc các thực thể có thành phần XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID được đính kèm từ ảnh chụp nhanh khám phá bằng bộ lọc, cũng như truy vấn mã nhận dạng thực thể của các thực thể bao hàm.

// 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);

Cấu trúc mới

Hằng số Enum mới

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION
  • Mở rộng XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
  • Mở rộng XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 1, ngày 19/11/2025 (Brian Chen)

    • Nội dung mô tả ban đầu của tiện ích.