XR_ANDROID_spatial_component_subsumed_by

Name String

XR_ANDROID_spatial_component_subsumed_by

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

792

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_EXT_spatial_entity
e
XR_EXT_spatial_plane_tracking

Data ultima modifica

2025-08-19

Stato IP

Nessuna rivendicazione di PI 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 XrSpatialEntityIdEXT che include l'entità corrente.

Quando il runtime ha acquisito informazioni sull'ambiente sufficienti 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 le entità che hanno il componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Autorizzazioni

Le app per Android devono disporre dell'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE elencata nel loro 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 includere 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 li include.

Subsumed By Component

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

Filtra le 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 next di XrSpatialDiscoverySnapshotCreateInfoEXT per ottenere uno snapshot con entità non 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 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 rilevamento dei piani

Il seguente codice di esempio mostra come creare un contesto spaziale con 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 codice di esempio 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à incluse

Il seguente codice di esempio 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à di inclusione.

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

    • Descrizione iniziale dell'estensione.