Estensione OpenXR XR_ANDROID_trackables_qr_code

Stringa del nome

XR_ANDROID_trackables_qr_code

Tipo di estensione

Estensione dell'istanza

Numero di interno registrato

460

Revisione

1

Dipendenze da estensioni e versioni

XR_ANDROID_trackables

Data ultima modifica

2025-02-05

Stato IP

Nessuna rivendicazione di proprietà intellettuale 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.

Ispezionare la funzionalità del sistema

XrSystemQrCodeTrackingPropertiesANDROID

La struttura XrSystemQrCodeTrackingPropertiesANDROID è definita come segue:

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Non sono definite strutture di questo tipo 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 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 tracciare 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 del codice QR se e solo se supportsQrCodeTracking è XR_FALSE.

Se un runtime supporta il monitoraggio dei codici QR, deve supportare maxQrCodeCount codici QR monitorati in qualsiasi momento.

Se un runtime supporta la stima delle dimensioni del codice QR, l'applicazione può impostare XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 su per indicare l'utilizzo della stima delle dimensioni. In caso contrario, l'applicazione deve impostare XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize su un valore positivo o verrà restituito XR_ERROR_VALIDATION_FAILURE.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_trackables_qr_code deve essere attivata prima di utilizzare XrSystemQrCodeTrackingPropertiesANDROID
  • type deve essere XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture

Monitorare i codici QR

Questa estensione aggiunge XR_TRACKABLE_TYPE_QR_CODE_ANDROID a XrTrackableTypeANDROID.

L'applicazione potrebbe creare un XrTrackableTrackerANDROID chiamando xrCreateTrackableTrackerANDROID e specificando XR_TRACKABLE_TYPE_QR_CODE_ANDROID come tipo 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.

XrTrackableQrCodeConfigurationANDROID

La struttura XrTrackableQrCodeConfigurationANDROID è definita come segue:

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

Descrizioni dei membri

  • type è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Non sono definite strutture di questo tipo 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 è zero, le dimensioni del codice QR verranno stimate 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 potrebbe impostare XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize su 0 per indicare l'utilizzo della stima delle dimensioni. In caso contrario, l'applicazione deve impostare XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize su un valore positivo o verrà restituito XR_ERROR_VALIDATION_FAILURE.

Il filtro must runtime deve filtrare l'output da xrGetAllTrackablesANDROID per corrispondere a trackingMode e qrCodeEdgeSize.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_trackables_qr_code deve essere attivata prima di utilizzare XrTrackableQrCodeConfigurationANDROID
  • type deve essere XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
  • trackingMode deve essere un valore XrQrCodeTrackingModeANDROID valido

XrQrCodeTrackingModeANDROID

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

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 | Il codice QR è dinamico e potrebbe spostarsi. |

Visualizzare i codici QR

xrGetTrackableQrCodeANDROID

La funzione xrGetTrackableQrCodeANDROID è definita come segue:

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

Descrizioni dei parametri

  • tracker è il XrTrackableTrackerANDROID da interrogare.
  • getInfo è il XrTrackableGetInfoANDROID con le informazioni utilizzate per ottenere il codice QR tracciabile.
  • qrCodeOutput è un puntatore alla struttura XrTrackableQrCodeANDROID in cui viene restituito il codice QR tracciabile.

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)

  • L'estensione XR_ANDROID_trackables_qr_code deve essere attivata prima di chiamare xrGetTrackableQrCodeANDROID
  • tracker deve essere un handle XrTrackableTrackerANDROID valido
  • getInfo deve essere un puntatore a una struttura XrTrackableGetInfoANDROID valida
  • qrCodeOutput deve essere un puntatore a una struttura XrTrackableQrCodeANDROID

XrTrackableQrCodeANDROID

La struttura XrTrackableQrCodeANDROID è definita come segue:

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 è il XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Non sono definite strutture di questo tipo in OpenXR di base o in questa estensione.
  • trackingState è il XrTrackingStateANDROID del codice QR.
  • lastUpdatedTime è la XrTime dell'ultimo aggiornamento del codice QR.
  • centerPose è il 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 e Z che punta verso il basso.
  • 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à le dimensioni del buffer richieste in bufferCountOutput. In caso contrario, contiene il totale degli elementi scritti in buffer.
  • buffer è un puntatore a un array di char per scrivere i dati del codice QR decodificato. L'applicazione può passare un nullptr per determinare la dimensione del buffer richiesta o se non richiede la decodifica dei dati del codice QR. I dati del codice QR vengono restituiti come stringa UTF-8 con terminazione null.
  • Consulta la sezione Parametri delle dimensioni del buffer per una descrizione dettagliata del recupero delle dimensioni buffer richieste.

Utilizzo valido (implicito)

  • L'estensione XR_ANDROID_trackables_qr_code deve essere attivata prima di utilizzare XrTrackableQrCodeANDROID
  • type deve essere XR_TYPE_TRACKABLE_QR_CODE_ANDROID
  • next deve essere NULL o un puntatore valido alla struttura successiva in una catena di strutture
  • trackingState deve essere un valore XrTrackingStateANDROID valido
  • Se bufferCapacityInput non è 0, buffer deve essere un puntatore a un array di valori char bufferCapacityInput

Codice di esempio per ottenere codici QR monitorabili

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

Nuove costanti enum

L'enumerazione XrStructureType viene estesa con:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

L'enumerazione XrTrackableTypeANDROID viene estesa con:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Nuovi enum

  • XrQrCodeTrackingModeANDROID

Nuove strutture

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Nuove funzioni

  • xrGetTrackableQrCodeANDROID

Problemi

Cronologia delle versioni

  • Revisione 1, 05/02/2025 (Levana Chen)
    • Descrizione iniziale dell'estensione.

OpenXR™ e il logo OpenXR sono marchi di proprietà di The Khronos Group Inc. e sono registrati come marchi in Cina, nell'Unione Europea, in Giappone e nel Regno Unito.