XR_ANDROID_spatial_component_subsumed_by

Stringa del nome

XR_ANDROID_spatial_component_subsumed_by

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

792

Revisione

1

Stato di ratifica

Non ratificato

Dipendenze di estensione e versione

XR_EXT_spatial_entity
e
XR_EXT_spatial_plane_tracking

Data ultima modifica

2025-08-19

Stato IP

Nessuna rivendicazione IP 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 l'elemento XrSpatialEntityIdEXT che sussume l'entità corrente.

Quando il runtime ha acquisito informazioni sufficienti sull'ambiente per rilevare che due piani monitorati sono in realtà lo stesso, il componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID con l'ID di uno dei piani viene collegato all'altro. Da quel momento in poi, l'applicazione deve elaborare solo l'entità che non ha il componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Questa estensione introduce anche un nuovo filtro, che l'applicazione può concatenare a XrSpatialDiscoverySnapshotCreateInfoEXT per filtrare tutte le entità che hanno il componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Autorizzazioni

Le applicazioni Android devono avere l'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE elencata nel file manifest, in quanto questa estensione monitora i piani nell'ambiente. L'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE è considerata pericolosa.

(livello di protezione: pericoloso)

Supporto di runtime

Se il runtime è in grado di sussumere un piano in un altro, 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'entità collegata XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID devono essere identici all'entità che la sussume.

Componente sussunto da

Dati dei componenti

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID utilizza la struttura XrSpatialEntityIdEXT per i suoi dati, che rappresenta l'ID dell'entità sussunta.

Struttura dell'elenco dei componenti per eseguire query sui dati

La struttura XrSpatialComponentSubsumedByListANDROID è definita come segue:

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 XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID 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 abilitata 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ò abilitarlo includendo l'enum nell'elenco XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents della struttura derivata XrSpatialCapabilityConfigurationBaseHeaderEXT della funzionalità che supporta questo componente.

Filtra le entità sussunte

La struttura XrSpatialDiscoveryUniqueEntitiesFilterANDROID è definita come segue:

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 next di XrSpatialDiscoverySnapshotCreateInfoEXT per ottenere uno snapshot con entità non sussunte da 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 l'applicazione concatena XrSpatialDiscoveryUniqueEntitiesFilterANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT ma non elenca alcun componente in XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , il runtime deve includere nello snapshot tutte le entità spaziali che hanno l'insieme 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 dei piani

Il seguente esempio di codice mostra come creare un contesto spaziale con la funzionalità XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT che supporta 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))

Esegui query sui dati dei componenti

Il seguente esempio di codice mostra come eseguire query sui dati dei componenti XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID dal contesto configurato con 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);

Filtra le entità sussunte

Il seguente esempio di codice mostra come filtrare le entità con il componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID collegato dallo snapshot di rilevamento utilizzando il filtro, nonché come eseguire query sull'ID entità delle entità sussunte.

// 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);

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, 2025-11-19 (Brian Chen)

    • Descrizione iniziale dell'estensione.