XR_ANDROID_spatial_component_subsumed_by

String do nome

XR_ANDROID_spatial_component_subsumed_by

Tipo de extensão

Extensão de instância

Número de extensão registrada

792

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_spatial_entity
e
XR_EXT_spatial_plane_tracking

Data da última modificação

2025-08-19

Status de IP

Nenhuma reivindicação de IP conhecida.

Colaboradores

Brian Chen, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Visão geral

Essa extensão se baseia em XR_EXT_spatial_entity e oferece um novo componente para XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT para expor o XrSpatialEntityIdEXT que engloba a entidade atual.

Quando o ambiente de execução adquire informações suficientes sobre o ambiente para detectar que dois planos rastreados são iguais, o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID com o ID de um dos planos é anexado ao outro. A partir desse momento, o aplicativo só precisa processar a entidade que não tem o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Essa extensão também apresenta um novo filtro, que o aplicativo pode encadear ao XrSpatialDiscoverySnapshotCreateInfoEXT para filtrar todas as entidades que têm o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Permissões

Os aplicativos Android precisam ter a permissão android.permission.SCENE_UNDERSTANDING_COARSE listada no manifesto, já que essa extensão rastreia planos no ambiente. A permissão android.permission.SCENE_UNDERSTANDING_COARSE é considerada perigosa.

(nível de proteção: perigoso)

Suporte ao ambiente de execução

Se o ambiente de execução puder englobar um plano em outro, ele precisará indicar isso enumerando XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID como um componente compatível para a capacidade XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT em xrEnumerateSpatialCapabilityComponentTypesEXT .

Todos os dados de componentes da entidade anexada XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID precisam ser idênticos à entidade que a engloba.

Componente englobado por

Dados do componente

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID usa a estrutura XrSpatialEntityIdEXT para os dados, que representa o ID da entidade englobadora.

Estrutura da lista de componentes para consultar dados

A estrutura XrSpatialComponentSubsumedByListANDROID é definida como:

typedef struct XrSpatialComponentSubsumedByListANDROID {
    XrStructureType          type;
    void*                    next;
    uint32_t                 subsumedUniqueIdCount;
    XrSpatialEntityIdEXT*    subsumedUniqueIds;
} XrSpatialComponentSubsumedByListANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • subsumedUniqueIdCount é um uint32_t que descreve a contagem de elementos na matriz subsumedUniqueIds.
  • subsumedUniqueIds é uma matriz de XrSpatialEntityIdEXT .

O aplicativo pode consultar o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID das entidades espaciais em um XrSpatialSnapshotEXT adicionando XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID à próxima cadeia do XrSpatialComponentDataQueryResultEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID estiver na próxima cadeia de XrSpatialComponentDataQueryResultEXT :: next mas XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

O ambiente de execução precisa retornar XR_ERROR_SIZE_INSUFFICIENT de xrQuerySpatialComponentDataEXT se subsumedUniqueIdCount for menor que XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

Uso válido (implícito)

  • A extensão XR_ANDROID_spatial_component_subsumed_by precisa ser ativada antes de usar XrSpatialComponentSubsumedByListANDROID.
  • type precisa ser XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
  • next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
  • subsumedUniqueIds precisa ser um ponteiro para uma matriz de subsumedUniqueIdCount XrSpatialEntityIdEXT valores
  • O parâmetro subsumedUniqueIdCount precisa ser maior que 0

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para a capacidade XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, o aplicativo poderá ativá-lo incluindo a enumeração na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada XrSpatialCapabilityConfigurationBaseHeaderEXT da capacidade que oferece suporte a esse componente.

Filtrar entidades englobadas

A estrutura XrSpatialDiscoveryUniqueEntitiesFilterANDROID é definida como:

typedef struct XrSpatialDiscoveryUniqueEntitiesFilterANDROID {
    XrStructureType    type;
    const void*        next;
} XrSpatialDiscoveryUniqueEntitiesFilterANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.

O aplicativo pode incluir XrSpatialDiscoveryUniqueEntitiesFilterANDROID na cadeia next de XrSpatialDiscoverySnapshotCreateInfoEXT para receber um snapshot com entidades que não são englobadas por outra entidade.

Se os aplicativos encadearem XrSpatialDiscoveryUniqueEntitiesFilterANDROID ao XrSpatialDiscoverySnapshotCreateInfoEXT ao incluir o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID no XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , o ambiente de execução precisará retornar XR_ERROR_VALIDATION_FAILURE .

Se o aplicativo encadear XrSpatialDiscoveryUniqueEntitiesFilterANDROID ao XrSpatialDiscoverySnapshotCreateInfoEXT, mas não listar nenhum componente em XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, o ambiente de execução precisará incluir todas as entidades espaciais no snapshot que têm o conjunto de componentes enumerados em XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents para as capacidades configuradas para spatialContext, exceto entidades que têm o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Uso válido (implícito)

Exemplo de código

Configurar a capacidade de rastreamento de planos

O exemplo de código a seguir demonstra como criar um contexto espacial com a capacidade XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT que oferece suporte a 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))

Consultar dados de componentes

O exemplo de código a seguir demonstra como consultar dados de componentes XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID do contexto configurado com 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);

Filtrar entidades englobadas

O exemplo de código a seguir demonstra como filtrar entidades com o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID anexado do snapshot de descoberta usando o filtro, bem como consultar o ID da entidade das entidades englobadoras.

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

Novas estruturas

Novas constantes de enumeração

  • XR_ANDROID_SPATIAL_COMPONENT_SUBSUMED_BY_EXTENSION_NAME
  • XR_ANDROID_spatial_component_subsumed_by_SPEC_VERSION

  • Estendendo XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

  • Estendendo XrStructureType :

    • XR_TYPE_SPATIAL_COMPONENT_SUBSUMED_BY_LIST_ANDROID
    • XR_TYPE_SPATIAL_DISCOVERY_UNIQUE_ENTITIES_FILTER_ANDROID

Problemas

Histórico de versões

  • Revisão 1, 19/11/2025 (Brian Chen)

    • Descrição inicial da extensão.