XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

792

Bản sửa đổi

1

Trạng thái phê chuẩn

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

Phần phụ thuộc của tiện ích và phiên bản

XR_EXT_spatial_entity
và
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ó tuyên bố nào về tài sản 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 được xây dựng 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ự giống nhau, 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. Từ đó trở đi, ứ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

Ứng dụng Android phải có quyền android.permission.SCENE_UNDERSTANDING_COARSE 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à quyền nguy hiểm.

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

Hỗ trợ thời gian chạy

Nếu thời gian chạy có thể gộp 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 dưới dạng thành phần được hỗ trợ cho chức 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ể đính kèm XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID phải giống hệt với thực thể chứa nó.

Đượ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 định nghĩa như sau:

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

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ 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 .

Cách sử dụng hợp lệ (Ngầm ẩn)

• Tiện ích XR_ANDROID_spatial_component_subsumed_by phải được bật trước khi sử dụng XrSpatialComponentSubsumedByListANDROID
• type phải là XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
• next phải là NULL 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ỏ trỏ đến một mảng gồm subsumedUniqueIdCount giá trị 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 chức 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 bắt nguồn XrSpatialCapabilityConfigurationBaseHeaderEXT của chức năng hỗ trợ thành phần này.

Lọc pháp nhân được bao gồm

Cấu trúc XrSpatialDiscoveryUniqueEntitiesFilterANDROID được định nghĩa như sau:

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

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ 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 ảnh chụp nhanh có các thực thể không được bao gồm trong một thực thể khác.

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

Nếu ứng dụng liên kết XrSpatialDiscoveryUniqueEntitiesFilterANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT nhưng không liệ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 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 .

Cách 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 XrSpatialDiscoveryUniqueEntitiesFilterANDROID
• type phải là XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc

Mã ví dụ

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

Mã ví dụ sau đây minh hoạ cách tạo bối cảnh không gian có chức 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))

Dữ liệu thành phần truy vấ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 ra các thực thể được bao hàm

Mã ví dụ sau đây minh hoạ cách lọc ra 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ã thực thể của các thực thể phụ.

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

• Mở rộng XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentSubsumedByListANDROID

• Mở rộng XrSpatialDiscoverySnapshotCreateInfoEXT :

  • XrSpatialDiscoveryUniqueEntitiesFilterANDROID

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 tháng 11 năm 2025 (Brian Chen)

  • Nội dung mô tả ban đầu về tiện ích.