Ekstensi OpenXR XR_ANDROID_trackables_qr_code

String Nama

XR_ANDROID_trackables_qr_code

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

460

Revisi

1

Dependensi Ekstensi dan Versi

XR_ANDROID_trackables

Tanggal Terakhir Diubah

2025-02-05

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

Christopher Doer, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Nihav Jain, Google

Diego Tipaldi, Google

Ken Mackay, Google

Daniel Guttenberg, Qualcomm

Ringkasan

Ekstensi ini memungkinkan pelacakan Kode QR fisik dan decoding data Kode QR.

Memeriksa kemampuan sistem

XrSystemQrCodeTrackingPropertiesANDROID

Struktur XrSystemQrCodeTrackingPropertiesANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • supportsQrCodeTracking adalah XrBool32 yang menunjukkan apakah sistem saat ini menyediakan kemampuan pelacakan Kode QR.
  • supportsQrCodeSizeEstimation adalah XrBool32 yang menunjukkan apakah sistem saat ini memberikan estimasi ukuran Kode QR.
  • maxQrCodeCount adalah jumlah maksimum total Kode QR yang dapat dilacak secara bersamaan.

Aplikasi dapat memeriksa apakah sistem mampu melakukan pelacakan Kode QR dengan memperluas XrSystemProperties dengan struktur XrSystemQrCodeTrackingPropertiesANDROID saat memanggil xrGetSystemProperties. Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED untuk pembuatan pelacak Kode QR jika dan hanya jika supportsQrCodeTracking adalah XR_FALSE.

Jika mendukung pelacakan Kode QR, runtime harus mendukung maxQrCodeCount Kode QR yang dilacak kapan saja.

Jika runtime mendukung estimasi ukuran Kode QR, aplikasi dapat menyetel XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 ke menunjukkan penggunaan estimasi ukuran. Jika tidak, aplikasi harus menetapkan XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize ke nilai positif atau XR_ERROR_VALIDATION_FAILURE akan ditampilkan.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_trackables_qr_code harus diaktifkan sebelum menggunakan XrSystemQrCodeTrackingPropertiesANDROID
  • type harus berupa XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur

Melacak Kode QR

Ekstensi ini menambahkan XR_TRACKABLE_TYPE_QR_CODE_ANDROID ke XrTrackableTypeANDROID.

Aplikasi dapat membuat XrTrackableTrackerANDROID dengan memanggil xrCreateTrackableTrackerANDROID dan menentukan XR_TRACKABLE_TYPE_QR_CODE_ANDROID sebagai jenis yang dapat dilacak di XrTrackableTrackerCreateInfoANDROID::trackableType untuk melacak kode QR.

Runtime harus menampilkan XR_ERROR_FEATURE_UNSUPPORTED jika XrTrackableTrackerCreateInfoANDROID::trackableType adalah XR_TRACKABLE_TYPE_QR_CODE_ANDROID dan XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking menampilkan XR_FALSE melalui xrGetSystemProperties.

XrTrackableQrCodeConfigurationANDROID

Struktur XrTrackableQrCodeConfigurationANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • trackingMode adalah XrQrCodeTrackingModeANDROID yang menunjukkan mode yang diinginkan untuk pelacakan.
  • qrCodeEdgeSize menunjukkan ukuran tepi Kode QR dalam meter. Jika nol, ukuran Kode QR akan diperkirakan secara online.

Aplikasi harus menetapkan konfigurasi yang valid dengan menambahkan XrTrackableQrCodeConfigurationANDROID ke rantai XrTrackableTrackerCreateInfoANDROID berikutnya. Jika tidak, runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE.

Jika runtime mendukung estimasi ukuran Kode QR, aplikasi dapat menyetel XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize ke 0 untuk menunjukkan penggunaan estimasi ukuran. Jika tidak, aplikasi harus menetapkan XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize ke nilai positif atau XR_ERROR_VALIDATION_FAILURE akan ditampilkan.

Filter runtime harus memfilter output dari xrGetAllTrackablesANDROID agar cocok dengan trackingMode dan qrCodeEdgeSize.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_trackables_qr_code harus diaktifkan sebelum menggunakan XrTrackableQrCodeConfigurationANDROID
  • type harus berupa XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
  • trackingMode harus berupa nilai XrQrCodeTrackingModeANDROID yang valid

XrQrCodeTrackingModeANDROID

