XR_ANDROID_trackables_qr_code

Name String

XR_ANDROID_trackables_qr_code

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

709

Düzeltme

1

Onay durumu

Onaylanmadı

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

XR_ANDROID_trackables

Kullanımdan Kaldırma Durumu

  • XR_EXT_spatial_marker_tracking uzantısı tarafından kullanımdan kaldırıldı

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.

İzinler

Bu uzantı XR_ANDROID_trackables'ya bağlı olduğundan ve ortamın geometrisini ortaya çıkardığından Android uygulamalarının manifest dosyalarında android.permission.SCENE_UNDERSTANDING_COARSE izninin listelenmesi gerekir. android.permission.SCENE_UNDERSTANDING_COARSE izni tehlikeli bir izin olarak kabul edilir.

(koruma düzeyi: tehlikeli)

Sistem kapasitesini inceleme

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

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • 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ı gösteren bir XrBool32'dir.
  • maxQrCodeCount, aynı anda izlenebilecek toplam maksimum QR kodu sayısıdır.

Bir uygulama, xrGetSystemProperties çağrıldığında XrSystemProperties'i XrSystemQrCodeTrackingPropertiesANDROID yapısıyla genişleterek sistemin QR kodu izleme özelliğine sahip olup olmadığını kontrol edebilir . Çalışma zamanı, supportsQrCodeTracking değeri XR_FALSE ise QR kodu izleyici oluşturma için XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir .

Bir çalışma zamanı QR kodu izlemeyi destekliyorsa maxQrCodeCount en az 1 olmalıdır. Bir çalışma zamanı QR kodu izlemeyi desteklemiyorsa maxQrCodeCount 0 olmalıdır.

Geçerli Kullanım (Dolaylı)

QR kodlarını izleme

Bu uzantı, XrTrackableTypeANDROID öğesine XR_TRACKABLE_TYPE_QR_CODE_ANDROID ekler .

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

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

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

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

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • 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 belirten bir XrQrCodeTrackingModeANDROID değeridir.
  • qrCodeEdgeSize, QR kodu kenarının metre cinsinden boyutunu gösterir. Sıfırsa çalışma zamanı, QR kodu boyutunu online olarak tahmin eder.

Uygulama, XrTrackableTrackerCreateInfoANDROID zincirine 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 XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize değerini 0.0 olarak ayarlayabilir.

Çalışma zamanı, QR kodu boyut tahminini desteklemiyorsa uygulama XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize değerini pozitif bir değere ayarlamalıdır. Aksi takdirde çalışma zamanı XR_ERROR_VALIDATION_FAILURE değerini döndürmelidir.

Çalışma zamanı, xrGetAllTrackablesANDROID'den gelen çıktıyı trackingMode ile eşleşecek şekilde filtrelemelidir . XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize, 0.0 olarak ayarlanmamışsa çalışma zamanı yalnızca bu boyuta uyan QR kodlarını döndürmelidir. XrTrackableQrCodeConfigurationANDROID :: qrCodeEdgeSize, 0.0 olarak ayarlanırsa çalışma zamanı, tahmini boyuta sahip tüm QR kodlarını döndürmelidir.

Geçerli Kullanım (Dolaylı)

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

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;

Numaralandırılmış Değer Açıklamaları

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID — Dinamik QR kodlarını izleme. Bu mod, en yüksek doğruluğa sahiptir ve hareketli ve statik QR kodlarında çalışır ancak en yüksek güç tüketimine de sahiptir.
  • XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID — Statik QR kodlarını izleme. Bu mod, öncelikli olarak statik olduğu bilinen QR kodları için kullanışlıdır. Bu sayede, dinamik moda kıyasla daha az güç tüketilir.
  • XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM: Bu mod, statik QR kodları için kullanılmalıdır. Statik modun aksine bu mod, QR kodunu yalnızca bir kez izler ve ardından izlenen örneklerin konumlarını yalnızca cihazın konumuna göre günceller. Bu sayede, QR kodu referans çerçevesinin görünüm alanından çıksa bile izleme devam eder. Bu sayede, QR kodu izlendikten sonra güç tüketimi en aza indirilir. (XR_QCOM_trackables_qr_code_operations uzantısı tarafından eklendi)

QR kodu alma

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

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

Parametre Açıklamaları

Ç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ı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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

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'ıdır.
  • 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 değeridir.
  • lastUpdatedTime, QR kodunun son güncelleme XrTime tarihidir. lastUpdatedTime son aramadan sonra değiştirildiyse diğer tüm alanlar değişmiş olabilir.
  • centerPose, XrTrackableGetInfoANDROID :: baseSpace içinde bulunan QR kodunun XrPosef değeridir . QR kodu, XZ düzleminde yer alır. X, QR kodunun sağını, Z ise altını gösterir. Y ise QR kodundan normal olarak çıkar.
  • extents, QR kodunun XrExtent2Df boyutlarıdır. Sınırlayıcı kutunun sınırı şu noktalardadır: centerPose +/- ( extents / 2).
  • bufferCapacityInput , buffer veya 0 öğesinin 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 . QR kodu verileri henüz çözülmediyse çalışma zamanı bufferCountOutput değerini 0 olarak ayarlamalıdır.
  • buffer, çözümlenmiş QR kodu verilerini yazmak için char dizisine yönelik bir işaretçidir. Uygulama, kodu çözülen QR kodu verilerini önemsemiyorsa geçebilir (nullptr) ve ikinci iki çağrı çağrısını atlayabilir. 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ı)

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

Yeni Komutlar

Yeni Yapılar

Yeni Sıralamalar

Yeni Enum Sabitleri

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • XrStructureType uzatma :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • XrTrackableTypeANDROID'i genişletme :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

Sayılar

Sürüm Geçmişi

  • 1. düzeltme, 05.02.2025 (Levana Chen)

    • İlk uzantı açıklaması.