Extensão XR_ANDROID_trackables_qr_code OpenXR

String de nome

XR_ANDROID_trackables_qr_code

Tipo de extensão

Extensão da instância

Número de ramal registrado

460

Revisão

1

Dependências de extensão e versão

XR_ANDROID_trackables

Data da última modificação

2025-02-05

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

Ken Mackay, Google

Daniel Guttenberg, Qualcomm

Visão geral

Essa extensão permite o rastreamento físico e a decodificação de dados de QR code.

Inspecionar a capacidade do sistema

XrSystemQrCodeTrackingPropertiesANDROID

A estrutura XrSystemQrCodeTrackingPropertiesANDROID é definida como:

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint32_t           maxQrCodeCount;
} XrSystemQrCodeTrackingPropertiesANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no OpenXR principal ou nesta extensão.
  • supportsQrCodeTracking é um XrBool32 que indica se o sistema atual oferece a capacidade de rastreamento de QR code.
  • supportsQrCodeSizeEstimation é um XrBool32 que indica se o sistema atual oferece estimativa de tamanho do QR code.
  • maxQrCodeCount é o número máximo total de QR Codes que podem ser rastreados ao mesmo tempo.

Um aplicativo pode inspecionar se o sistema é capaz de rastrear códigos QR estendendo o XrSystemProperties com a estrutura XrSystemQrCodeTrackingPropertiesANDROID ao chamar xrGetSystemProperties. O tempo de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED para a criação de rastreadores de QR code se e somente se supportsQrCodeTracking for XR_FALSE.

Se um ambiente de execução for compatível com o rastreamento de QR codes, ele precisa ser compatível com maxQrCodeCount QR codes rastreados a qualquer momento.

Se um ambiente de execução for compatível com a estimativa de tamanho do QR code, o aplicativo poderá definir XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 para indicar o uso da estimativa de tamanho. Caso contrário, o aplicativo precisa definir XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize como um valor positivo ou XR_ERROR_VALIDATION_FAILURE será retornado.

Uso válido (implícito)

  • A extensão XR_ANDROID_trackables_qr_code precisa ser ativada antes de usar XrSystemQrCodeTrackingPropertiesANDROID
  • type precisa ser XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas.

Rastreamento de QR codes

Essa extensão adiciona XR_TRACKABLE_TYPE_QR_CODE_ANDROID a XrTrackableTypeANDROID.

O aplicativo pode criar um XrTrackableTrackerANDROID chamando xrCreateTrackableTrackerANDROID e especificando XR_TRACKABLE_TYPE_QR_CODE_ANDROID como o tipo rastreável em XrTrackableTrackerCreateInfoANDROID::trackableType para rastrear códigos QR.

O tempo de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED se XrTrackableTrackerCreateInfoANDROID::trackableType for XR_TRACKABLE_TYPE_QR_CODE_ANDROID e XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking retornar XR_FALSE via xrGetSystemProperties.

XrTrackableQrCodeConfigurationANDROID

A estrutura XrTrackableQrCodeConfigurationANDROID é definida como:

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType               type;
    const void*                   next;
    XrQrCodeTrackingModeANDROID   trackingMode;
    float                         qrCodeEdgeSize;
} XrTrackableQrCodeConfigurationANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no OpenXR principal ou nesta extensão.
  • trackingMode é um XrQrCodeTrackingModeANDROID que indica o modo de acompanhamento desejado.
  • qrCodeEdgeSize indica o tamanho da borda do QR code em metros. Se for zero, o tamanho do QR code será estimado on-line.

O aplicativo precisa definir uma configuração válida adicionando um XrTrackableQrCodeConfigurationANDROID à próxima cadeia de XrTrackableTrackerCreateInfoANDROID. Caso contrário, o tempo de execução precisa retornar XR_ERROR_VALIDATION_FAILURE.

