XR_ANDROID_trackables_image
String de nome
XR_ANDROID_trackables_image
Tipo de extensão
Extensão de instância
Número de ramal registrado
710
Revisão
1
Status da ratificação
Não ratificado
Dependências de extensão e versão
XR_EXT_future
e
XR_ANDROID_trackables
Data da última modificação
2025-04-08
Status do IP
Não há reivindicações de IP conhecidas.
Colaboradores
Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Daniel Guttenberg, Qualcomm
Mark Vadasi, Qualcomm
Markus Birkner, Qualcomm
Maximilian Mayer, Qualcomm
Visão geral
Essa extensão permite o rastreamento de imagens planas, conforme especificado por conjuntos de imagens de referência de entrada.
Permissões
Os aplicativos Android precisam ter a permissão android.permission.SCENE_UNDERSTANDING_COARSE listada no manifesto, já que essa extensão depende do XR_ANDROID_trackables e expõe a geometria do ambiente. A permissão android.permission.SCENE_UNDERSTANDING_COARSE é considerada perigosa.
(nível de proteção: perigoso)
Inspecionar a capacidade do sistema
A estrutura XrSystemImageTrackingPropertiesANDROID é definida como:
typedef struct XrSystemImageTrackingPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsImageTracking;
XrBool32 supportsPhysicalSizeEstimation;
uint32_t maxTrackedImageCount;
uint32_t maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;
Descrições de membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão. Para mais detalhes sobre a cadeia de estrutura, consulte a estrutura que está sendo estendida ( XrSystemProperties ).supportsImageTrackingé umXrBool32que indica se o sistema atual oferece capacidade de rastreamento de imagens.supportsPhysicalSizeEstimationé umXrBool32que indica se o sistema atual fornece estimativa de tamanho da imagem.maxTrackedImageCounté o número máximo total de imagens que podem ser rastreadas ao mesmo tempo.maxLoadedImageCounté o número máximo total de imagens de referência que podem ser carregadas em todos os bancos de dados.
Um aplicativo pode inspecionar se o sistema é capaz de rastrear imagens estendendo o XrSystemProperties com a estrutura XrSystemImageTrackingPropertiesANDROID ao chamar xrGetSystemProperties . O tempo de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED para a criação de rastreadores de imagens se e somente se supportsImageTracking for XR_FALSE .
Se um ambiente de execução for compatível com o rastreamento de imagens, ele precisa ser compatível com maxTrackedImageCount imagens rastreadas a qualquer momento.
Se um ambiente de execução for compatível com o rastreamento de imagens, ele precisa ser compatível com maxLoadedImageCount imagens carregadas a qualquer momento.
Se um tempo de execução oferecer suporte à estimativa de tamanho da imagem, o aplicativo poderá definir XrTrackableImageDatabaseEntryANDROID :: physicalWidth 0 para indicar o uso da estimativa de tamanho. Caso contrário, o aplicativo precisa definir XrTrackableImageDatabaseEntryANDROID :: physicalWidth como um valor positivo. Se não fizer isso, XR_ERROR_VALIDATION_FAILURE será retornado.
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de usar XrSystemImageTrackingPropertiesANDROID. -
typeprecisa serXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
Como criar bancos de dados
O aplicativo pode criar um identificador XrTrackableImageDatabaseANDROID criando uma ou mais estruturas XrTrackableImageDatabaseEntryANDROID e transmitindo-as para a função xrCreateTrackableImageDatabaseAsyncANDROID usando uma estrutura XrTrackableImageDatabaseCreateInfoANDROID.
O aplicativo precisa fornecer pelo menos um XrTrackableImageDatabaseEntryANDROID ao criar um identificador XrTrackableImageDatabaseANDROID.
Um XrTrackableImageDatabaseANDROID é um identificador que representa um conjunto de imagens de referência processadas que podem ser descobertas e rastreadas no ambiente.
XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)
A estrutura XrTrackableImageDatabaseEntryANDROID é definida como:
typedef struct XrTrackableImageDatabaseEntryANDROID {
XrStructureType type;
const void* next;
XrTrackableImageTrackingModeANDROID trackingMode;
float physicalWidth;
uint32_t imageWidth;
uint32_t imageHeight;
XrTrackableImageFormatANDROID format;
uint32_t bufferSize;
const uint8_t* buffer;
} XrTrackableImageDatabaseEntryANDROID;
Descrições de membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.trackingModeé um XrTrackableImageTrackingModeANDROID que indica o modo desejado para o rastreamento.physicalWidthindica a largura da imagem em metros. Se for zero, o tamanho da imagem será estimado on-line.imageWidthindica a largura da imagem em pixels.imageHeightindica a altura da imagem em pixels.formaté um XrTrackableImageFormatANDROID que indica o formato dos dados de imagem embuffer.bufferSizeindica o comprimento de bytes debuffer.bufferé o bufferuint8_tque contém os dados de pixel de imagem da imagem de referência. O conteúdo debufferprecisa ser válido durante a operação assíncrona de criação do banco de dados, que é iniciada por xrCreateTrackableImageDatabaseAsyncANDROID e concluída por xrCreateTrackableImageDatabaseCompleteANDROID .
O aplicativo pode definir physicalWidth como 0 para solicitar a estimativa de tamanho on-line se XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation for XR_TRUE .
O tempo de execução pode retornar XR_ERROR_VALIDATION_FAILURE de xrCreateTrackableImageDatabaseAsyncANDROID se bufferSize não corresponder ao tamanho esperado com base em imageWidth , imageHeight e format da entrada .
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de usar XrTrackableImageDatabaseEntryANDROID. -
typeprecisa serXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas -
trackingModeprecisa ser um valor XrTrackableImageTrackingModeANDROID válido -
formatprecisa ser um valor XrTrackableImageFormatANDROID válido -
bufferprecisa ser um ponteiro para uma matriz de valoresbufferSizeuint8_t. - O parâmetro
bufferSizeprecisa ser maior que0
A estrutura XrTrackableImageDatabaseCreateInfoANDROID é definida como:
typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
XrStructureType type;
const void* next;
uint32_t entryCount;
const XrTrackableImageDatabaseEntryANDROID* entries;
} XrTrackableImageDatabaseCreateInfoANDROID;
Descrições de membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.entryCounté umuint32_tque especifica a contagem de elementos na matrizentries.entriesé uma matriz de estruturas XrTrackableImageDatabaseEntryANDROID.
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de usar XrTrackableImageDatabaseCreateInfoANDROID. -
typeprecisa serXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas -
entriesprecisa ser um ponteiro para uma matriz deentryCountestruturas XrTrackableImageDatabaseEntryANDROID válidas - O parâmetro
entryCountprecisa ser maior que0
A estrutura XrCreateTrackableImageDatabaseCompletionANDROID é definida como:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
Descrições de membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.futureResulté o XrResult da operação assíncrona.databaseé o identificador XrTrackableImageDatabaseANDROID criado.
Códigos de retorno futuros
Valores de futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de usar XrCreateTrackableImageDatabaseCompletionANDROID. -
typeprecisa serXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas -
futureResultprecisa ser um valor XrResult válido -
databaseprecisa ser um identificador XrTrackableImageDatabaseANDROID válido.
A função xrCreateTrackableImageDatabaseAsyncANDROID é definida como:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
Descrições dos parâmetros
sessioné um identificador de uma XrSession criada anteriormente com xrCreateSession .createInfoé um ponteiro para uma estrutura XrTrackableImageDatabaseCreateInfoANDROID.futureé um ponteiro para oXrFutureEXTcriado .
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de chamar xrCreateTrackableImageDatabaseAsyncANDROID. -
sessionprecisa ser um identificador XrSession válido -
createInfoprecisa ser um ponteiro para uma estrutura XrTrackableImageDatabaseCreateInfoANDROID válida -
futureprecisa ser um ponteiro para um valorXrFutureEXT.
Códigos de retorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
A função xrCreateTrackableImageDatabaseCompleteANDROID é definida como:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
Descrições dos parâmetros
sessioné um identificador de uma XrSession criada anteriormente com xrCreateSession .futureé oXrFutureEXTdo futuro a ser concluído.completioné um ponteiro para uma estrutura XrCreateTrackableImageDatabaseCompletionANDROID que contém o resultado da operação.
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de chamar xrCreateTrackableImageDatabaseCompleteANDROID. -
sessionprecisa ser um identificador XrSession válido -
completionprecisa ser um ponteiro para uma estrutura XrCreateTrackableImageDatabaseCompletionANDROID.
Códigos de retorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
A função xrDestroyTrackableImageDatabaseANDROID é definida como:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
Descrições dos parâmetros
databaseé o identificador XrTrackableImageDatabaseANDROID a ser destruído.
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de chamar xrDestroyTrackableImageDatabaseANDROID. -
databaseprecisa ser um identificador XrTrackableImageDatabaseANDROID válido.
Concorrência segura
- O acesso a
databasee a qualquer identificador filho precisa ser sincronizado externamente.
Códigos de retorno
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_RUNTIME_FAILURE
Imagens de rastreamento
Essa extensão adiciona XR_TRACKABLE_TYPE_IMAGE_ANDROID a XrTrackableTypeANDROID .
O aplicativo pode criar um XrTrackableTrackerANDROID chamando xrCreateTrackableTrackerANDROID e especificando XR_TRACKABLE_TYPE_IMAGE_ANDROID como o tipo rastreável em XrTrackableTrackerCreateInfoANDROID :: trackableType para rastrear imagens.
O tempo de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED se XrTrackableTrackerCreateInfoANDROID :: trackableType for XR_TRACKABLE_TYPE_IMAGE_ANDROID e XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking retornar XR_FALSE via xrGetSystemProperties .
A estrutura XrTrackableImageConfigurationANDROID é definida como:
typedef struct XrTrackableImageConfigurationANDROID {
XrStructureType type;
const void* next;
uint32_t databaseCount;
const XrTrackableImageDatabaseANDROID* databases;
} XrTrackableImageConfigurationANDROID;
Descrições de membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.databaseCounté umuint32_tque especifica o número de elementos emdatabases.databasesé uma matriz de XrTrackableImageDatabaseANDROID que especifica os bancos de dados para criar o rastreador.
O aplicativo precisa definir uma configuração válida adicionando um XrTrackableImageConfigurationANDROID à cadeia next de XrTrackableTrackerCreateInfoANDROID . Caso contrário, o tempo de execução precisa retornar XR_ERROR_VALIDATION_FAILURE .
O aplicativo precisa fornecer pelo menos uma estrutura XrTrackableImageDatabaseANDROID para criar o rastreador.
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de usar XrTrackableImageConfigurationANDROID. -
typeprecisa serXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas -
databasesprecisa ser um ponteiro para uma matriz dedatabaseCountidentificadores XrTrackableImageDatabaseANDROID válidos - O parâmetro
databaseCountprecisa ser maior que0
O enum XrTrackableImageTrackingModeANDROID descreve os modos de rastreamento de imagens compatíveis.
typedef enum XrTrackableImageTrackingModeANDROID {
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;
Descrições de enumeradores
XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID: esse modo tem a maior precisão e permite o rastreamento de baixa latência de imagens em movimento. Ele também tem o maior consumo de energia.XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID: esse modo deve ser usado para imagens estáticas ou semiestáticas. Esse modo consome menos energia em comparação com o modo dinâmico. Se uma imagem estática estiver sendo movida, ela será atualizada com uma latência muito maior do que usando o modo dinâmico.
O enum XrTrackableImageFormatANDROID descreve os formatos de imagem compatíveis.
typedef enum XrTrackableImageFormatANDROID {
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;
Descrições de enumeradores
XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID: formato de imagem RGBA com dados de cor e transparência de 8 bits por canal.
A função xrAddTrackableImageDatabaseANDROID é definida como:
XrResult xrAddTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Descrições dos parâmetros
trackeré o identificador XrTrackableTrackerANDROID a que odatabaseserá adicionado.databaseé o identificador XrTrackableImageDatabaseANDROID a ser adicionado aotracker.
Quando um XrTrackableImageDatabaseANDROID é adicionado a um rastreador, as imagens de referência desse banco de dados precisam ser consideradas para detecção e rastreamento, além de outros bancos de dados adicionados anteriormente com xrAddTrackableImageDatabaseANDROID ou pela estrutura XrTrackableImageConfigurationANDROID ao criar o rastreador.
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de chamar xrAddTrackableImageDatabaseANDROID. -
trackerprecisa ser um identificador XrTrackableTrackerANDROID válido -
databaseprecisa ser um identificador XrTrackableImageDatabaseANDROID válido. -
databaseetrackerprecisam ter sido criados, alocados ou recuperados da mesma XrSession.
Códigos de retorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
A função xrRemoveTrackableImageDatabaseANDROID é definida como:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
Descrições dos parâmetros
trackeré o identificador XrTrackableTrackerANDROID de onde odatabaseserá removido.databaseé o identificador XrTrackableImageDatabaseANDROID a ser removido dotracker.
Quando um XrTrackableImageDatabaseANDROID é removido de um XrTrackableTrackerANDROID , as estruturas XrTrackableImageDatabaseEntryANDROID desse banco de dados não devem mais ser consideradas para detecção e rastreamento. Todas as entradas ativas desse banco de dados não podem mais ser informadas. O identificador XrTrackableImageDatabaseANDROID removido não pode ser destruído implicitamente como parte dessa operação.
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de chamar xrRemoveTrackableImageDatabaseANDROID. -
trackerprecisa ser um identificador XrTrackableTrackerANDROID válido -
databaseprecisa ser um identificador XrTrackableImageDatabaseANDROID válido. -
databaseetrackerprecisam ter sido criados, alocados ou recuperados da mesma XrSession.
Códigos de retorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
Como receber imagens
A função xrGetTrackableImageANDROID é definida como:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
Descrições dos parâmetros
trackeré o XrTrackableTrackerANDROID a ser consultado.getInfoé o XrTrackableGetInfoANDROID com as informações usadas para receber o QR code rastreável.trackableé um ponteiro para a estrutura XrTrackableImageANDROID em que a imagem rastreável é retornada.
O tempo de execução precisa retornar XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID se o tipo rastreável do XrTrackableANDROID não for XR_TRACKABLE_TYPE_IMAGE_ANDROID ou se o tipo rastreável do XrTrackableTrackerANDROID não for XR_TRACKABLE_TYPE_IMAGE_ANDROID .
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de chamar xrGetTrackableImageANDROID. -
trackerprecisa ser um identificador XrTrackableTrackerANDROID válido -
getInfoprecisa ser um ponteiro para uma estrutura XrTrackableGetInfoANDROID válida. -
trackableprecisa ser um ponteiro para uma estrutura XrTrackableImageANDROID
Códigos de retorno
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_ERROR_VALIDATION_FAILURE
A estrutura XrTrackableImageANDROID é definida como:
typedef struct XrTrackableImageANDROID {
XrStructureType type;
const void* next;
XrTrackingStateANDROID trackingState;
XrTime lastUpdatedTime;
XrTrackableImageDatabaseANDROID database;
uint32_t databaseEntryIndex;
XrPosef centerPose;
XrExtent2Df extents;
} XrTrackableImageANDROID;
Descrições de membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.trackingStateé o XrTrackingStateANDROID da imagem.lastUpdatedTimeé oXrTimeda última atualização da imagem.databaseé o identificador XrTrackableImageDatabaseANDROID de onde essa imagem foi rastreada.databaseEntryIndexé o índice que mapeia a matriz XrTrackableImageDatabaseCreateInfoANDROID ::entriesdedatabase.centerPoseé o XrPosef da imagem localizada em XrTrackableGetInfoANDROID ::baseSpace. A imagem fica no plano XZ, com X apontando para a direita e Z para a parte de baixo.extentssão as dimensões XrExtent2Df da imagem. O limite da caixa delimitadora está nos pontos:centerPose+/- (extents/ 2).
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de usar XrTrackableImageANDROID. -
typeprecisa serXR_TYPE_TRACKABLE_IMAGE_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas -
trackingStateprecisa ser um valor XrTrackingStateANDROID válido -
databaseprecisa ser um identificador XrTrackableImageDatabaseANDROID válido.
Gerenciamento de falhas
O aplicativo precisa fazer uma pesquisa do evento XrEventDataImageTrackingLostANDROID usando xrPollEvent e não pode ignorá-lo.
A estrutura XrEventDataImageTrackingLostANDROID é definida como:
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
Descrições de membros
typeé o XrStructureType dessa estrutura.nextéNULLou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas está definida no OpenXR principal ou nesta extensão.timeXrTime
Receber o evento XrEventDataImageTrackingLostANDROID indica que o rastreamento de imagem sofreu uma falha interna, invalidando os recursos atuais. O aplicativo precisa destruir todos os manipuladores XrTrackableImageDatabaseANDROID e recriá-los se quiser continuar o rastreamento de imagens. O aplicativo também precisa destruir todos os identificadores XrTrackableTrackerANDROID relacionados ao rastreamento de imagens e recriá-los se quiser continuar rastreando imagens.
Uso válido (implícito)
- A extensão
XR_ANDROID_trackables_imageprecisa ser ativada antes de usar XrEventDataImageTrackingLostANDROID. -
typeprecisa serXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID -
nextprecisa serNULLou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas
Exemplo de código para receber imagens rastreáveis
O exemplo de código a seguir demonstra como receber imagens rastreáveis.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
XrSystemId systemId; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties; // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace; // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.
// Inspect system capability
XrSystemImageTrackingPropertiesANDROID imageProperty {
.type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
.next = nullptr,
};
XrSystemProperties systemProperties {
.type = XR_TYPE_SYSTEM_PROPERTIES,
.next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
// image tracking is not supported.
return;
}
uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
{
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
.next = nullptr,
.trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
.physicalWidth = 0.1f, // The width of the image in meters.
.imageWidth = 640,
.imageHeight = 480,
.format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
.bufferSize = imageBufferSize, // RGBA buffer size in bytes.
.buffer = imageBuffer, // RGBA data.
}
};
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
futureReady = true;
keepLooping = false;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrTrackableImageDatabaseANDROID imageDatabase;
if (futureReady) {
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
}
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.
// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
while (1) {
uint32_t trackableCountOutput = 0;
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));
std::vector<XrTrackableANDROID> allImageTrackables;
allImageTrackables.resize(trackableCountOutput);
CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));
for (XrTrackableANDROID trackable : allImageTrackables) {
XrTrackableGetInfoANDROID imageGetInfo {
.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
.next = nullptr,
.trackable = trackable,
.baseSpace = appSpace,
.time = updateTime
};
XrTrackableImageANDROID trackableImage{
.type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
};
CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));
// Use XrTrackableImageANDROID data.
(void)trackableImage.trackingState;
(void)trackableImage.lastUpdatedTime;
(void)trackableImage.centerPose;
(void)trackableImage.extents;
if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
// Knowing which image the index of 0 maps to, use the specific image database
// entry (e.g. rendering A for image A).
}
// indices 1+N comparisons for another specific image database entry.
}
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
Exemplo de código para gerenciar bancos de dados de imagens durante a execução
O exemplo de código a seguir demonstra como modificar o conjunto de imagens rastreadas.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID; // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID; // Previously initialized.
// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.
// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 2,
.databases = imageDatabases
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));
// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));
// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.
// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &anotherImageDatabase
};
XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &anotherImageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));
// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.
Exemplo de código para reagir a falhas no rastreamento de imagens
O exemplo de código a seguir demonstra como processar falhas fazendo polling do evento XrEventDataImageTrackingLostANDROID.
XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.
// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT; // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID; // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID; // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID; // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID; // Previously initialized.
XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.
// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
.type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
switch (event.type) {
case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
const XrEventDataImageTrackingLostANDROID& eventdata =
*reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);
// All existing databases and trackers need to be destroyed.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));
// To resume image tracking, the database(s) and the tracker need to be re-created.
XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
.type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
.next = nullptr,
.entryCount = 1,
.entries = imageDatabaseEntries
};
XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));
while (true) {
XrFuturePollInfoEXT pollInfo{
.type = XR_TYPE_FUTURE_POLL_INFO_EXT,
.future = imageDatabaseFuture,
};
XrFuturePollResultEXT pollResult{
.type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
};
CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
break;
} else {
// Throttle the loop to not fully expend this CPU core.
std::this_thread::yield();
}
}
XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
.type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
.next = nullptr,
};
CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
CHK_XR(imageDatabaseCompletion.futureResult);
imageDatabase = imageDatabaseCompletion.database;
XrTrackableImageConfigurationANDROID imageConfig {
.type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
.next = nullptr,
.databaseCount = 1,
.databases = &imageDatabase
};
XrTrackableTrackerCreateInfoANDROID createInfo {
.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
.next = &imageConfig,
.trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};
XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));
break;
}
}
}
Novos tipos de objeto
Novos comandos
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
Novas estruturas
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
Estendendo XrSystemProperties :
Novos tipos enumerados
Novas constantes de tipo enumerado
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_ANDROID_trackables_image_SPEC_VERSIONExtensão de XrObjectType :
XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
Extensão de XrResult :
XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
Extensão de XrStructureType :
XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
Estendendo XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
Problemas
Histórico de versões
Revisão 1, 08/04/2025 (Daniel Guttenberg)
- Descrição inicial da extensão.