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 소유권 주장이 없습니다.

도움을 주신 분들

브라이언 첸, Google
카일 첸, Google
레바나 첸, Google
니하브 자인, Google
스펜서 퀸, Google

개요

이 확장 프로그램은 XR_EXT_spatial_entity를 기반으로 하며 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT가 현재 항목을 포함하는 XrSpatialEntityIdEXT를 노출할 수 있는 새로운 구성요소를 제공합니다.

런타임에서 추적된 평면 2개가 실제로 동일하다는 것을 감지하기에 충분한 환경 정보를 획득하면 평면 중 하나의 ID가 있는 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 권한은 위험한 권한으로 간주됩니다.

(보호 수준: 위험)

런타임 지원

런타임이 한 평면을 다른 평면에 포함할 수 있는 경우 xrEnumerateSpatialCapabilityComponentTypesEXT에서 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 기능의 지원되는 구성요소로 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID를 열거하여 이를 표시해야 합니다(must).

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 연결된 항목의 모든 구성요소 데이터는 이를 포함하는 항목과 동일해야 합니다.

구성요소에 포함됨

구성요소 데이터

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID는 데이터에 XrSpatialEntityIdEXT 구조를 사용하며, 이는 포함하는 항목의 ID를 나타냅니다.

데이터를 쿼리하는 구성요소 목록 구조체

XrSpatialComponentSubsumedByListANDROID 구조는 다음과 같이 정의됩니다.

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

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.
  • subsumedUniqueIdCount은 subsumedUniqueIds 배열의 요소 수를 설명하는 uint32_t입니다.
  • subsumedUniqueIds는 XrSpatialEntityIdEXT의 배열입니다.

애플리케이션은 XrSpatialComponentDataQueryResultEXT의 다음 체인에 XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID를 추가하여 XrSpatialSnapshotEXT에서 공간 항목의 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 구성요소를 쿼리할 수 있습니다.

XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID가 XrSpatialComponentDataQueryResultEXT :: next의 다음 체인에 있지만 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID가 XrSpatialComponentDataQueryConditionEXT :: componentTypes에 포함되지 않은 경우 런타임은 xrQuerySpatialComponentDataEXT에서 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(must).

subsumedUniqueIdCount가 XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput보다 작은 경우 런타임은 xrQuerySpatialComponentDataEXT에서 XR_ERROR_SIZE_INSUFFICIENT를 반환해야 합니다(must).

올바른 사용 (암시적)

  • XrSpatialComponentSubsumedByListANDROID를 사용하기 전에 XR_ANDROID_spatial_component_subsumed_by 확장 프로그램을 사용 설정해야 합니다.
  • type은(는) XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID여야 합니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 유효한 포인터여야 합니다.
  • subsumedUniqueIds는 subsumedUniqueIdCount XrSpatialEntityIdEXT 값 배열에 대한 포인터여야 합니다.
  • subsumedUniqueIdCount 매개변수는 0보다 커야 합니다.

구성

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID가 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 기능의 XrSpatialCapabilityComponentTypesEXT :: componentTypes에 열거된 경우 애플리케이션은 이 구성요소를 지원하는 기능의 XrSpatialCapabilityConfigurationBaseHeaderEXT 파생 구조의 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents 목록에 enum을 포함하여 이를 사용 설정할 수 있습니다.

포함된 항목 필터링

XrSpatialDiscoveryUniqueEntitiesFilterANDROID 구조는 다음과 같이 정의됩니다.

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

회원 설명

  • type는 이 구조의 XrStructureType입니다.
  • next는 NULL 또는 구조 체인의 다음 구조에 대한 포인터입니다.

애플리케이션은 XrSpatialDiscoverySnapshotCreateInfoEXT의 next 체인에 XrSpatialDiscoveryUniqueEntitiesFilterANDROID를 포함하여 다른 항목에 포함되지 않은 항목이 있는 스냅샷을 가져올 수 있습니다.

애플리케이션이 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes에 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 구성요소를 포함하면서 XrSpatialDiscoveryUniqueEntitiesFilterANDROID를 XrSpatialDiscoverySnapshotCreateInfoEXT에 연결하는 경우 런타임은 XR_ERROR_VALIDATION_FAILURE를 반환해야 합니다(must).

애플리케이션이 XrSpatialDiscoveryUniqueEntitiesFilterANDROID를 XrSpatialDiscoverySnapshotCreateInfoEXT에 연결하지만 XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes에 구성요소를 나열하지 않는 경우 런타임은 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 구성요소가 있는 항목을 제외하고 spatialContext에 구성된 기능의 XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents에 열거된 구성요소 집합이 있는 스냅샷의 모든 공간 항목을 포함해야 합니다(must).

올바른 사용 (암시적)

예시 코드

평면 추적 기능 구성

다음 예시 코드는 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID를 지원하는 XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 기능으로 공간 컨텍스트를 만드는 방법을 보여줍니다.

// 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_CAPABILITY_PLANE_TRACKING_EXT로 구성된 컨텍스트에서 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 구성요소 데이터를 쿼리하는 방법을 보여줍니다.

// 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 구성요소가 연결된 항목을 필터링하는 방법과 포함하는 항목의 항목 ID를 쿼리하는 방법을 보여줍니다.

// 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, 2025-11-19 (브라이언 첸)

    • 초기 확장 프로그램 설명입니다.