XR_ANDROID_trackables_qr_code

String Nama

XR_ANDROID_trackables_qr_code

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

709

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

XR_ANDROID_trackables

Status Penghentian Penggunaan

  • Tidak digunakan lagi oleh ekstensi XR_EXT_spatial_marker_tracking

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.

Izin

Aplikasi Android harus mencantumkan izin android.permission.SCENE_UNDERSTANDING_COARSE dalam manifesnya karena ekstensi ini bergantung pada XR_ANDROID_trackables dan mengekspos geometri lingkungan. Izin android.permission.SCENE_UNDERSTANDING_COARSE dianggap sebagai izin berbahaya.

(tingkat perlindungan: berbahaya)

Memeriksa kemampuan sistem

Struktur XrSystemQrCodeTrackingPropertiesANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari 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 runtime mendukung pelacakan kode QR, maxQrCodeCount harus minimal 1. Jika runtime tidak mendukung pelacakan kode QR, maxQrCodeCount harus 0.

Penggunaan yang Valid (Implisit)

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 objek 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 .

Struktur XrTrackableQrCodeConfigurationANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari 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, runtime memperkirakan ukuran kode QR secara online.

Aplikasi harus menyetel 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.0 untuk menunjukkan penggunaan estimasi ukuran.

Jika runtime tidak mendukung estimasi ukuran kode QR, aplikasi harus menetapkan XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize ke nilai positif, atau runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE .

Runtime harus memfilter output dari xrGetAllTrackablesANDROID agar cocok dengan trackingMode . Jika XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize tidak disetel ke 0.0, runtime hanya boleh menampilkan kode QR yang cocok dengan ukuran ini. Jika XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize disetel ke 0.0, runtime harus menampilkan semua kode QR dengan perkiraan ukuran.

Penggunaan yang Valid (Implisit)

Enum XrQrCodeTrackingModeANDROID menjelaskan mode pelacakan kode QR yang didukung.

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;

Deskripsi Enumeran

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID — Melacak kode QR dinamis. Mode ini memiliki akurasi tertinggi dan berfungsi pada kode QR bergerak dan statis, tetapi juga memiliki konsumsi daya tertinggi.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID — Melacak kode QR statis. Mode ini terutama berguna untuk kode QR yang diketahui bersifat statis, sehingga menghasilkan konsumsi daya yang lebih rendah dibandingkan dengan mode dinamis.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM — Mode ini harus digunakan untuk kode QR statis. Berbeda dengan mode statis, mode ini hanya akan melacak kode QR satu kali, lalu memperbarui posisi instance yang dilacak hanya berdasarkan posisi perangkat. Akibatnya, pelacakan akan terus berlanjut meskipun kode QR tidak terlihat oleh frame referensi. Hal ini menyebabkan konsumsi daya minimal setelah kode QR dilacak. (Ditambahkan oleh ekstensi XR_QCOM_trackables_qr_code_operations)

Mendapatkan kode QR

Fungsi xrGetTrackableQrCodeANDROID ditentukan sebagai:

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

Deskripsi Parameter

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)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • 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

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 dari 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 dari pembaruan terakhir kode QR. Jika lastUpdatedTime berubah dari panggilan terakhir, semua kolom lainnya mungkin telah berubah.
  • centerPose adalah XrPosef kode QR yang terletak di XrTrackableGetInfoANDROID :: baseSpace . Kode QR terletak di bidang XZ dengan X mengarah ke kanan kode QR, Z mengarah ke bawahnya, dan Y keluar dari kode QR sebagai normal.
  • 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 . Jika data kode QR belum didekode, runtime harus menyetel bufferCountOutput ke 0.
  • buffer adalah pointer ke array char untuk menulis data kode QR yang didekode. Jika aplikasi tidak peduli dengan data kode QR yang didekode, aplikasi dapat meneruskan nullptr dan menghilangkan panggilan dua panggilan kedua. 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)

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, {
  .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));

Perintah Baru

Struktur Baru

Enum Baru

Konstanta Enum Baru

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • Memperluas XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • Memperluas XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Masalah

Riwayat Versi

  • Revisi 1, 05-02-2025 (Levana Chen)

    • Deskripsi ekstensi awal.