Se o ambiente de execução for compatível com a estimativa de tamanho do QR code, o aplicativo poderá definir XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize como 0 para indicar o uso da estimativa de tamanho. Caso contrário, o aplicativo precisa definir XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize como um valor positivo ou XR_ERROR_VALIDATION_FAILURE será retornado.

O tempo de execução precisa filtrar a saída de xrGetAllTrackablesANDROID para corresponder a trackingMode e qrCodeEdgeSize.

Uso válido (implícito)

  • A extensão XR_ANDROID_trackables_qr_code precisa ser ativada antes de usar XrTrackableQrCodeConfigurationANDROID
  • type precisa ser XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas.
  • trackingMode precisa ser um valor XrQrCodeTrackingModeANDROID válido

XrQrCodeTrackingModeANDROID

O enum XrQrCodeTrackingModeANDROID descreve os modos de rastreamento compatíveis de QR codes.

typedef enum XrQrCodeTrackingModeANDROID {
    XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID = 0,
    XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_QR_CODE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrQrCodeTrackingModeANDROID;

| Enum | Description XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | O QR code é dinâmico e pode se mover. |

Ver QR codes

xrGetTrackableQrCodeANDROID

A função xrGetTrackableQrCodeANDROID é definida como:

XrResult xrGetTrackableQrCodeANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableQrCodeANDROID*                   qrCodeOutput);

Descrições dos parâmetros

  • tracker é o XrTrackableTrackerANDROID a ser consultado.
  • getInfo é o XrTrackableGetInfoANDROID com as informações usadas para gerar o QR code rastreável.
  • qrCodeOutput é um ponteiro para a estrutura XrTrackableQrCodeANDROID em que o QR code rastreável é retornado.

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_QR_CODE_ANDROID ou se o tipo rastreável do XrTrackableTrackerANDROID não for XR_TRACKABLE_TYPE_QR_CODE_ANDROID.

Uso válido (implícito)

  • A extensão XR_ANDROID_trackables_qr_code precisa ser ativada antes de chamar xrGetTrackableQrCodeANDROID.
  • tracker precisa ser um identificador XrTrackableTrackerANDROID válido
  • getInfo precisa ser um ponteiro para uma estrutura XrTrackableGetInfoANDROID válida
  • qrCodeOutput precisa ser um ponteiro para uma estrutura XrTrackableQrCodeANDROID.

XrTrackableQrCodeANDROID

A estrutura XrTrackableQrCodeANDROID é definida como:

typedef struct XrTrackableQrCodeANDROID {
    XrStructureType           type;
    void*                     next;
    XrTrackingStateANDROID    trackingState;
    XrTime                    lastUpdatedTime;
    XrPosef                   centerPose;
    XrExtent2Df               extents;
    uint32_t                  bufferCapacityInput;
    uint32_t                  bufferCountOutput;
    char*                     buffer;
} XrTrackableQrCodeANDROID;

Descrições de membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma dessas estruturas é definida no OpenXR principal ou nesta extensão.
  • trackingState é o XrTrackingStateANDROID do QR code.
  • lastUpdatedTime é o XrTime da última atualização do QR code.
  • centerPose é o XrPosef do QR code localizado em XrTrackableGetInfoANDROID::baseSpace. O QR code fica no plano XZ, com X apontando para a direita do QR code e Z apontando para a parte de baixo.
  • extents são as dimensões XrExtent2Df do QR code. O limite da caixa delimitadora está nos pontos: centerPose +/- (extents / 2).
  • bufferCapacityInput é a capacidade do buffer ou 0 para recuperar a capacidade necessária.
  • bufferCountOutput Se o bufferCapacityInput for 0, o tempo de execução vai gravar o tamanho do buffer necessário em bufferCountOutput. Caso contrário, ele vai conter o total de elementos gravados em buffer.
  • buffer é um ponteiro para uma matriz de char para gravar os dados decodificados do QR code. O aplicativo pode transmitir um nullptr para determinar o tamanho do buffer necessário ou se não estiver solicitando os dados do QR code de decodificação. Os dados do QR code são retornados como uma string UTF-8 terminada em nulo.
  • Consulte a seção Parâmetros de tamanho do buffer para uma descrição detalhada de como recuperar o tamanho buffer necessário.

