XR_ANDROID_trackables_qr_code OpenXR uzantısı

Name String

XR_ANDROID_trackables_qr_code

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

460

Düzeltme

1

Uzantı ve Sürüm Bağımlılıkları

XR_ANDROID_trackables

Son Değiştirilme Tarihi

2025-02-05

IP Durumu

Bilinen IP hak talebi yok.

Katkıda bulunanlar

Christopher Doer, Google

Levana Chen, Google

Jared Finder, Google

Spencer Quin, Google

Nihav Jain, Google

Diego Tipaldi, Google

Ken Mackay, Google

Daniel Guttenberg, Qualcomm

Genel Bakış

Bu uzantı, fiziksel QR kodu izlemeyi ve QR kodu verilerinin kodunu çözmeyi sağlar.

Sistem kapasitesini inceleme

XrSystemQrCodeTrackingPropertiesANDROID

XrSystemQrCodeTrackingPropertiesANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • supportsQrCodeTracking, mevcut sistemin QR kodu izleme özelliği sağlayıp sağlamadığını gösteren bir XrBool32'dir.
  • supportsQrCodeSizeEstimation, mevcut sistemin QR kodu boyut tahmini sağlayıp sağlamadığını belirten bir XrBool32'dir.
  • maxQrCodeCount, aynı anda izlenebilecek toplam maksimum QR kodu sayısıdır.

Bir uygulama, xrGetSystemProperties çağrılırken XrSystemProperties ile XrSystemQrCodeTrackingPropertiesANDROID yapısı genişletilerek sistemin QR kodu izlemeye uygun olup olmadığını inceleyebilir. Çalışma zamanı, supportsQrCodeTracking yalnızca XR_FALSE ise QR kodu izleyici oluşturma için döndürmelidir.XR_ERROR_FEATURE_UNSUPPORTED

Bir çalışma zamanı, QR kodu izlemeyi destekliyorsa herhangi bir zamanda izlenen QR kodlarını desteklemelidir.maxQrCodeCount

Bir çalışma zamanı QR kodu boyutu tahminini destekliyorsa uygulama, boyut tahmininin kullanımını belirtmek için XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 değerini ayarlayabilir. Aksi takdirde, uygulama XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize değerini pozitif bir değere ayarlamalıdır. Aksi takdirde XR_ERROR_VALIDATION_FAILURE döndürülür.

Geçerli Kullanım (Dolaylı)

  • XrSystemQrCodeTrackingPropertiesANDROID özelliğini kullanmadan önce XR_ANDROID_trackables_qr_code uzantısı etkinleştirilmelidir.
  • type XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID olmalıdır
  • next, NULL olmalı veya bir yapı zincirindeki sonraki yapıya yönelik geçerli bir işaretçi olmalıdır.

QR kodlarını izleme

Bu uzantı, XrTrackableTypeANDROID hizmetine XR_TRACKABLE_TYPE_QR_CODE_ANDROID özelliğini ekler.

Uygulama, QR kodlarını izlemek için XrTrackableTrackerANDROID oluşturabilir. Bunun için xrCreateTrackableTrackerANDROID çağrılır ve XrTrackableTrackerCreateInfoANDROID::trackableType içinde izlenebilir tür olarak XR_TRACKABLE_TYPE_QR_CODE_ANDROID belirtilir.

Çalışma zamanı, XrTrackableTrackerCreateInfoANDROID::trackableType değeri XR_TRACKABLE_TYPE_QR_CODE_ANDROID ise ve XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking değeri xrGetSystemProperties üzerinden XR_FALSE döndürüyorsa XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir.

XrTrackableQrCodeConfigurationANDROID

XrTrackableQrCodeConfigurationANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • trackingMode, izleme için istenen modu gösteren bir XrQrCodeTrackingModeANDROID'dir.
  • qrCodeEdgeSize, QR kodu kenarının metre cinsinden boyutunu gösterir. Sıfırsa QR kodu boyutu online olarak tahmin edilir.

Uygulama, XrTrackableTrackerCreateInfoANDROID zincirinin bir sonraki bölümüne XrTrackableQrCodeConfigurationANDROID ekleyerek geçerli bir yapılandırma ayarlamalıdır. Aksi takdirde, çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

Çalışma zamanı, QR kodu boyutu tahminini destekliyorsa uygulama, boyut tahmininin kullanımını belirtmek için değerini XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize olarak ayarlayabilir.0 Aksi takdirde, uygulama XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize değerini pozitif bir değere ayarlamalıdır. Aksi takdirde XR_ERROR_VALIDATION_FAILURE döndürülür.

Çalışma zamanı, xrGetAllTrackablesANDROID çıkışını trackingMode ve qrCodeEdgeSize ile eşleşecek şekilde filtrelemelidir.

Geçerli Kullanım (Dolaylı)

  • XrTrackableQrCodeConfigurationANDROID özelliğini kullanmadan önce XR_ANDROID_trackables_qr_code uzantısı etkinleştirilmelidir.
  • type XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID olmalıdır
  • next, NULL olmalı veya bir yapı zincirindeki sonraki yapıya yönelik geçerli bir işaretçi olmalıdır.
  • trackingMode geçerli bir XrQrCodeTrackingModeANDROID değeri olmalıdır.

