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 クレームはありません。

寄与者

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 の新しいコンポーネントを提供して、現在のエンティティを包含する XrSpatialEntityIdEXT を公開します。

ランタイムが、追跡対象の 2 つの平面が実際には同じであることを検出するのに十分な環境情報を取得すると、平面の 1 つの 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 権限は危険な権限と見なされます。

(保護レベル: 危険)

ランタイム サポート

ランタイムが 1 つの平面を別の平面に包含できる場合は、そのことを示す必要があります 。サポート対象コンポーネントとして XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROIDXR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 機能の xrEnumerateSpatialCapabilityComponentTypesEXT で列挙します。

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

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

ランタイムは、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 拡張機能を有効にする必要があります
  • type である必要があります XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next NULL または構造体チェーン内の次の構造体への有効なポインタ**である必要があります**
  • subsumedUniqueIds subsumedUniqueIdCount XrSpatialEntityIdEXT 値の配列へのポインタ**である必要があります** 。
  • subsumedUniqueIdCount パラメータは である必要があります 0 より大きい値

構成

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROIDXrSpatialCapabilityComponentTypesEXT :: componentTypesXR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT 機能に対して列挙されている場合、アプリケーションは、このコンポーネントをサポートする機能の XrSpatialCapabilityConfigurationBaseHeaderEXT 派生構造体の XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents リストに列挙型を含めることで、このコンポーネントを有効にできます

包含されるエンティティをフィルタする

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

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

メンバーの説明

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

アプリケーションは、XrSpatialDiscoverySnapshotCreateInfoEXTnext チェーンに 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 で列挙されたコンポーネントのセットを持つすべての空間エンティティをスナップショットに含める必要があります

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

コード例

平面追跡機能を構成する

次のサンプルコードは、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);

包含されるエンティティを除外する

次のサンプルコードは、フィルタを使用して、包含されるエンティティのエンティティ ID をクエリするだけでなく、XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID コンポーネントがアタッチされたエンティティを検出スナップショットから除外する方法を示しています。

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

新しい構造体

新しい列挙型定数

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

    • 拡張機能の最初の説明。