XR_ANDROID_spatial_component_subsumed_by
Stringa del nome
XR_ANDROID_spatial_component_subsumed_by
Tipo di estensione
Estensione dell'istanza
Numero di interno registrato
792
Revisione
1
Stato di ratifica
Non ratificato
Dipendenze da estensioni e versioni
XR_EXT_spatial_entity
e
XR_EXT_spatial_plane_tracking
Data ultima modifica
2025-08-19
Stato IP
Nessuna rivendicazione di proprietà intellettuale nota.
Collaboratori
Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google
Panoramica
Questa estensione si basa su XR_EXT_spatial_entity e fornisce un nuovo componente per XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , per esporre la proprietà subsumed_by.
Quando il runtime ha acquisito informazioni sull'ambiente sufficienti per rilevare che due piani tracciati sono in realtà lo stesso, il componente subsumed_by con l'ID di uno dei piani verrà allegato all'altro.
Questa estensione introduce anche un nuovo filtro, che l'applicazione può concatenare a XrSpatialDiscoverySnapshotCreateInfoEXT per filtrare le entità a cui è associato il componente subsumed_by.
Autorizzazioni
Le applicazioni Android devono disporre dell'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE elencata nel loro manifest, in quanto questa estensione rileva i piani nell'ambiente. L'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE è considerata pericolosa.
(livello di protezione: pericoloso)
Supporto di runtime
Se il runtime supporta subumed_by, deve supportare la funzionalità di monitoraggio del piano e indicarlo enumerando XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT in xrEnumerateSpatialCapabilitiesEXT .
Se il runtime fornisce subsumed_by, deve indicarlo enumerando XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID come componente supportato per la funzionalità XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT in xrEnumerateSpatialCapabilityComponentTypesEXT .
Tutti i dati dei componenti dell'XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROIDentità allegatadevono essere identici all'entità che la include.
Incluso nel componente
Dati dei componenti
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID utilizza la struttura XrSpatialEntityIdEXT per i suoi dati, che rappresenta l'ID dell'entità di inclusione.
Struttura dell'elenco dei componenti per eseguire query sui dati
La struttura XrSpatialComponentSubsumedByListANDROID è definita come:
typedef struct XrSpatialComponentSubsumedByListANDROID {
XrStructureType type;
void* next;
uint32_t subsumedUniqueIdCount;
XrSpatialEntityIdEXT* subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture.subsumedUniqueIdCountè unuint32_tche descrive il conteggio degli elementi nell'arraysubsumedUniqueIds.subsumedUniqueIdsè un array diXrSpatialEntityIdEXT.
L'applicazione può eseguire query sul componente subsumed_by delle entità spaziali in un XrSpatialSnapshotEXT aggiungendo XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID alla catena successiva di XrSpatialComponentDataQueryResultEXT .
Il runtime deve restituire XR_ERROR_VALIDATION_FAILURE da xrQuerySpatialComponentDataEXT se XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID si trova nella catena successiva di XrSpatialComponentDataQueryResultEXT :: next, ma XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID non è incluso in XrSpatialComponentDataQueryConditionEXT :: componentTypes .
Il runtime deve restituire XR_ERROR_SIZE_INSUFFICIENT da xrQuerySpatialComponentDataEXT se subsumedUniqueIdCount è inferiore a XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_spatial_component_subsumed_bydeve essere attivata prima di utilizzare XrSpatialComponentSubsumedByListANDROID -
typedeve essereXR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture -
subsumedUniqueIdsdeve essere un puntatore a un array di valorisubsumedUniqueIdCountXrSpatialEntityIdEXT - Il parametro
subsumedUniqueIdCountdeve essere maggiore di0
Configurazione
Se XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID è enumerato in XrSpatialCapabilityComponentTypesEXT :: componentTypes per la funzionalità XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, l'applicazione può abilitarla includendo l'enumerazione nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents della struttura derivata XrSpatialCapabilityConfigurationBaseHeaderEXT della funzionalità che supporta questo componente.
Filtra entità incluse
La struttura XrSpatialDiscoveryUniqueEntitiesFilterANDROID è definita come:
typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
XrStructureType type;
const void* next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;
Descrizioni dei membri
typeè l'XrStructureType di questa struttura.nextèNULLo un puntatore alla struttura successiva in una catena di strutture.
L'applicazione può includere XrSpatialDiscoveryUniqueEntitiesFilterANDROID nella catena successiva di XrSpatialDiscoverySnapshotCreateInfoEXT per ottenere uno snapshot con entità che non sono incluse in un'altra entità.
Se le applicazioni concatenano XrSpatialDiscoveryUniqueEntitiesFilterANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT includendo il componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .
Se le catene di applicazioni XrSpatialDiscoveryUniqueEntitiesFilterANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT, ma non elencano alcun componente in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, il runtime deve includere tutte le entità spaziali nello snapshot che hanno il set di componenti enumerati in XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents per le funzionalità configurate per spatialContext, ad eccezione delle entità che hanno il componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.
Utilizzo valido (implicito)
- L'estensione
XR_ANDROID_spatial_component_subsumed_bydeve essere attivata prima di utilizzare XrSpatialDiscoveryUniqueEntitiesFilterANDROID -
typedeve essereXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID -
nextdeve essereNULLo un puntatore valido alla struttura successiva in una catena di strutture
Esempio di codice
Configura la funzionalità di monitoraggio degli aerei
Il seguente codice di esempio mostra come creare un contesto spaziale con la funzionalità XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT che supporta 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))
Eseguire query sui dati dei componenti
Il seguente codice di esempio mostra come eseguire query sui dati dei componenti subsumed_by dal contesto configurato con 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);
Filtra le entità incluse
Il seguente codice di esempio mostra come filtrare le entità con il componente subsumed_by allegato dallo snapshot di rilevamento utilizzando il filtro, nonché come eseguire query sull'ID entità delle entità di sussunzione.
// 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);
Nuove strutture
Estensione di XrSpatialComponentDataQueryResultEXT :
Estensione di XrSpatialDiscoverySnapshotCreateInfoEXT :
Nuove costanti enum
XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAMEXR_ANDROID_spatial_component_subsumed_by_SPEC_VERSIONEstensione di XrSpatialComponentTypeEXT :
XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
Estensione di XrStructureType :
XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROIDXR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID
Problemi
Cronologia delle versioni
Revisione 1, 19/11/2025 (Brian Chen)
- Descrizione iniziale dell'estensione.