XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

709

Revisione

1

Stato della ratifica

Non ratificato

Dipendenze di estensioni e versioni

XR_ANDROID_trackables

Stato di ritiro

  • Ritirata dall'estensione XR_EXT_spatial_marker_tracking

Data ultima modifica

5/02/2025

Stato IP

Nessuna rivendicazione di PI nota.

Collaboratori

Christopher Doer, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Diego Tipaldi, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

Panoramica

Questa estensione consente il monitoraggio dei codici QR fisici e la decodifica dei dati dei codici QR.

Autorizzazioni

Le app per Android devono disporre dell'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE elencata nel loro manifest, in quanto questa estensione dipende da XR_ANDROID_trackables ed espone la geometria dell'ambiente. L'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE è considerata pericolosa.

(livello di protezione: pericoloso)

Ispeziona la funzionalità del sistema

La struttura XrSystemQrCodeTrackingPropertiesANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • supportsQrCodeTracking è un XrBool32 che indica se il sistema attuale fornisce la funzionalità di monitoraggio dei codici QR.
  • supportsQrCodeSizeEstimation è un valore XrBool32 che indica se il sistema attuale fornisce la stima delle dimensioni del codice QR.
  • maxQrCodeCount è il numero massimo totale di codici QR che possono essere monitorati contemporaneamente.

Un'applicazione può verificare se il sistema è in grado di monitorare i codici QR estendendo XrSystemProperties con la struttura XrSystemQrCodeTrackingPropertiesANDROID quando chiama xrGetSystemProperties . Il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED per la creazione del tracker dei codici QR se e solo se supportsQrCodeTracking è XR_FALSE .

Se un runtime supporta il monitoraggio dei codici QR, maxQrCodeCount deve essere almeno 1. Se un runtime non supporta il monitoraggio dei codici QR, maxQrCodeCount deve essere 0.

Utilizzo valido (implicito)

Monitoraggio dei codici QR

Questa estensione aggiunge XR_TRACKABLE_TYPE_QR_CODE_ANDROID a XrTrackableTypeANDROID .

L'applicazione può creare un XrTrackableTrackerANDROID chiamando xrCreateTrackableTrackerANDROID e specificando XR_TRACKABLE_TYPE_QR_CODE_ANDROID come tipo di elemento tracciabile in XrTrackableTrackerCreateInfoANDROID :: trackableType per monitorare i codici QR.

Il runtime deve restituire XR_ERROR_FEATURE_UNSUPPORTED se XrTrackableTrackerCreateInfoANDROID :: trackableType è XR_TRACKABLE_TYPE_QR_CODE_ANDROID e XrSystemQrCodeTrackingPropertiesANDROID :: supportsQrCodeTracking restituisce XR_FALSE tramite xrGetSystemProperties .

La struttura XrTrackableQrCodeConfigurationANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • trackingMode è un XrQrCodeTrackingModeANDROID che indica la modalità di monitoraggio desiderata.
  • qrCodeEdgeSize indica la dimensione del bordo del codice QR in metri. Se è pari a zero, il runtime stima le dimensioni del codice QR online.

L'applicazione deve impostare una configurazione valida aggiungendo un XrTrackableQrCodeConfigurationANDROID alla catena successiva di XrTrackableTrackerCreateInfoANDROID . In caso contrario, il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Se il runtime supporta la stima delle dimensioni del codice QR, l'applicazione può impostare XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize su 0.0 per indicare l'utilizzo della stima delle dimensioni.

Se il runtime non supporta la stima delle dimensioni del codice QR, l'applicazione deve impostare XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize su un valore positivo, altrimenti il runtime deve restituire XR_ERROR_VALIDATION_FAILURE .

Il runtime deve filtrare l'output di xrGetAllTrackablesANDROID in modo che corrisponda a trackingMode . Se XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize non è impostato su 0.0, il runtime deve restituire solo i codici QR corrispondenti a questa dimensione. Se XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize è impostato su 0.0, il runtime deve restituire tutti i codici QR con le dimensioni stimate.