Uso válido (implícito)

  • A extensão XR_ANDROID_trackables_qr_code precisa ser ativada antes de usar XrTrackableQrCodeANDROID
  • type precisa ser XR_TYPE_TRACKABLE_QR_CODE_ANDROID
  • next precisa ser NULL ou um ponteiro válido para a próxima estrutura em uma cadeia de estruturas.
  • trackingState precisa ser um valor XrTrackingStateANDROID válido
  • Se bufferCapacityInput não for 0, buffer precisa ser um ponteiro para uma matriz de valores char bufferCapacityInput.

Exemplo de código para receber QR codes rastreáveis

O exemplo de código a seguir demonstra como receber QR Codes rastreáveis.

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

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // previously initialized
PFN_xrGetTrackableQrCodeANDROID xrGetTrackableQrCodeANDROID;           // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // 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
XrSystemQrCodeTrackingPropertiesANDROID qrCodeProperty =
        {.type = XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID, .next = nullptr};
XrSystemProperties systemProperties = {.type = XR_TYPE_SYSTEM_PROPERTIES,
                                       .next = &qrCodeProperty};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!qrCodeProperty.supportsQrCodeTracking) {
    // QR Code tracking is not supported.
    return;
}

// Create a trackable tracker for QR Code tracking.
// If the runtime does not support size estimation, configures QR Code edge size of 0.1m.
XrTrackableQrCodeConfigurationANDROID configuration =
        {.type = XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID,
         .next = nullptr,
         .trackingMode = XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID,
         .qrCodeEdgeSize = qrCodeProperty.supportsQrCodeSizeEstimation ? 0.0f : 0.1f};
XrTrackableTrackerCreateInfoANDROID createInfo =
        {.type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
         .next = &configuration,
         .trackableType = XR_TRACKABLE_TYPE_QR_CODE_ANDROID};
XrTrackableTrackerANDROID qrCodeTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &qrCodeTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get QR Codes.
std::vector<XrTrackableANDROID> trackables(qrCodeProperty.maxQrCodeCount);
std::vector<XrTrackableQrCodeANDROID> qrCodes(qrCodeProperty.maxQrCodeCount);
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    qrCodes[i].type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID;
    qrCodes[i].next = nullptr;
    qrCodes[i].bufferCountOutput = 0;
    XrTrackableGetInfoANDROID getInfo = {.type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
                                         .next = nullptr,
                                         .trackable = trackables.at(i),
                                         .baseSpace = appSpace,
                                         .time = updateTime};
    CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
    if (qrCodes[i].bufferCountOutput > 0) {
        // Allocate the buffer if it is not already allocated.
        if (qrCodes[i].bufferCapacityInput == 0) {
            qrCodes[i].buffer = new char[qrCodes[i].bufferCountOutput];
            qrCodes[i].bufferCapacityInput = qrCodes[i].bufferCountOutput;
            CHK_XR(xrGetTrackableQrCodeANDROID(qrCodeTracker, &getInfo, &qrCodes[i]));
        }
    }
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(qrCodeTracker));

Novas constantes de enumeração

A enumeração XrStructureType é estendida com:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

A enumeração XrTrackableTypeANDROID é estendida com:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Novos enums

  • XrQrCodeTrackingModeANDROID

Novas estruturas

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Novas funções

  • xrGetTrackableQrCodeANDROID

Problemas

Histórico de versões

  • Revisão 1, 05/02/2025 (Levana Chen)
    • Descrição inicial da extensão.

OpenXR™ e o logotipo OpenXR são marcas registradas de propriedade da Khronos Group Inc. e estão registradas como marcas comerciais na China, na União Europeia, no Japão e no Reino Unido.