XR_ANDROID_spatial_component_subsumed_by
String Nama
XR_ANDROID_spatial_component_subsumed_by
Jenis Ekstensi
Ekstensi instance
Nomor Ekstensi Terdaftar
792
Revisi
1
Status Ratifikasi
Tidak diratifikasi
Dependensi Ekstensi dan Versi
XR_EXT_spatial_entity
dan
XR_EXT_spatial_plane_tracking
Tanggal Terakhir Diubah
2025-08-19
Status IP
Tidak ada klaim IP yang diketahui.
Kontributor
Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Ringkasan
Ekstensi ini dibuat berdasarkan XR_EXT_spatial_entity dan menyediakan komponen baru untuk XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , untuk mengekspos properti subsumed_by.
Saat runtime telah memperoleh informasi lingkungan yang cukup untuk mendeteksi bahwa 2 bidang yang dilacak sebenarnya sama, komponen subsumed_by dengan ID salah satu bidang akan dilampirkan ke bidang lainnya.
Ekstensi ini juga memperkenalkan filter baru, yang dapat dirangkai aplikasi ke XrSpatialDiscoverySnapshotCreateInfoEXT untuk memfilter semua entity yang memiliki komponen subsumed_by yang terpasang padanya.
Izin
Aplikasi Android harus mencantumkan izin android.permission.SCENE_UNDERSTANDING_COARSE dalam manifesnya karena ekstensi ini melacak bidang di lingkungan. Izin android.permission.SCENE_UNDERSTANDING_COARSE dianggap sebagai izin berbahaya.
(tingkat perlindungan: berbahaya)
Dukungan Runtime
Jika runtime mendukung subumed_by, runtime harus mendukung kemampuan pelacakan bidang dan menunjukkannya dengan mencantumkan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT di xrEnumerateSpatialCapabilitiesEXT .
Jika runtime menyediakan subsumed_by, runtime harus menunjukkannya dengan mencantumkan XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID sebagai komponen yang didukung untuk kemampuan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT di xrEnumerateSpatialCapabilityComponentTypesEXT .
Semua data komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID entitas terlampir harus identik dengan entitas yang mencakupnya.
Dicakup Oleh Komponen
Data komponen
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID menggunakan struktur XrSpatialEntityIdEXT untuk datanya, yang merepresentasikan ID entitas yang mencakup.
Struktur daftar komponen untuk mengkueri data
Struktur XrSpatialComponentSubsumedByListANDROID ditentukan sebagai:
typedef struct XrSpatialComponentSubsumedByListANDROID {
XrStructureType type;
void* next;
uint32_t subsumedUniqueIdCount;
XrSpatialEntityIdEXT* subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur.subsumedUniqueIdCountadalahuint32_tyang menjelaskan jumlah elemen dalam arraysubsumedUniqueIds.subsumedUniqueIdsadalah arrayXrSpatialEntityIdEXT.
Aplikasi dapat mengkueri komponen subsumed_by entitas spasial dalam XrSpatialSnapshotEXT dengan menambahkan XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID ke rantai berikutnya dari XrSpatialComponentDataQueryResultEXT .
Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID ada di rantai XrSpatialComponentDataQueryResultEXT berikutnya :: next, tetapi XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .
Runtime harus menampilkan XR_ERROR_SIZE_INSUFFICIENT dari xrQuerySpatialComponentDataEXT jika subsumedUniqueIdCount kurang dari XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_spatial_component_subsumed_byharus diaktifkan sebelum menggunakan XrSpatialComponentSubsumedByListANDROID -
typeharusXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur -
subsumedUniqueIdsharus berupa pointer ke array nilaisubsumedUniqueIdCountXrSpatialEntityIdEXT - Parameter
subsumedUniqueIdCountharus lebih besar dari0
Konfigurasi
Jika XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID tercantum dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk kemampuan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, aplikasi dapat mengaktifkannya dengan menyertakan enum dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dari kemampuan struktur turunan XrSpatialCapabilityConfigurationBaseHeaderEXT yang mendukung komponen ini.
Memfilter Entitas yang Tercakup
Struktur XrSpatialDiscoveryUniqueEntitiesFilterANDROID ditentukan sebagai:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
Deskripsi Anggota
typeadalah XrStructureType dari struktur ini.nextadalahNULLatau pointer ke struktur berikutnya dalam rantai struktur.
Aplikasi dapat menyertakan XrSpatialDiscoveryUniqueEntitiesFilterANDROID dalam rantai XrSpatialDiscoverySnapshotCreateInfoEXT berikutnya untuk mendapatkan snapshot dengan entitas yang tidak termasuk dalam entitas lain.
Jika aplikasi merangkai XrSpatialDiscoveryUniqueEntitiesFilterANDROID ke XrSpatialDiscoverySnapshotCreateInfoEXT sambil menyertakan komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .
Jika rantai aplikasi XrSpatialDiscoveryUniqueEntitiesFilterANDROID ke XrSpatialDiscoverySnapshotCreateInfoEXT, tetapi tidak mencantumkan komponen apa pun di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, runtime harus menyertakan semua entitas spasial dalam snapshot yang memiliki kumpulan komponen yang tercantum di XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents untuk kemampuan yang dikonfigurasi untuk spatialContext, kecuali entitas yang memiliki komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Penggunaan yang Valid (Implisit)
- Ekstensi
XR_ANDROID_spatial_component_subsumed_byharus diaktifkan sebelum menggunakan XrSpatialDiscoveryUniqueEntitiesFilterANDROID -
typeharusXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID -
nextharus berupaNULLatau pointer yang valid ke struktur berikutnya dalam rantai struktur
Kode contoh
Mengonfigurasi Kemampuan Pelacakan Bidang
Contoh kode berikut menunjukkan cara membuat konteks spasial dengan kemampuan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT yang mendukung 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))
Membuat Kueri Data Komponen
Contoh kode berikut menunjukkan cara mengkueri data komponen subsumed_by dari konteks yang dikonfigurasi dengan 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);
Memfilter Entitas yang Tercakup
Contoh kode berikut menunjukkan cara memfilter entity dengan komponen subsumed_by yang dilampirkan dari snapshot penemuan menggunakan filter, serta mengkueri ID entity dari entity yang mencakup.
// 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);
Struktur Baru
Memperluas XrSpatialComponentDataQueryResultEXT :
Memperluas XrSpatialDiscoverySnapshotCreateInfoEXT :
Konstanta Enum Baru
XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSIONMemperluas XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
Memperluas XrStructureType :
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
Masalah
Histori Versi
Revisi 1, 19-11-2025 (Brian Chen)
- Deskripsi ekstensi awal.