XR_ANDROID_spatial_discovery_bounds

String de nome

XR_ANDROID_spatial_discovery_bounds

Tipo de extensão

Extensão de instância

Número de ramal registrado

762

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_spatial_entity

Colaboradores

Nihav Jain, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Yin Li, Microsoft
Ron Bessems, Meta
Karthik Kadappan, Magic Leap
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Visão geral

Essa extensão adiciona definições para limites espaciais que permitem que os aplicativos filtrem entidades espaciais descobertas ao chamar xrCreateSpatialDiscoverySnapshotAsyncEXT .

Limites espaciais

A estrutura XrSpatialBoundsSpherefANDROID é definida como:

typedef struct XrSpatialBoundsSpherefANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrSpheref          sphere;
} XrSpatialBoundsSpherefANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • space é o XrSpace em que as poses dos limites são definidas.
  • time é um XrTime em que as poses dos limites são definidas.
  • sphere é um XrSpheref que descreve o volume esférico em que o ambiente de execução precisa restringir a descoberta de entidades espaciais.

Os recursos espaciais que oferecem suporte a XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID (conforme enumerado por xrEnumerateSpatialCapabilityFeaturesEXT) permitem que o aplicativo restrinja a descoberta a entidades espaciais com localização ou limites dentro ou que se cruzam com sphere ao encadear XrSpatialBoundsSpherefANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Para um snapshot de descoberta em que o recurso aplicável é compatível com XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID , se essa estrutura estiver presente na cadeia next, o ambiente de execução não pode incluir entidades espaciais com localização ou limites totalmente fora de sphere .

É importante observar que a inclusão de XrSpatialBoundsSpherefANDROID na próxima cadeia de XrSpatialDiscoverySnapshotCreateInfoEXT funciona como uma condição "AND" com os outros filtros fornecidos. As entidades provenientes de recursos espaciais que não são compatíveis com XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID não podem ser incluídas no snapshot de descoberta. Esse comportamento é diferente do restante da especificação do OpenXR, em que estruturas não reconhecidas ou não compatíveis na próxima cadeia de ponteiros são ignoradas pelo ambiente de execução. Além disso, conforme descrito na seção Exclusividade da estrutura da próxima cadeia, o ambiente de execução só vai processar a primeira ocorrência da estrutura XrSpatialBoundsSpherefANDROID na próxima cadeia.

Uso válido (implícito)

A estrutura XrSpatialBoundsBoxfANDROID é definida como:

typedef struct XrSpatialBoundsBoxfANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrBoxf             box;
} XrSpatialBoundsBoxfANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • space é o XrSpace em que as poses dos limites são definidas.
  • time é um XrTime em que as poses dos limites são definidas.
  • box é um XrBoxf que descreve o volume da caixa em que o ambiente de execução precisa restringir a descoberta de entidades espaciais.

Os recursos espaciais compatíveis com XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID (conforme enumerado por xrEnumerateSpatialCapabilityFeaturesEXT) permitem que o aplicativo restrinja a descoberta a entidades espaciais com localização ou limites dentro ou que se cruzam com box ao encadear XrSpatialBoundsBoxfANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Para um snapshot de descoberta em que o recurso aplicável é compatível com XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID , se essa estrutura estiver presente na cadeia next, o ambiente de execução não pode incluir entidades espaciais com localização ou limites totalmente fora de box .

É importante observar que a inclusão de XrSpatialBoundsBoxfANDROID na próxima cadeia de XrSpatialDiscoverySnapshotCreateInfoEXT funciona como uma condição "AND" com os outros filtros fornecidos. As entidades provenientes de recursos espaciais que não são compatíveis com XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID não podem ser incluídas no snapshot de descoberta. Esse comportamento é diferente do restante da especificação do OpenXR, em que estruturas não reconhecidas ou não compatíveis na próxima cadeia de ponteiros são ignoradas pelo ambiente de execução. Além disso, conforme descrito na seção Exclusividade da estrutura da próxima cadeia, o ambiente de execução só vai processar a primeira ocorrência da estrutura XrSpatialBoundsBoxfANDROID na próxima cadeia.

Uso válido (implícito)

A estrutura XrSpatialBoundsFrustumfANDROID é definida como:

typedef struct XrSpatialBoundsFrustumfANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrFrustumf         frustum;
} XrSpatialBoundsFrustumfANDROID;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • space é o XrSpace em que as poses dos limites são definidas.
  • time é um XrTime em que as poses dos limites são definidas.
  • frustum é um XrFrustumf que descreve o volume do tronco em que o ambiente de execução precisa restringir a descoberta de entidades espaciais.

Os recursos espaciais que oferecem suporte a XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID (conforme enumerado por xrEnumerateSpatialCapabilityFeaturesEXT) permitem que o aplicativo restrinja a descoberta a entidades espaciais com localização ou limites dentro ou que se cruzam com frustum ao encadear XrSpatialBoundsFrustumfANDROID a XrSpatialDiscoverySnapshotCreateInfoEXT :: next . Para um snapshot de descoberta em que o recurso aplicável é compatível com XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID , se essa estrutura estiver presente na cadeia next, o ambiente de execução não pode incluir entidades espaciais com localização ou limites totalmente fora de frustum .

É importante observar que a inclusão de XrSpatialBoundsFrustumfANDROID na próxima cadeia de XrSpatialDiscoverySnapshotCreateInfoEXT funciona como uma condição "AND" com os outros filtros fornecidos. As entidades provenientes de recursos espaciais que não são compatíveis com XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID não podem ser incluídas no snapshot de descoberta. Esse comportamento é diferente do restante da especificação do OpenXR, em que estruturas não reconhecidas ou não compatíveis na próxima cadeia de ponteiros são ignoradas pelo ambiente de execução. Além disso, conforme descrito na seção Exclusividade da estrutura da próxima cadeia, o ambiente de execução só vai processar a primeira ocorrência da estrutura XrSpatialBoundsFrustumfANDROID na próxima cadeia.

Uso válido (implícito)

Exemplo

O código a seguir demonstra como usar limites espaciais para filtrar a descoberta de entidades espaciais.

// previously initialized & configured with the XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT capability.
XrSpatialContextEXT spatialContext;

// Enumerate supported features for XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT capability
uint32_t featureCount = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, 0, &featureCount, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> fooFeatures(featureCount);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, featureCount, &featureCount, fooFeatures.data()));

// Check if spatial sphere bounds filter is supported
const auto supportsFeature = [&fooFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(fooFeatures.begin(), fooFeatures.end(), feature) != fooFeatures.end();
};

const bool supportsSphereBoundsFilter = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID);

// We want to look for entities in a sphere around the head with a radius of 2m.
XrSpatialBoundsSpherefANDROID sphereBounds {
  .type = XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID,
  .space = viewSpace,
  .time = predictedDisplayTime,
  .sphere = {
    .center = {
      .orientation = {
        .w = 1.0f,
      },
    },
    .radius = 2.0f,
  },
};

// We want to look for entities that have the following components.
std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT};

XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = supportsSphereBoundsFilter ? &sphereBounds : nullptr,
  .componentTypeCount = snapshotComponents.size(),
  .componentTypes = snapshotComponents.data(),
};

XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

Novas estruturas

Novas constantes de tipo enumerado

  • XR_ANDROID_SPATIAL_DISCOVERY_BOUNDS_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_bounds_SPEC_VERSION

  • Estendendo XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID
    • XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID
    • XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

  • Estendendo XrStructureType :

    • XR_TYPE_SPATIAL_BOUNDS_BOXF_ANDROID
    • XR_TYPE_SPATIAL_BOUNDS_FRUSTUMF_ANDROID
    • XR_TYPE_SPATIAL_BOUNDS_SPHEREF_ANDROID

Problemas

  • Por que o suporte para limites espaciais depende de uma definição de XrSpatialCapabilityFeatureEXT?

    • Resolvido
    • Resposta: nem todos os recursos espaciais são capazes de oferecer suporte a limites espaciais. Um exemplo disso é uma entidade de contêiner global hipotética que não tem nenhuma posição espacial ou limites próprios, mas apenas ajuda a coletar e organizar as outras entidades dentro dela. Os valores XrSpatialCapabilityFeatureEXT enumerados pelo recurso ajudam a informar ao app sobre o suporte à filtragem de limites espaciais.

Histórico de versões

  • Revisão 1, 03/05/2025 (Nihav Jain, Google)

    • Descrição inicial da extensão