XR_ANDROID_spatial_component_subsumed_by

Chuỗi tên

XR_ANDROID_spatial_component_subsumed_by

Loại tiện ích

Tiện ích thực thể

Số tiện ích đã đăng ký

792

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa phê chuẩn

Tiện ích và các phần phụ thuộc vào phiên bản

XR_EXT_spatial_entity

XR_EXT_spatial_plane_tracking

Ngày sửa đổi gần 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 IP nào được biết.

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ị thuộc tính subsumed_by.

Khi thời gian chạy thu thập đủ thông tin về môi trường để phát hiện 2 mặt phẳng được theo dõi thực sự là giống nhau, thì thành phần subsumed_by 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.

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 mọi thực thể có thành phần subsumed_by được đính kèm.

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 của chúng 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 hỗ trợ subumed_by, thì thời gian chạy phải hỗ trợ khả năng theo dõi mặt phẳng và cho biết điều này bằng cách liệt kê XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT trong xrEnumerateSpatialCapabilitiesEXT .

Nếu thời gian chạy cung cấp subsumed_by, 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 một 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ể được đính kèm XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID phải giống với thực thể bao trùm thực thể đó.

Thành phần được bao trùm

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, cấu trúc này đại diện cho mã nhận dạng của thực thể bao trù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;

Mô tả thành phần

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc một 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 subsumed_by 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 đưa vào 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ụ ý)

  • Tiện ích XR_ANDROID_spatial_component_subsumed_by phải được bật 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ệ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc
  • subsumedUniqueIds phải là một con trỏ 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 tính năng này bằng cách đưa enum vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents của cấu trúc XrSpatialCapabilityConfigurationBaseHeaderEXT dẫn xuất của khả năng hỗ trợ thành phần này.

Lọc các thực thể được bao trùm

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

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

Mô tả thành phần

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

Ứng dụng có thể đưa XrSpatialDiscoveryUniqueEntitiesFilterANDROID vào chuỗi tiếp theo của XrSpatialDiscoverySnapshotCreateInfoEXT để lấy ảnh chụp nhanh với các thực thể không được một thực thể khác bao trùm.

Nếu các ứng dụng liên kết XrSpatialDiscoveryUniqueEntitiesFilterANDROID với XrSpatialDiscoverySnapshotCreateInfoEXT trong khi đưa 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 các ứng dụng liên kết XrSpatialDiscoveryUniqueEntitiesFilterANDROID với 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 đưa tất cả các thực thể không gian vào ả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 khả 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ã ví dụ

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

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ợ subsumed_by.

// Check runtime supported capabilities
uint32_t capabilityCount;
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;
}

std::vector<XrSpatialComponentTypeEXT> planeTrackingComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
  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

Mã ví dụ sau đây minh hoạ cách truy vấn dữ liệu thành phần subsumed_by từ ngữ cảnh được định cấu hình bằng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .

// Create Discovery Snapshot
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
};

CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT (
spatialContext, &discoverySnapshotCreateInfo, &future));

// Poll the state till snapshot it's ready.
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 {
  XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
           spatialContext, &createSnapshotCompletionInfo,
           &completion));

if(completion.futureResult != XR_SUCCESS) return;

// 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(
           completion.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(
           completion.snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityEXT> subsumedEntities;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    // access planes[i] for merged plane id
    XrSpatialEntityIdEXT entityId = queryResult.entityIds[i];
    XrSpatialEntityIdEXT subsumedUniqueId = subsumedUniqueIds[i];

    // create handle via entityId
  XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
    .type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
    .entityId = entityId,
  };

  XrSpatialEntityEXT entity = XR_NULL_HANDLE;
  xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);

  subsumedEntities.push_back(entity);
}

// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);

Lọc các thực thể được bao trùm

Mã ví dụ sau đây minh hoạ cách lọc các thực thể có thành phần subsumed_by đượ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 trùm.

// Init filter
XrSpatialDiscoveryUniqueEntitiesFilterANDROID filter {
  .type = XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID,
};

// Chain filter to the snapshot create info
// WARNING: Chain 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
};

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 {
  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
// Bounded2D to render subsuming planes
std::vector<XrSpatialComponentTypeEXT> queryComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
};

XrSpatialComponentDataQueryConditionEXT queryCond {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
  .componentTypeCount = 1,
  .componentTypes     = queryComponents.data(),
};

XrSpatialComponentDataQueryResultEXT queryResult {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};

CHK_XR(xrQuerySpatialComponentDataEXT(
           completion.snapshot, &queryCond, &queryResult));

// Chain Bounded2D list
std::vector<XrSpatialBounded2DDataEXT> bounded2dData;
bounded2dData.resize(queryResult.entityIdCountOutput);

XrSpatialComponentBounded2DListEXT bounded2dList {
  .type = XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT,
  .boundCount = static_cast<uint32_t>(bounded2dData.size()),
  .bounds = bounded2dData.data(),
};

// Query again
queryResult.next = &bounded2dList;
CHK_XR(xrQuerySpatialComponentDataEXT(
           completion.snapshot, &queryCond, &queryResult));

std::vector<XrSpatialEntityEXT> subsumingPlanes;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // access planes[i] for merged plane id
  XrSpatialEntityIdEXT entityId = queryResult.entityIds[i];

  // create handle via entityId.
  XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
    .type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
    .entityId = entityId,
  };

  XrSpatialEntityEXT entity = XR_NULL_HANDLE;
  xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);

  subsumingPlanes.push_back(entity);
}

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

Nhật ký phiên bản

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

    • Mô tả tiện ích ban đầu.