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 guna mengekspos XrSpatialEntityIdEXT yang mencakup entitas 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 dilampirkan ke bidang lainnya. Mulai saat itu, aplikasi hanya perlu memproses entitas yang tidak memiliki komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Ekstensi ini juga memperkenalkan filter baru, yang dapat dirangkai aplikasi ke XrSpatialDiscoverySnapshotCreateInfoEXT untuk memfilter semua entity yang memiliki komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
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 dapat menyertakan satu bidang ke bidang lain, 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_ANDROIDentitas 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 entity 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 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 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 berada 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 -
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 tercantum 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 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 next dari XrSpatialDiscoverySnapshotCreateInfoEXT untuk mendapatkan snapshot dengan entity yang tidak termasuk dalam entity 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 -
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))
Membuat Kueri Data Komponen
Contoh kode berikut menunjukkan cara membuat kueri 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
Contoh kode berikut menunjukkan cara memfilter entity dengan komponen XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID yang terlampir 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: 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.