XR_EXT_spatial_image_tracking

String de nome

XR_EXT_spatial_image_tracking

Tipo de extensão

Extensão de instância

Número de ramal registrado

783

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_EXT_spatial_entity

Colaboradores

Daniel Guttenberg, Qualcomm
Nihav Jain, Google
Jared Finder, Google
Zhipeng Liu, ByteDance

Visão geral

Essa extensão oferece o recurso de rastreamento de imagens para a extensão XR_EXT_spatial_entity. Ele permite que os aplicativos detectem e rastreiem imagens planas específicas, conforme definido por conjuntos de imagens de referência de entrada.

Uma imagem rastreada é representada como uma entidade espacial com os seguintes componentes:

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Os aplicativos normalmente usam a extensão de rastreamento de imagem espacial no seguinte padrão:

  • Primeiro, um aplicativo cria um ou vários identificadores XrSpatialImageTrackingDatabaseEXT com base em conjuntos de dados de imagem de referência pré-carregados.
  • Em seguida, o aplicativo cria um identificador XrSpatialContextEXT com base nos identificadores XrSpatialImageTrackingDatabaseEXT criados anteriormente.
  • Em seguida, o aplicativo libera os dados da imagem de referência para reduzir o consumo de memória.
  • O aplicativo descobre e consulta imagens de acordo com os padrões de acesso de entidades espaciais.
  • O aplicativo pode carregar outros conjuntos de imagens de referência e criar mais XrSpatialImageTrackingDatabaseEXT e, em seguida, XrSpatialContextEXT com base neles para ampliar o conjunto de imagens detectáveis e rastreáveis de forma dinâmica no momento da execução.
  • O aplicativo pode destruir identificadores XrSpatialImageTrackingDatabaseEXT para reduzir o conjunto de imagens detectáveis e rastreáveis dinamicamente no momento da execução.
  • O aplicativo pode destruir identificadores XrSpatialContextEXT para reduzir o conjunto de imagens detectáveis e rastreáveis dinamicamente no momento da execução.

Suporte ao ambiente de execução

Um ambiente de execução precisa anunciar que oferece suporte ao recurso de rastreamento de imagens usando xrEnumerateSpatialCapabilitiesEXT e listando o seguinte recurso:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

Configuração

Para ativar a detecção e o rastreamento de imagens planas, o aplicativo pode transmitir estruturas XrSpatialCapabilityConfigurationImageTrackingEXT em XrSpatialContextCreateInfoEXT :: capabilityConfigs ao chamar a função xrCreateSpatialContextAsyncEXT e transmitir matrizes de estruturas XrSpatialImageTrackingDatabaseEXT em cada XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

Criação do conjunto de imagens de entrada

Para especificar as imagens de referência a serem detectadas e rastreadas, o aplicativo precisa criar pelo menos um conjunto de imagens de referência de entrada. Um conjunto de imagens de referência de entrada é representado por um identificador XrSpatialImageTrackingDatabaseEXT e contém pelo menos uma imagem.

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

O identificador XrSpatialImageTrackingDatabaseEXT representa os recursos para descobrir e atualizar um número de imagens espaciais no ambiente do usuário. Os aplicativos podem usar esse identificador para descobrir e atualizar imagens espaciais usando outras funções nessa extensão.

Criar o banco de dados de rastreamento de imagens espaciais

A função xrCreateSpatialImageTrackingDatabaseAsyncEXT é definida como:

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

Descrições dos parâmetros

  • session é uma XrSession em que o banco de dados de rastreamento de imagens espaciais estará ativo.
  • createInfo é o XrSpatialImageTrackingDatabaseCreateInfoEXT usado para especificar os parâmetros do banco de dados de rastreamento de imagens espaciais.
  • future é um ponteiro para um XrFutureEXT .

