XR_ANDROID_trackables_qr_code

Stringa del nome

XR_ANDROID_trackables_qr_code

Tipo di estensione

Estensione dell'istanza

Numero di estensione registrato

709

Revisione

1

Stato di ratifica

Non ratificata

Dipendenze di estensione e versione

XR_ANDROID_trackables

Stato di ritiro

  • Obsoleta dall'estensione XR_EXT_spatial_marker_tracking

Data ultima modifica

5/02/2025

Stato IP

Nessuna rivendicazione IP 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 applicazioni Android devono disporre dell'autorizzazione android.permission.SCENE_UNDERSTANDING_COARSE elencata nel file 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)

Esaminare la funzionalità del sistema

La struttura XrSystemQrCodeTrackingPropertiesANDROID è definita come segue:

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 di queste strutture è definita in OpenXR core 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 dei codici 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 la struttura XrSystemProperties con 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)

Monitorare i 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 monitorabile 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 segue:

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 di queste strutture è definita in OpenXR core o in questa estensione.
  • trackingMode è un XrQrCodeTrackingModeANDROID che indica la modalità di monitoraggio desiderata.
  • qrCodeEdgeSize indica le dimensioni del bordo del codice QR in metri. Se è 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 dei codici 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 dei codici 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 che corrispondono a queste dimensioni. Se XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize è impostato su 0.0 , il runtime deve restituire tutti i codici QR con 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à ha la massima precisione e funziona su codici QR statici e in movimento, 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 in base alla posizione del dispositivo. Di conseguenza, il monitoraggio continua anche se il codice QR esce dal campo visivo del frame di riferimento. Ciò comporta un consumo energetico minimo una volta monitorato il codice QR. (Aggiunto dall'estensione XR_QCOM_trackables_qr_code_operations)

Ottenere i 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 di elemento monitorabile di XrTrackableANDROID non è XR_TRACKABLE_TYPE_QR_CODE_ANDROID o se il tipo di elemento monitorabile di XrTrackableTrackerANDROID non è XR_TRACKABLE_TYPE_QR_CODE_ANDROID .

Utilizzo valido (implicito)

Codici restituiti

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 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 è l'XrStructureType di questa struttura.
  • next è NULL o un puntatore alla struttura successiva in una catena di strutture. Nessuna di queste strutture è definita in OpenXR core o in questa estensione.
  • trackingState è lo XrTrackingStateANDROID del codice QR.
  • lastUpdatedTime è l'XrTime dell'ultimo aggiornamento del codice QR. Se lastUpdatedTime viene modificato dall'ultima chiamata, tutti gli altri campi potrebbero essere stati modificati.
  • 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 verso il basso e Y che esce dal codice QR come normale.
  • extents sono le dimensioni XrExtent2Df del codice QR. Il limite del riquadro di delimitazione si trova nei punti: centerPose +/- ( extents / 2).
  • bufferCapacityInput è la capacità di buffer o 0 per recuperare la capacità richiesta.
  • bufferCountOutput Se bufferCapacityInput è 0 , il runtime scriverà le dimensioni del buffer richieste in bufferCountOutput . In caso contrario, contiene il numero totale di elementi 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 decodificati. Se all'applicazione non interessano i dati del codice QR decodificati, può passare nullptr e omettere la seconda chiamata a due chiamate. I dati del codice QR vengono restituiti come stringa UTF-8 con terminazione null.
  • Per una descrizione dettagliata del recupero delle dimensioni buffer richieste, consulta la sezione Parametri delle dimensioni del buffer.

Utilizzo valido (implicito)

Esempio di codice per ottenere codici QR monitorabili

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

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, 5/02/2025 (Levana Chen)

    • Descrizione iniziale dell'estensione.