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 をサポートする場合、平面トラッキング機能をサポートし、xrEnumerateSpatialCapabilitiesEXT で XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT を列挙してこれを示す必要があります。
ランタイムが subsumed_by を提供する場合、xrEnumerateSpatialCapabilityComponentTypesEXT で XR_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です。subsumedUniqueIdsはXrSpatialEntityIdEXTの配列です。
アプリケーションは、XrSpatialComponentDataQueryResultEXT の次のチェーンに XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID を追加することで、XrSpatialSnapshotEXT の空間エンティティの subsumed_by コンポーネントをクエリできます。
ランタイムは、XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID が XrSpatialComponentDataQueryResultEXT :: next の次のチェーンにあるが、XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID が XrSpatialComponentDataQueryConditionEXT :: componentTypes に含まれていない場合、xrQuerySpatialComponentDataEXT から XR_ERROR_VALIDATION_FAILURE を返さなければなりません。
subsumedUniqueIdCount が XrSpatialComponentDataQueryResultEXT :: 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は、subsumedUniqueIdCountXrSpatialEntityIdEXT値の配列へのポインタでなければなりません。 -
subsumedUniqueIdCountパラメータは0より大きい値にする必要があります
構成
XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT ケーパビリティの XrSpatialCapabilityComponentTypesEXT :: componentTypes で XR_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 を含めて、別のエンティティに包含されていないエンティティを含むスナップショットを取得できます。
アプリケーションが XrSpatialDiscoveryUniqueEntitiesFilterANDROID を XrSpatialDiscoverySnapshotCreateInfoEXT にチェーンし、XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes に XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID コンポーネントを含める場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。
アプリケーションが XrSpatialDiscoveryUniqueEntitiesFilterANDROID を XrSpatialDiscoverySnapshotCreateInfoEXT にチェーンしているが、XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes にコンポーネントをリストしていない場合、ランタイムは、XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID コンポーネントを持つエンティティを除き、spatialContext に構成されたケーパビリティの XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents に列挙されたコンポーネントのセットを持つスナップショット内のすべての空間エンティティを含めなければなりません。
有効な使用方法(暗黙的)
- XrSpatialDiscoveryUniqueEntitiesFilterANDROID を使用する前に、
XR_ANDROID_spatial_component_subsumed_by拡張機能を有効にする必要があります。 -
typeはXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROIDでなければなりません。 -
nextは、NULLまたは構造体チェーン内の次の構造体への有効なポインタでなければなりません。
サンプルコード
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_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSIONXrSpatialComponentTypeEXT を拡張 :
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
XrStructureType を拡張する :
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
問題
バージョン履歴
リビジョン 1、2025 年 11 月 19 日(Brian Chen)
- 拡張機能の初回説明。