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
Belum 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 kekayaan intelektual 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 guna mengekspos XrSpatialEntityIdEXT yang mencakup entity saat ini.
Saat runtime telah memperoleh informasi lingkungan yang cukup untuk mendeteksi bahwa 2 bidang yang dilacak sebenarnya sama, komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dengan ID salah satu bidang akan dipasang ke bidang lainnya. Sejak saat itu, aplikasi hanya perlu memproses entity yang tidak memiliki komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Ekstensi ini juga memperkenalkan filter baru, yang dapat dihubungkan oleh aplikasi ke XrSpatialDiscoverySnapshotCreateInfoEXT untuk memfilter entity apa pun yang memiliki komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Izin
Aplikasi Android harus memiliki izin android.permission.SCENE_UNDERSTANDING_COARSE yang tercantum 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 mampu menggabungkan satu bidang ke bidang lain, runtime harus menunjukkan hal ini dengan menghitung XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID sebagai komponen yang didukung untuk kemampuan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT di xrEnumerateSpatialCapabilityComponentTypesEXT .
Semua data komponen entity terlampir XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID harus identik dengan entity yang mencakupnya.
Dicakup oleh Komponen
Data komponen
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID menggunakan struktur XrSpatialEntityIdEXT untuk datanya, yang mewakili ID entitas yang mencakup.
Struct daftar komponen untuk mengkueri data
Struktur XrSpatialComponentSubsumedByListANDROID didefinisikan 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 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dari entity 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 berada dalam rantai berikutnya dari XrSpatialComponentDataQueryResultEXT :: 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 -
typeharus berupaXR_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 dihitung dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk kemampuan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, aplikasi dapat mengaktifkannya dengan menyertakan enum dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents dari struktur turunan XrSpatialCapabilityConfigurationBaseHeaderEXT dari kemampuan yang mendukung komponen ini.
Memfilter Entitas yang Tercakup
Struktur XrSpatialDiscoveryUniqueEntitiesFilterANDROID didefinisikan 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 next XrSpatialDiscoverySnapshotCreateInfoEXT untuk mendapatkan snapshot dengan entity yang tidak tercakup oleh entity lain.
Jika aplikasi merantai XrSpatialDiscoveryUniqueEntitiesFilterANDROID ke XrSpatialDiscoverySnapshotCreateInfoEXT sekaligus menyertakan komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .
Jika aplikasi merantai XrSpatialDiscoveryUniqueEntitiesFilterANDROID ke XrSpatialDiscoverySnapshotCreateInfoEXT, tetapi tidak mencantumkan komponen apa pun di XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , runtime harus menyertakan semua entity spasial dalam snapshot yang memiliki kumpulan komponen yang dienumerasi di XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents untuk kemampuan yang dikonfigurasi untuk spatialContext , kecuali entity 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 -
typeharus berupaXR_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 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID .
// 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))
Data Komponen Kueri
Contoh kode berikut menunjukkan cara mengkueri data komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dari konteks yang dikonfigurasi dengan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT .
// 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);
Memfilter Entitas yang Tercakup
Kode contoh berikut menunjukkan cara memfilter entity dengan komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID yang dilampirkan dari snapshot penemuan menggunakan filter, serta mengkueri ID entity dari entity yang mencakupnya.
// 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);
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
Riwayat Versi
Revisi 1, 19-11-2025 (Brian Chen)
- Deskripsi ekstensi awal.