Utilizzo valido (implicito)

L'enum XrQrCodeTrackingModeANDROID descrive le modalità di monitoraggio supportate dei codici QR.

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;

Descrizioni degli enumeranti

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID: monitoraggio dei codici QR dinamici. Questa modalità offre la massima precisione e funziona con codici QR in movimento e statici, ma ha anche il consumo energetico più elevato.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID: monitoraggio dei codici QR statici. Questa modalità è utile principalmente per i codici QR che sono noti per essere statici, il che comporta un consumo energetico inferiore rispetto alla modalità dinamica.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM: questa modalità deve essere utilizzata per i codici QR statici. A differenza della modalità statica, questa modalità monitora il codice QR una sola volta e poi aggiorna le posizioni delle istanze monitorate esclusivamente in base alla posizione del dispositivo. Di conseguenza, il monitoraggio continua anche se il codice QR non è più visibile nel frame di riferimento. Ciò comporta un consumo energetico minimo una volta monitorato il codice QR. (Aggiunto dall'estensione XR_QCOM_trackables_qr_code_operations)

Genera codici QR

La funzione xrGetTrackableQrCodeANDROID è definita come segue:

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

Descrizioni dei parametri

Il runtime deve restituire XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID se il tipo tracciabile di XrTrackableANDROID non è XR_TRACKABLE_TYPE_QR_CODE_ANDROID o se il tipo tracciabile di XrTrackableTrackerANDROID non è XR_TRACKABLE_TYPE_QR_CODE_ANDROID .

Utilizzo valido (implicito)

Codici di risposta

Operazione riuscita

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Errore

  • 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

La struttura XrTrackableQrCodeANDROID è definita come:

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

Descrizioni dei membri

  • type è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna struttura di questo tipo è definita in OpenXR di base o in questa estensione.
  • trackingState è l'XrTrackingStateANDROID del codice QR.
  • lastUpdatedTime è la XrTime dell'ultimo aggiornamento del codice QR. Se lastUpdatedTime è cambiato rispetto all'ultima chiamata, tutti gli altri campi potrebbero essere cambiati.
  • centerPose è l'XrPosef del codice QR che si trova in XrTrackableGetInfoANDROID :: baseSpace . Il codice QR si trova nel piano XZ con X che punta a destra del codice QR, Z che punta alla sua parte inferiore e Y che esce dal codice QR come normale.
  • extents sono le dimensioni XrExtent2Df del codice QR. Il confine del riquadro di delimitazione si trova nei punti: centerPose +/- ( extents / 2).
  • bufferCapacityInput è la funzionalità di buffer o 0 per recuperare la funzionalità richiesta.
  • bufferCountOutput Se bufferCapacityInput è 0 , il runtime scriverà la dimensione del buffer richiesta in bufferCountOutput . In caso contrario, contiene gli elementi totali scritti in buffer . Se i dati del codice QR non sono ancora stati decodificati, il runtime deve impostare bufferCountOutput su 0.
  • buffer è un puntatore a un array di char per scrivere i dati del codice QR decodificato. Se l'applicazione non è interessata ai dati del codice QR decodificato, può passare nullptr e omettere la seconda chiamata. I dati del codice QR vengono restituiti come stringa UTF-8 con terminazione null.
  • Consulta la sezione Parametri della dimensione del buffer per una descrizione dettagliata del recupero della dimensione buffer richiesta.

Utilizzo valido (implicito)

Codice di esempio per ottenere codici QR tracciabili

Il seguente codice di esempio mostra come ottenere codici QR tracciabili.

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));

Nuovi comandi

Nuove strutture

Nuovi enum

Nuove costanti enum

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • Estensione di XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • Estensione di XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Problemi

Cronologia delle versioni

  • Revisione 1, 05/02/2025 (Levana Chen)

    • Descrizione iniziale dell'estensione.