Um aplicativo pode criar um identificador XrSpatialImageTrackingDatabaseEXT usando a função xrCreateSpatialImageTrackingDatabaseAsyncEXT e configurar os conjuntos de imagens de referência de entrada do banco de dados de rastreamento de imagens com createInfo .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT se o XrSpatialReferenceImageEXT :: format de qualquer uma das imagens de referência de entrada não for enumerado por xrEnumerateSpatialReferenceImageFormatsEXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_IMAGE_INVALID_EXT se a matriz planes de XrSpatialReferenceImageEXT de qualquer uma das imagens de referência de entrada não puder ser avaliada de acordo com os metadados da imagem de referência de XrSpatialReferenceImageEXT .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_IMAGE_INVALID_EXT se a matriz planes de XrSpatialReferenceImageEXT de qualquer uma das imagens de referência de entrada não fornecer exatamente o mesmo número de planos que os canais de cores de format de XrSpatialReferenceImageEXT.

Se um ambiente de execução aplicar um sistema de permissões para controlar o acesso do aplicativo ao recurso de rastreamento de imagens, ele precisará retornar XR_ERROR_PERMISSION_INSUFFICIENT se essas permissões não tiverem sido concedidas ao aplicativo.

Essa função inicia uma operação assíncrona e cria um XrFutureEXT correspondente, que pode ser usado com xrPollFutureEXT e funções relacionadas. O valor de retorno dessa função indica apenas se os parâmetros eram aceitáveis para programar a operação assíncrona. A função de conclusão correspondente é xrCreateSpatialImageTrackingDatabaseCompleteEXT , que pode ser usada quando um futuro dessa função está no estado READY, com saídas preenchidas por essa função na estrutura de conclusão XrCreateSpatialImageTrackingDatabaseCompletionEXT .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrSpatialImageTrackingDatabaseCreateInfoEXT é definida como:

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • spatialReferenceImageCount é o número de elementos na matriz spatialReferenceImages.
  • spatialReferenceImages é uma matriz de XrSpatialReferenceImageEXT .

A estrutura XrSpatialImageTrackingDatabaseCreateInfoEXT descreve as informações para criar um identificador XrSpatialImageTrackingDatabaseEXT.

Cada XrSpatialImageTrackingDatabaseEXT precisa ser criado com pelo menos um XrSpatialReferenceImageEXT na matriz XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

Uso válido (implícito)

A função xrCreateSpatialImageTrackingDatabaseCompleteEXT é definida como:

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

Descrições dos parâmetros

xrCreateSpatialImageTrackingDatabaseCompleteEXT conclui a operação assíncrona iniciada por xrCreateSpatialImageTrackingDatabaseAsyncEXT .

O ambiente de execução não pode acessar nenhum ponteiro XrSpatialReferenceImagePlaneEXT :: buffer fornecido pela matriz de entrada XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages para essa chamada xrCreateSpatialImageTrackingDatabaseAsyncEXT após a conclusão. O aplicativo pode liberar todos os dados de XrSpatialReferenceImagePlaneEXT :: buffer após a conclusão de xrCreateSpatialImageTrackingDatabaseAsyncEXT para reduzir o consumo de memória.

O ambiente de execução precisa retornar XR_ERROR_FUTURE_PENDING_EXT se future não estiver no estado pronto. O ambiente de execução precisa retornar XR_ERROR_FUTURE_INVALID_EXT se future já tiver sido concluído ou cancelado.

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

A estrutura XrCreateSpatialImageTrackingDatabaseCompletionEXT é definida como:

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

Descrições dos membros

Códigos de retorno futuros

Valores de futureResult:

Sucesso

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Falha

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

Se futureResult for um código de sucesso, database precisa ser um identificador válido. Se database for válido, ele vai permanecer assim apenas no ciclo de vida de xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session ou até que o aplicativo destrua o database com xrDestroySpatialImageTrackingDatabaseEXT , o que ocorrer primeiro.

Uso válido (implícito)

Destruir o banco de dados de rastreamento de imagens espaciais

A função xrDestroySpatialImageTrackingDatabaseEXT é definida como:

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

Descrições dos parâmetros

O aplicativo pode chamar a função xrDestroySpatialImageTrackingDatabaseEXT para liberar o identificador database e os recursos associados quando terminar as tarefas de descoberta e atualização de imagens espaciais.

O aplicativo pode chamar a função xrDestroySpatialImageTrackingDatabaseEXT antes de chamar xrDestroySpatialContextEXT . O ambiente de execução não pode mais informar imagens gerenciadas por esse XrSpatialImageTrackingDatabaseEXT destruído. O ambiente de execução precisa continuar informando as imagens gerenciadas por outros bancos de dados.