Enum XrQrCodeTrackingModeANDROID menjelaskan mode pelacakan yang didukung Kode 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 | Deskripsi XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | Kode QR bersifat dinamis dan dapat berpindah. |

Mendapatkan Kode QR

xrGetTrackableQrCodeANDROID

Fungsi xrGetTrackableQrCodeANDROID ditentukan sebagai:

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

Deskripsi Parameter

  • tracker adalah XrTrackableTrackerANDROID yang akan dikueri.
  • getInfo adalah XrTrackableGetInfoANDROID dengan informasi yang digunakan untuk mendapatkan Kode QR yang dapat dilacak.
  • qrCodeOutput adalah pointer ke struktur XrTrackableQrCodeANDROID tempat Kode QR yang dapat dilacak ditampilkan.

Runtime harus menampilkan XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID jika jenis objek yang dapat dilacak dari XrTrackableANDROID bukan XR_TRACKABLE_TYPE_QR_CODE_ANDROID, atau jika jenis objek yang dapat dilacak dari XrTrackableTrackerANDROID bukan XR_TRACKABLE_TYPE_QR_CODE_ANDROID.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_trackables_qr_code harus diaktifkan sebelum memanggil xrGetTrackableQrCodeANDROID
  • tracker must harus berupa nama sebutan channel XrTrackableTrackerANDROID yang valid
  • getInfo harus berupa pointer ke struktur XrTrackableGetInfoANDROID yang valid
  • qrCodeOutput harus berupa pointer ke struktur XrTrackableQrCodeANDROID

XrTrackableQrCodeANDROID

Struktur XrTrackableQrCodeANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • trackingState adalah XrTrackingStateANDROID Kode QR.
  • lastUpdatedTime adalah XrTime update terakhir kode QR.
  • centerPose adalah XrPosef Kode QR yang terletak di XrTrackableGetInfoANDROID::baseSpace. Kode QR terletak di bidang XZ dengan X mengarah ke kanan kode QR dan Z mengarah ke bagian bawahnya.
  • extents adalah dimensi XrExtent2Df Kode QR. Batas kotak pembatas berada di titik: centerPose +/- (extents / 2).
  • bufferCapacityInput adalah kemampuan buffer, atau 0 untuk mengambil kemampuan yang diperlukan.
  • bufferCountOutput Jika bufferCapacityInput adalah 0, runtime akan menulis ukuran buffer yang diperlukan ke bufferCountOutput. Jika tidak, kolom ini berisi total elemen yang ditulis dalam buffer.
  • buffer adalah pointer ke array char untuk menulis data kode QR yang telah didekode. Aplikasi dapat meneruskan nullptr untuk menentukan ukuran buffer yang diperlukan atau jika tidak meminta data Kode QR yang didekode. Data Kode QR ditampilkan sebagai string UTF-8 yang diakhiri dengan null.
  • Lihat bagian Parameter Ukuran Buffer untuk mengetahui deskripsi mendetail tentang pengambilan ukuran buffer yang diperlukan.

Penggunaan yang Valid (Implisit)

  • Ekstensi XR_ANDROID_trackables_qr_code harus diaktifkan sebelum menggunakan XrTrackableQrCodeANDROID
  • type harus berupa XR_TYPE_TRACKABLE_QR_CODE_ANDROID
  • next harus berupa NULL atau pointer yang valid ke struktur berikutnya dalam rantai struktur
  • trackingState harus berupa nilai XrTrackingStateANDROID yang valid
  • Jika bufferCapacityInput bukan 0, buffer harus berupa pointer ke array nilai char bufferCapacityInput

Contoh kode untuk mendapatkan Kode QR yang dapat dilacak

Contoh kode berikut menunjukkan cara mendapatkan Kode QR yang dapat dilacak.

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

Konstanta Enum Baru

Enumerasi XrStructureType diperluas dengan:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

Enumerasi XrTrackableTypeANDROID diperluas dengan:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Enum Baru

  • XrQrCodeTrackingModeANDROID

Struktur Baru

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Fungsi Baru

  • xrGetTrackableQrCodeANDROID

Masalah

Histori Versi

  • Revisi 1, 05-02-2025 (Levana Chen)
    • Deskripsi ekstensi awal.

OpenXR™ dan logo OpenXR adalah merek dagang yang dimiliki oleh The Khronos Group Inc. dan terdaftar sebagai merek dagang di China, Uni Eropa, Jepang, dan Inggris Raya.