XR_ANDROID_spatial_component_subsumed_by

String de nome

XR_ANDROID_spatial_component_subsumed_by

Tipo de extensão

Extensão de instância

Número de ramal registrado

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 do IP

Nenhuma reivindicação de PI 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 fornece um novo componente para que XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT exponha o XrSpatialEntityIdEXT que inclui a entidade atual.

Quando o ambiente de execução tiver adquirido informações suficientes para detectar que dois planos rastreados são, na verdade, o mesmo, o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID com o ID de um dos planos será anexado ao outro. A partir de então, 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 introduz um novo filtro, que o aplicativo pode encadear a XrSpatialDiscoverySnapshotCreateInfoEXT para filtrar todas as entidades que têm o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID.

Permissões

Os apps 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 for capaz de incluir um plano em outro, ele precisa indicar isso enumerando XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID como um componente compatível com o recurso XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT em xrEnumerateSpatialCapabilityComponentTypesEXT .

Todos os dados de componente da entidade anexada XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID precisam ser idênticos aos da entidade que a subsume.

Subsumido por componente

Dados do componente

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID usa a estrutura XrSpatialEntityIdEXT para os dados, que representa o ID da entidade de subsumação.

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 dos 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 valores subsumedUniqueIdCount XrSpatialEntityIdEXT
  • 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 o recurso XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, o aplicativo poderá ativá-lo incluindo o tipo enumerado na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents da estrutura derivada de XrSpatialCapabilityConfigurationBaseHeaderEXT do recurso que oferece suporte a esse componente.

Filtrar entidades incluídas

A estrutura XrSpatialDiscoveryUniqueEntitiesFilterANDROID é definida como:

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

Descrições dos 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 estão incluídas em outra entidade.

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

Se o aplicativo encadear XrSpatialDiscoveryUniqueEntitiesFilterANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT, mas não listar nenhum componente em XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes, o ambiente de execução precisa incluir todas as entidades espaciais no snapshot que têm o conjunto de componentes enumerados em XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents para os recursos configurados 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 o recurso de rastreamento de plano

O exemplo de código a seguir demonstra como criar um contexto espacial com o recurso 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))

Dados do componente de consulta

O exemplo de código a seguir demonstra como consultar dados do componente 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 subsumidas

O exemplo de código a seguir demonstra como usar o filtro para remover do snapshot de descoberta as entidades com o componente XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID anexado, além de consultar o ID das entidades de subsumação.

// 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 tipo enumerado

  • 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.