O ambiente de execução precisa garantir que os snapshots de descoberta retornados por xrCreateSpatialDiscoverySnapshotCompleteEXT não contenham imagens relacionadas a identificadores XrSpatialImageTrackingDatabaseEXT destruídos ou inválidos, mesmo que o identificador tenha sido destruído depois que o aplicativo chamou xrCreateSpatialDiscoverySnapshotAsyncEXT . Como os dados em um snapshot espacial são imutáveis, o aplicativo precisa destruir todos os identificadores XrSpatialSnapshotEXT criados antes de destruir database. Caso contrário, o aplicativo pode receber identificadores XrSpatialImageTrackingDatabaseEXT inválidos ao usar xrQuerySpatialComponentDataEXT.

O aplicativo pode chamar a função xrDestroySpatialContextEXT para liberar o identificador XrSpatialContextEXT antes de destruir qualquer um dos identificadores XrSpatialImageTrackingDatabaseEXT com que XrSpatialContextEXT foi criado. O ambiente de execução não pode destruir implicitamente esses identificadores XrSpatialImageTrackingDatabaseEXT quando o XrSpatialContextEXT é destruído.

Gerenciar o ciclo de vida de XrSpatialContextEXT e XrSpatialImageTrackingDatabaseEXT de forma independente permite que os aplicativos reutilizem identificadores XrSpatialImageTrackingDatabaseEXT criados anteriormente sem precisar refazer o processo de criação, que é caro.

Por exemplo, destruir um XrSpatialContextEXT e recriar outro XrSpatialContextEXT com o mesmo XrSpatialImageTrackingDatabaseEXT permite pausar e retomar o rastreamento de imagens sem precisar realizar outro procedimento de inicialização.

Uso válido (implícito)

Concorrência segura

  • O acesso a database e a qualquer identificador filho precisa ser sincronizado externamente.

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Suporte a formatos da imagem de entrada

Os aplicativos precisam chamar xrEnumerateSpatialReferenceImageFormatsEXT para receber a lista de formatos da imagem de referência de entrada compatíveis.

A função xrEnumerateSpatialReferenceImageFormatsEXT é definida como:

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

Descrições dos parâmetros

  • instance é um identificador para uma XrInstance .
  • systemId é o XrSystemId em que os formatos da imagem de referência de entrada serão enumerados.
  • capability é o XrSpatialCapabilityEXT para o qual os formatos de imagem de referência de entrada serão enumerados.
  • formatCapacityInput é a capacidade da matriz formats ou 0 para indicar uma solicitação de recuperação da capacidade necessária.
  • formatCountOutput é o número de formatos ou a capacidade necessária caso formatCapacityInput seja insuficiente.
  • formats é uma matriz de XrSpatialReferenceImageFormatEXT . Pode ser NULL se formatCapacityInput for 0.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho de formats necessário.

O aplicativo pode enumerar a lista de formatos de imagem de referência de entrada compatíveis com um determinado XrSystemId para um determinado XrSpatialCapabilityEXT usando xrEnumerateSpatialReferenceImageFormatsEXT .

O ambiente de execução não pode enumerar os formatos de extensões que não estão ativadas para instance .

Uso válido (implícito)

Códigos de retorno

Sucesso

  • XR_SUCCESS

Falha

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Consulte XrSpatialReferenceImageFormatEXT para ver uma lista completa de todos os formatos de imagem de referência compatíveis com qualquer extensão.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

A enumeração XrSpatialReferenceImageFormatEXT identifica os formatos da imagem de referência de entrada que o ambiente de execução pode aceitar.

Pelo menos os valores XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT e XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT precisam ser aceitos.

Os enumerantes têm o seguinte significado:

Descrições de enumerantes

  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT: um buffer RGBA. O formato não oferece garantias quanto ao layout dos dados de pixel na memória. Os pixels precisam ser acessados usando os metadados fornecidos pelas estruturas XrSpatialReferenceImagePlaneEXT correspondentes. Cada canal de cor de pixel tem um tamanho de 8 bits, o que faz com que cada pixel tenha 32 bits.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT: um buffer RGB. O formato não oferece garantias quanto ao layout dos dados de pixel na memória. Os pixels precisam ser acessados usando os metadados fornecidos pelas estruturas XrSpatialReferenceImagePlaneEXT correspondentes. Cada canal de cor de pixel tem um tamanho de 8 bits, o que faz com que cada pixel tenha 24 bits.
  • XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT: um buffer YUV com subamostragem de croma de padrão 4:2:0. O formato não oferece garantias quanto ao layout dos dados de pixel na memória. Os pixels precisam ser acessados usando os metadados fornecidos pelas estruturas XrSpatialReferenceImagePlaneEXT correspondentes. Cada canal de cor de pixel RGB decodificado tem um tamanho de 8 bits, o que faz com que cada pixel tenha 24 bits.

Configurações de rastreamento de imagem espacial

Essa extensão fornece estruturas opcionais que o aplicativo pode usar para configurar o recurso de rastreamento de imagens.

Otimização de imagens estáticas

A estrutura XrSpatialImageStaticOptimizationEXT é definida como:

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • optimizeForStaticImage é um XrBool32 que indica se as imagens se movem ou não. Um valor de XR_TRUE indica que as imagens não se movem.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT for enumerado por xrEnumerateSpatialCapabilityFeaturesEXT para o recurso XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, o aplicativo poderá encadear XrSpatialImageStaticOptimizationEXT à cadeia XrSpatialImageTrackingDatabaseCreateInfoEXT :: next ou XrSpatialReferenceImageEXT :: next .

Se o aplicativo encadear XrSpatialImageStaticOptimizationEXT à estrutura XrSpatialImageTrackingDatabaseCreateInfoEXT, o ambiente de execução precisará presumir que todas as imagens desse XrSpatialImageTrackingDatabaseEXT são estáticas se optimizeForStaticImage estiver definido como XR_TRUE . Da mesma forma, o ambiente de execução precisa presumir que todas as imagens desse XrSpatialImageTrackingDatabaseEXT não são estáticas se optimizeForStaticImage estiver definido como XR_FALSE .

Se o aplicativo encadear XrSpatialImageStaticOptimizationEXT à estrutura XrSpatialReferenceImageEXT, o ambiente de execução precisará presumir que essa imagem de referência é estática se optimizeForStaticImage estiver definido como XR_TRUE . Da mesma forma, o ambiente de execução precisa presumir que essa imagem de referência não é estática se optimizeForStaticImage estiver definido como XR_FALSE . Encadear a estrutura XrSpatialImageStaticOptimizationEXT à estrutura XrSpatialReferenceImageEXT tem precedência sobre o encadeamento à estrutura XrSpatialImageTrackingDatabaseCreateInfoEXT.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT não for enumerado por xrEnumerateSpatialCapabilityFeaturesEXT para o recurso XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT e o aplicativo encadear uma estrutura XrSpatialImageStaticOptimizationEXT a qualquer uma das próximas cadeias aplicáveis, o ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrCreateSpatialImageTrackingDatabaseAsyncEXT .

Isso pode permitir que o ambiente de execução gere uma pose e um tamanho mais precisos.

Isso pode permitir que o ambiente de execução reduza o consumo de energia.

Uso válido (implícito)

Largura da imagem de referência

A estrutura XrSpatialImageSizeEXT é definida como:

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • physicalWidth é um valor float que representa a largura física em metros a ser definida.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT for enumerado por xrEnumerateSpatialCapabilityFeaturesEXT para o recurso XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, o aplicativo poderá encadear XrSpatialImageSizeEXT a XrSpatialImageTrackingDatabaseCreateInfoEXT :: next ou XrSpatialReferenceImageEXT :: next .

Se o aplicativo encadear XrSpatialImageSizeEXT à estrutura XrSpatialImageTrackingDatabaseCreateInfoEXT, o ambiente de execução precisará presumir que todas as imagens desse XrSpatialImageTrackingDatabaseEXT têm uma largura de physicalWidth metros e uma altura de acordo com a proporção fornecida implicitamente por XrSpatialReferenceImageEXT :: width e XrSpatialReferenceImageEXT :: height .

