XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

拡張機能のタイプ

インスタンス拡張機能

Registered Extension Number

792

リビジョン

1

Ratification Status(批准ステータス)

未批准

拡張機能とバージョンの依存関係

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 の新しいコンポーネントを提供して、subsumed_by プロパティを公開します。

ランタイムが、追跡対象の 2 つの飛行機が実際には同じであることを検出するのに十分な環境情報を取得すると、飛行機の 1 つの ID を持つ subsumed_by コンポーネントがもう一方にアタッチされます。

この拡張機能では、新しいフィルタも導入されています。このフィルタを XrSpatialDiscoverySnapshotCreateInfoEXT にチェーンして、subsumed_by コンポーネントがアタッチされているエンティティをフィルタリングできます。

権限

この拡張機能は環境内の平面を追跡するため、Android アプリはマニフェストに android.permission.SCENE_UNDERSTANDING_COARSE 権限を記載しなければなりません。android.permission.SCENE_UNDERSTANDING_COARSE 権限は危険な権限と見なされます。

(保護レベル: 危険)

ランタイム サポート

ランタイムが subumed_by をサポートする場合、平面トラッキング機能をサポートし、xrEnumerateSpatialCapabilitiesEXTXR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT を列挙してこれを示す必要があります

ランタイムが subsumed_by を提供する場合、xrEnumerateSpatialCapabilityComponentTypesEXTXR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 機能のサポート対象コンポーネントとして XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID を列挙することで、これを示す必要があります。

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID に関連付けられたエンティティのすべてのコンポーネント データは、それを包含するエンティティと同一である必要があります

Subsumed By Component

コンポーネント データ

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 です。
  • subsumedUniqueIdsXrSpatialEntityIdEXT の配列です。

アプリケーションは、XrSpatialComponentDataQueryResultEXT の次のチェーンに XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID を追加することで、XrSpatialSnapshotEXT の空間エンティティの subsumed_by コンポーネントをクエリできます。

ランタイムは、XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXrSpatialComponentDataQueryResultEXT :: next の次のチェーンにあるが、XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROIDXrSpatialComponentDataQueryConditionEXT :: componentTypes に含まれていない場合、xrQuerySpatialComponentDataEXT から XR_ERROR_VALIDATION_FAILURE を返さなければなりません

subsumedUniqueIdCountXrSpatialComponentDataQueryResultEXT :: entityIdCountOutput より小さい場合、ランタイムは xrQuerySpatialComponentDataEXT から XR_ERROR_SIZE_INSUFFICIENT を返さなければなりません。

有効な使用方法(暗黙的)

  • XrSpatialComponentSubsumedByListANDROID を使用する前に、XR_ANDROID_spatial_component_subsumed_by 拡張機能を有効にする必要があります
  • typeXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID でなければなりません。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • subsumedUniqueIds は、subsumedUniqueIdCount XrSpatialEntityIdEXT 値の配列へのポインタでなければなりません。
  • subsumedUniqueIdCount パラメータは 0 より大きい値にする必要があります

構成

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT ケーパビリティの XrSpatialCapabilityComponentTypesEXT :: componentTypesXR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID が列挙されている場合、アプリは、このコンポーネントをサポートするケーパビリティの XrSpatialCapabilityConfigurationBaseHeaderEXT 派生構造の XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents リストに列挙型を含めることで、このコンポーネントを有効にできます

統合されたエンティティをフィルタする

XrSpatialDiscoveryUniqueEntitiesFilterANDROID 構造体は次のように定義されます。

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

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。

アプリは、XrSpatialDiscoverySnapshotCreateInfoEXT の次のチェーンに XrSpatialDiscoveryUniqueEntitiesFilterANDROID を含めて、別のエンティティに包含されていないエンティティを含むスナップショットを取得できます。

アプリケーションが XrSpatialDiscoveryUniqueEntitiesFilterANDROIDXrSpatialDiscoverySnapshotCreateInfoEXT にチェーンし、XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypesXR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID コンポーネントを含める場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

アプリケーションが XrSpatialDiscoveryUniqueEntitiesFilterANDROIDXrSpatialDiscoverySnapshotCreateInfoEXT にチェーンしているが、XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes にコンポーネントをリストしていない場合、ランタイムは、XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID コンポーネントを持つエンティティを除き、spatialContext に構成されたケーパビリティの XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents に列挙されたコンポーネントのセットを持つスナップショット内のすべての空間エンティティを含めなければなりません。

有効な使用方法(暗黙的)

サンプルコード

Plane Tracking Capability を構成する

次のサンプルコードは、subsumed_by をサポートする XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 機能を使用して空間コンテキストを作成する方法を示しています。

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

クエリ コンポーネント データ

次のコード例は、XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT で構成されたコンテキストから subsumed_by コンポーネント データをクエリする方法を示しています。

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

サブサームされたエンティティを除外する

次のコード例は、フィルタを使用して、サブサンプションされたコンポーネントがアタッチされたエンティティをディスカバリ スナップショットから除外する方法と、サブサンプションされたエンティティのエンティティ ID をクエリする方法を示しています。

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

新しい構造体

新しい列挙型定数

  • 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 日(Brian Chen)

    • 拡張機能の初回説明。