XR_ANDROID_trackables_qr_code

String de nome

XR_ANDROID_trackables_qr_code

Tipo de extensão

Extensão de instância

Número de ramal registrado

709

Revisão

1

Status de ratificação

Não ratificado

Dependências de extensão e versão

XR_ANDROID_trackables

Estado de descontinuação

  • Descontinuado pela extensão XR_EXT_spatial_marker_tracking

Data da última modificação

2025-02-05

Status do IP

Nenhuma reivindicação de PI conhecida.

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 de QR codes físicos e a decodificação de dados de QR codes.

Permissões

Os apps Android precisam ter a permissão android.permission.SCENE_UNDERSTANDING_COARSE listada no manifesto, já que essa extensão depende de 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 XrSystemQrCodeTrackingPropertiesANDROID é definida como:

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

Descrições dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • supportsQrCodeTracking é um XrBool32 que indica se o sistema atual oferece o recurso de rastreamento de QR code.
  • supportsQrCodeSizeEstimation é um XrBool32 que indica se o sistema atual fornece uma 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 verificar se o sistema é capaz de rastrear QR codes estendendo o XrSystemProperties com a estrutura XrSystemQrCodeTrackingPropertiesANDROID ao chamar xrGetSystemProperties . O ambiente de execução precisa retornar XR_ERROR_FEATURE_UNSUPPORTED para a criação do rastreador 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 code, maxQrCodeCount precisa ser pelo menos 1. Se um ambiente de execução não for compatível com o rastreamento de QR code, maxQrCodeCount precisa ser 0.

Uso válido (implícito)

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 QR codes.

O ambiente 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 .

A estrutura XrTrackableQrCodeConfigurationANDROID é definida como:

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

Descrições dos membros

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

O aplicativo precisa definir uma configuração válida adicionando um XrTrackableQrCodeConfigurationANDROID à próxima cadeia de XrTrackableTrackerCreateInfoANDROID . Caso contrário, o ambiente 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.0 para indicar o uso da estimativa de tamanho.

Se o ambiente de execução não oferecer suporte à estimativa de tamanho do QR code, o aplicativo precisará definir XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize como um valor positivo. Caso contrário, o ambiente de execução precisará retornar XR_ERROR_VALIDATION_FAILURE.

O ambiente de execução precisa filtrar a saída de xrGetAllTrackablesANDROID para corresponder ao trackingMode . Se XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize não estiver definido como 0.0, o ambiente de execução precisa retornar apenas QR codes que correspondam a esse tamanho. Se XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize estiver definido como 0.0, o ambiente de execução precisará retornar todos os QR codes com o tamanho estimado.

Uso válido (implícito)

O tipo enumerado XrQrCodeTrackingModeANDROID descreve os modos de rastreamento de QR codes disponíveis.

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

Descrições de enumerantes

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID: rastreamento de QR codes dinâmicos. Esse modo tem a maior precisão e funciona em QR codes estáticos e em movimento, mas também tem o maior consumo de energia.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID: rastreamento de QR codes estáticos. Esse modo é útil principalmente para QR codes que são estáticos, o que leva a um menor consumo de energia em comparação com o modo dinâmico.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM: esse modo deve ser usado para QR codes estáticos. Ao contrário do modo estático, esse modo rastreia o QR code apenas uma vez e atualiza as posições das instâncias rastreadas com base apenas na posição do dispositivo. Como resultado, o rastreamento continua mesmo que o QR code saia da visualização do frame de referência. Isso leva a um consumo mínimo de energia depois que o QR code é rastreado. (Adicionado pela extensão XR_QCOM_trackables_qr_code_operations)

Gerar QR codes

A função xrGetTrackableQrCodeANDROID é definida como:

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

Descrições dos parâmetros

O ambiente 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)

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_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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 dos membros

  • type é o XrStructureType dessa estrutura.
  • next é NULL ou um ponteiro para a próxima estrutura em uma cadeia de estruturas. Nenhuma estrutura desse tipo é definida no OpenXR principal ou nesta extensão.
  • trackingState é o XrTrackingStateANDROID do QR code.
  • lastUpdatedTime é o XrTime da última atualização do QR code. Se lastUpdatedTime for alterado desde a última chamada, todos os outros campos podem ter sido alterados.
  • 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, Z apontando para a parte de baixo e Y saindo do QR code como o normal.
  • 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 bufferCapacityInput for 0 , o ambiente 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 . Se os dados do QR code ainda não tiverem sido decodificados, o ambiente de execução precisará definir bufferCountOutput como 0.
  • buffer é um ponteiro para uma matriz de char para gravar os dados do QR code decodificado. Se o aplicativo não se importar com os dados do QR code decodificado, ele poderá transmitir nullptr e omitir a segunda chamada de duas chamadas. 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 de buffer necessário.

Uso válido (implícito)

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, {
  .type = XR_TYPE_TRACKABLE_QR_CODE_ANDROID,
  .next = nullptr,
  .bufferCountOutput = 0,
});
uint32_t qrCodeSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(qrCodeTracker, qrCodeProperty.maxQrCodeCount, &qrCodeSize,
                                 trackables.data()));
for (int i = 0; i < qrCodeSize; i++) {
    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));

Novos comandos

Novas estruturas

Novos tipos enumerados

Novas constantes de tipo enumerado

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • Estendendo XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • Estendendo XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Problemas

Histórico de versões

  • Revisão 1, 05/02/2025 (Levana Chen)

    • Descrição inicial da extensão.