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 è NULL o un puntatore alla struttura successiva in una catena di strutture.
  • subsumedUniqueIdCount è un uint32_t che descrive il conteggio degli elementi nell'array subsumedUniqueIds.
  • subsumedUniqueIds è un array di XrSpatialEntityIdEXT .

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_by deve essere attivata prima di utilizzare XrSpatialComponentSubsumedByListANDROID
  • type deve essere XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
  • subsumedUniqueIds deve essere un puntatore a un array di valori subsumedUniqueIdCount XrSpatialEntityIdEXT
  • Il parametro subsumedUniqueIdCount deve essere maggiore di 0

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 è NULL o 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)

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

Nuove costanti enum

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION
  • Estensione di XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID
  • Estensione di XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Problemi

Cronologia delle versioni

  • Revisione 1, 19/11/2025 (Brian Chen)

    • Descrizione iniziale dell'estensione.