XrQrCodeTrackingModeANDROID

XrQrCodeTrackingModeANDROID numaralandırması, QR kodlarının desteklenen izleme modlarını açıklar.

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 do not move.XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | QR kodu dinamiktir ve hareket edebilir. |

QR kodu alma

xrGetTrackableQrCodeANDROID

xrGetTrackableQrCodeANDROID işlevi şu şekilde tanımlanır:

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

Parametre Açıklamaları

  • tracker, sorgulanacak XrTrackableTrackerANDROID'dır.
  • getInfo, izlenebilir QR kodunu almak için kullanılan bilgileri içeren XrTrackableGetInfoANDROID'dir.
  • qrCodeOutput, izlenebilir QR kodunun döndürüldüğü XrTrackableQrCodeANDROID yapısına yönelik bir işaretçidir.

Çalışma zamanı, XrTrackableANDROID öğesinin izlenebilir türü XR_TRACKABLE_TYPE_QR_CODE_ANDROID değilse veya XrTrackableTrackerANDROID öğesinin izlenebilir türü XR_TRACKABLE_TYPE_QR_CODE_ANDROID değilse XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID değerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

  • XR_ANDROID_trackables_qr_code uzantısı, xrGetTrackableQrCodeANDROID aranmadan önce etkinleştirilmelidir.
  • tracker, geçerli bir XrTrackableTrackerANDROID herkese açık kullanıcı adı olmalıdır.
  • getInfo, geçerli bir XrTrackableGetInfoANDROID yapısının işaretçisi olmalıdır.
  • qrCodeOutput, XrTrackableQrCodeANDROID yapısına yönelik bir işaretçi olmalıdır.

XrTrackableQrCodeANDROID

XrTrackableQrCodeANDROID yapısı şu şekilde tanımlanır:

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

Üye Açıklamaları

  • type, bu yapının XrStructureType.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • trackingState, QR kodunun XrTrackingStateANDROID.
  • lastUpdatedTime, QR kodunun son güncellemesinin XrTime tarihidir.
  • centerPose, XrTrackableGetInfoANDROID::baseSpace konumundaki QR kodunun XrPosef değeridir. QR kodu, XZ düzleminde yer alır. X, QR kodunun sağını, Z ise altını gösterir.
  • extents, QR kodunun XrExtent2Df boyutudur. Sınırlayıcı kutunun sınırı şu noktalardadır: centerPose +/- (extents / 2).
  • bufferCapacityInput, buffer veya 0'nin gerekli özelliği alma yeteneğidir.
  • bufferCountOutput bufferCapacityInput 0 ise çalışma zamanı, gerekli arabellek boyutunu bufferCountOutput içine yazar. Aksi takdirde, buffer içinde yazılan toplam öğeleri içerir.
  • buffer, çözümlenmiş QR kodu verilerini yazmak için char dizisine yönelik bir işaretçidir. Uygulama, gerekli arabellek boyutunu belirlemek için nullptr geçirebilir veya QR kodu verilerinin kodunun çözülmesini istemiyorsa bunu yapabilir. QR kodu verileri, null ile sonlandırılmış UTF-8 dizesi olarak döndürülür.
  • Gerekli buffer boyutunun alınmasıyla ilgili ayrıntılı açıklama için Arabellek Boyutu Parametreleri bölümüne bakın.

Geçerli Kullanım (Dolaylı)

  • XrTrackableQrCodeANDROID özelliğini kullanmadan önce XR_ANDROID_trackables_qr_code uzantısı etkinleştirilmelidir.
  • type XR_TYPE_TRACKABLE_QR_CODE_ANDROID olmalıdır
  • next, NULL olmalı veya bir yapı zincirindeki sonraki yapıya yönelik geçerli bir işaretçi olmalıdır.
  • trackingState geçerli bir XrTrackingStateANDROID değeri olmalıdır.
  • bufferCapacityInput, 0 değilse buffer, bufferCapacityInput char değerleri dizisinin işaretçisi olmalıdır.

İzlenebilir QR kodları alma örneği

Aşağıdaki örnek kodda, izlenebilir QR kodlarının nasıl alınacağı gösterilmektedir.

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

Yeni Enum Sabitleri

XrStructureType numaralandırması şu öğelerle genişletildi:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

XrTrackableTypeANDROID numaralandırması şu öğelerle genişletildi:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Yeni sıralamalar

  • XrQrCodeTrackingModeANDROID

Yeni Yapılar

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

Yeni İşlevler

  • xrGetTrackableQrCodeANDROID

Sorunlar

Sürüm Geçmişi

  • 1. düzeltme, 05.02.2025 (Levana Chen)
    • İlk uzantı açıklaması.

OpenXR™ ve OpenXR logosu, The Khronos Group Inc. şirketinin ticari markalarıdır ve Çin, Avrupa Birliği, Japonya ve Birleşik Krallık'ta ticari marka olarak tescillidir.