Se o aplicativo encadear XrSpatialImageSizeEXT à estrutura XrSpatialReferenceImageEXT, o ambiente de execução precisará presumir que essa imagem de referência tem uma largura de physicalWidth metros e uma altura de acordo com a proporção fornecida implicitamente por XrSpatialReferenceImageEXT :: width e XrSpatialReferenceImageEXT :: height . Encadear a estrutura XrSpatialImageSizeEXT à estrutura XrSpatialReferenceImageEXT tem precedência sobre encadeá-la à estrutura XrSpatialImageTrackingDatabaseCreateInfoEXT.

Isso pode permitir que o ambiente de execução retorne uma pose e um tamanho mais precisos.

O ambiente de execução precisa enumerar XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT ou XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT ou ambos.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT for enumerado por xrEnumerateSpatialCapabilityFeaturesEXT, o ambiente de execução precisará fornecer tamanhos de imagem automaticamente para imagens em que o aplicativo não forneceu nenhuma estrutura XrSpatialImageSizeEXT como parte de nenhuma das próximas cadeias aplicáveis.

Para que o ambiente de execução possa gerar tamanhos de imagem de forma automática e precisa, alguns recursos e pré-requisitos do dispositivo podem ser necessários, como câmeras estéreo e parâmetros extrínsecos e intrínsecos da câmera calibrados com precisão.

Se XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT não for enumerado por xrEnumerateSpatialCapabilityFeaturesEXT, o aplicativo precisará vincular as estruturas XrSpatialImageSizeEXT às próximas cadeias aplicáveis para que todas as imagens tenham um tamanho explícito fornecido. Caso contrário, o ambiente de execução precisará retornar XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT de xrCreateSpatialImageTrackingDatabaseAsyncEXT.

Uso válido (implícito)

A estrutura XrSpatialCapabilityConfigurationImageTrackingEXT é definida como:

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • capability é um XrSpatialCapabilityEXT e precisa ser XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT .
  • enabledComponentCount é um uint32_t que especifica o número de elementos em enabledComponents .
  • enabledComponents é uma matriz de XrSpatialComponentTypeEXT que especifica os componentes a serem ativados para esse recurso.
  • imageTrackingDatabaseCount é um unint32_t que especifica o número de elementos em imageTrackingDatabases .
  • imageTrackingDatabases é uma matriz de identificadores XrSpatialImageTrackingDatabaseEXT que especifica os bancos de dados de rastreamento de imagens a serem ativados para o contexto espacial.

Se o rastreamento de imagens for compatível, o ambiente de execução precisará ativar o rastreamento de imagens se uma estrutura XrSpatialCapabilityConfigurationImageTrackingEXT for transmitida em XrSpatialContextCreateInfoEXT :: capabilityConfigs ao chamar xrCreateSpatialContextAsyncEXT .

A estrutura XrSpatialCapabilityConfigurationImageTrackingEXT permite que o aplicativo descubra as imagens de referência representadas pelos identificadores XrSpatialImageTrackingDatabaseEXT em imageTrackingDatabases .

O ambiente de execução precisa retornar XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT se XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT não for enumerado por xrEnumerateSpatialCapabilitiesEXT .

Uso válido (implícito)

Imagem de referência espacial

A estrutura XrSpatialReferenceImagePlaneEXT é definida como:

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

Descrições dos parâmetros

  • bufferSize é o tamanho da matriz buffer.
  • buffer é uma matriz de dados uint8_t que representa os dados do plano.
  • rowStride é a distância em bytes entre duas posições iniciais de linhas de dados de pixel consecutivas.
  • pixelStride é a distância em bytes entre dois pixels consecutivos.

O ambiente de execução precisa acessar buffer de acordo com os padrões fornecidos pelos parâmetros rowStride e pixelStride.

O aplicativo precisa definir rowStride e pixelStride de modo que apenas pixels significativos desse XrSpatialReferenceImagePlaneEXT sejam extraídos pelo ambiente de execução.

Uso válido (implícito)

  • A extensão XR_EXT_spatial_image_tracking precisa ser ativada antes de usar XrSpatialReferenceImagePlaneEXT
  • buffer precisa ser um ponteiro para uma matriz de valores bufferSize uint8_t
  • O parâmetro bufferSize precisa ser maior que 0.

A estrutura XrSpatialReferenceImageEXT é definida como:

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

Descrições dos parâmetros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • width é a largura em pixels da imagem de referência.
  • height é a altura em pixels da imagem de referência.
  • format é um XrSpatialReferenceImageFormatEXT que representa o formato da imagem.
  • planeCount é o número de elementos na matriz planes.
  • planes é uma matriz de estruturas XrSpatialReferenceImagePlaneEXT que representam os planos dos dados de imagem.

O aplicativo pode criar uma ou mais estruturas XrSpatialReferenceImageEXT, cada uma representando uma única imagem de referência de entrada a ser transmitida para a função xrCreateSpatialImageTrackingDatabaseAsyncEXT por meio de XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages ao criar um identificador XrSpatialImageTrackingDatabaseEXT.

Os dados buffer de XrSpatialReferenceImagePlaneEXT precisam ser fornecidos em uma ordem de pixels da esquerda para a direita e de cima para baixo pelo aplicativo.

O aplicativo precisa fornecer uma estrutura XrSpatialReferenceImagePlaneEXT na matriz XrSpatialReferenceImageEXT :: planes para cada canal de cor de XrSpatialReferenceImageEXT :: format .

Uso válido (implícito)

Componentes garantidos

Um ambiente de execução que oferece suporte a XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT precisa fornecer os seguintes componentes espaciais como componentes garantidos de todas as entidades descobertas por esses recursos e precisa enumerá-los em xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

Componente de imagem 2D

Estrutura de lista de componentes para consultar dados

A estrutura XrSpatialComponentImage2DListEXT é definida como:

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

Descrições dos parâmetros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas.
  • imageCount é o número de elementos na matriz images.
  • images é uma matriz de XrSpatialImage2DDataEXT .

O ambiente de execução precisa retornar XR_ERROR_VALIDATION_FAILURE de xrQuerySpatialComponentDataEXT se XrSpatialComponentImage2DListEXT estiver na cadeia XrSpatialComponentDataQueryResultEXT :: next, mas XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT não estiver incluído em XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

Uso válido (implícito)

Dados do componente

A estrutura XrSpatialImage2DDataEXT é definida como:

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

Descrições dos parâmetros

O aplicativo pode usar imageTrackingDatabase para identificar qual XrSpatialImageTrackingDatabaseEXT criado anteriormente contém a imagem de referência dessa estrutura XrSpatialImage2DDataEXT. Para esse XrSpatialImageTrackingDatabaseEXT, o aplicativo pode usar referenceImageIndex para identificar o XrSpatialReferenceImageEXT dessa estrutura XrSpatialImage2DDataEXT, correspondendo-o à ordem de entrada da matriz XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

O conjunto de imagens de referência definido pelo conjunto de todos os bancos de dados ativos não pode incluir imagens duplicadas. Incluir imagens duplicadas pode causar um comportamento adverso de descoberta ou rastreamento, ou seja, índices inconsistentes ou múltiplos sendo retornados.

Uso válido (implícito)

Configuração

Se XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT for enumerado em XrSpatialCapabilityComponentTypesEXT :: componentTypes para algum recurso, o aplicativo poderá ativá-lo incluindo o valor do tipo enumerado na lista XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Esse componente não requer nenhuma configuração especial para ser incluído na próxima cadeia de XrSpatialCapabilityConfigurationBaseHeaderEXT .

Componente 2D limitado

O componente 2D limitado fornece o centro e as extensões da imagem espacial representada pela entidade em que ele está. Consulte Bounded 2D para mais detalhes sobre o componente 2D limitado.

Código de exemplo

Descobrir imagens espaciais e consultar dados de componentes

O exemplo de código a seguir demonstra como descobrir entidades espaciais para o recurso de rastreamento de imagens e consultar os dados do componente.

XrInstance instance; // Previously initialized
XrSystemId systemId; // Previously initialized
XrSession session; // Previously initialized

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

Novos tipos de objeto

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de tipo enumerado

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • Estendendo XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • Estendendo XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • Estendendo XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • Estendendo XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • Estendendo XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • Estendendo XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

Problemas

Histórico de versões

  • Revisão 1, 22/04/2025 (Daniel Guttenberg, Qualcomm)

    • Descrição inicial da extensão