‫XR_ANDROID_trackables_qr_code OpenXR extension

מחרוזת שם

XR_ANDROID_trackables_qr_code

סוג התוסף

הרחבת המכונה

מספר שלוחה רשום

460

Revision

1

תלות בתוסף ובגרסה

XR_ANDROID_trackables

תאריך השינוי האחרון

2025-02-05

סטטוס כתובת ה-IP

לא ידוע על תלונות בנושא קניין רוחני.

שותפים ביצירת התוכן

Christopher Doer, Google

לבנה צ'ן, Google

Jared Finder, Google

ספנסר קווין, Google

Nihav Jain, Google

דייגו טיפלדי, Google

קן מקיי, Google

דניאל גוטנברג, קוואלקום

סקירה כללית

התוסף הזה מאפשר מעקב פיזי אחרי קודי QR ופענוח של נתוני קודי QR.

בדיקת יכולות המערכת

XrSystemQrCodeTrackingPropertiesANDROID

המבנה של XrSystemQrCodeTrackingPropertiesANDROID מוגדר כך:

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

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת של מבנים. לא מוגדרים מבנים כאלה ב-OpenXR הבסיסי או בתוסף הזה.
  • ‫supportsQrCodeTracking הוא XrBool32 שמציין אם המערכת הנוכחית מספקת יכולת מעקב אחרי קודי QR.
  • ‫supportsQrCodeSizeEstimation הוא XrBool32 שמציין אם המערכת הנוכחית מספקת הערכה של גודל קוד ה-QR.
  • ‫maxQrCodeCount הוא המספר המקסימלי הכולל של קודי QR שאפשר לעקוב אחריהם בו-זמנית.

אפליקציה יכולה לבדוק אם המערכת מסוגלת לעקוב אחרי קוד QR על ידי הרחבת XrSystemProperties עם מבנה XrSystemQrCodeTrackingPropertiesANDROID כשקוראים ל-xrGetSystemProperties. סביבת זמן הריצה חייבת להחזיר XR_ERROR_FEATURE_UNSUPPORTED ליצירת קוד QR למעקב אם ורק אם supportsQrCodeTracking הוא XR_FALSE.

אם סביבת ריצה תומכת במעקב אחרי קודי QR, חובה שתהיה בה תמיכה בmaxQrCodeCountמעקב אחרי קודי QR בכל זמן נתון.

אם סביבת זמן ריצה תומכת בהערכת גודל של קוד QR, האפליקציה יכולה להגדיר את XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize 0 כדי לציין את השימוש בהערכת הגודל. אחרת, האפליקציה חייבת להגדיר את XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize לערך חיובי או שיוחזר XR_ERROR_VALIDATION_FAILURE.

שימוש תקין (מרומז)

  • חובה להפעיל את התוסף XR_ANDROID_trackables_qr_code לפני שמשתמשים ב-XrSystemQrCodeTrackingPropertiesANDROID
  • הערך של type חייב להיות XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • הפרמטר next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

מעקב אחרי קודי QR

התוסף הזה מוסיף את XR_TRACKABLE_TYPE_QR_CODE_ANDROID אל XrTrackableTypeANDROID.

יכול להיות שהאפליקציה תיצור XrTrackableTrackerANDROID על ידי קריאה ל-xrCreateTrackableTrackerANDROID וציון XR_TRACKABLE_TYPE_QR_CODE_ANDROID כסוג שניתן למעקב ב-XrTrackableTrackerCreateInfoANDROID::trackableType כדי לעקוב אחרי קודי QR.

סביבת זמן הריצה חייבת להחזיר XR_ERROR_FEATURE_UNSUPPORTED אם XrTrackableTrackerCreateInfoANDROID::trackableType הוא XR_TRACKABLE_TYPE_QR_CODE_ANDROID ו-XrSystemQrCodeTrackingPropertiesANDROID::supportsQrCodeTracking מחזירה XR_FALSE באמצעות xrGetSystemProperties.

XrTrackableQrCodeConfigurationANDROID

המבנה של XrTrackableQrCodeConfigurationANDROID מוגדר כך:

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

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת של מבנים. לא מוגדרים מבנים כאלה ב-OpenXR הבסיסי או בתוסף הזה.
  • ‫trackingMode הוא XrQrCodeTrackingModeANDROID שמציין את מצב המעקב הרצוי.
  • ‫qrCodeEdgeSize מציין את הגודל של קצה קוד ה-QR במטרים. אם הערך הוא אפס, גודל קוד ה-QR יוערך אונליין.

האפליקציה חייבת להגדיר תצורה תקינה על ידי הוספת XrTrackableQrCodeConfigurationANDROID לשרשרת הבאה של XrTrackableTrackerCreateInfoANDROID. אחרת, סביבת זמן הריצה חייבת להחזיר XR_ERROR_VALIDATION_FAILURE.

אם סביבת זמן הריצה תומכת בהערכת גודל קוד ה-QR, האפליקציה עשויה להגדיר את XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize ל-0 כדי לציין את השימוש בהערכת הגודל. אחרת, האפליקציה חייבת להגדיר את XrTrackableQrCodeConfigurationANDROID::qrCodeEdgeSize לערך חיובי או שיוחזר XR_ERROR_VALIDATION_FAILURE.

מסנן זמן הריצה חייב לסנן את הפלט מ-xrGetAllTrackablesANDROID כך שיתאים ל-trackingMode ול-qrCodeEdgeSize.

שימוש תקין (מרומז)

  • חובה להפעיל את התוסף XR_ANDROID_trackables_qr_code לפני שמשתמשים ב-XrTrackableQrCodeConfigurationANDROID
  • הערך של type חייב להיות XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • הפרמטר next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
  • trackingMode חייב להיות ערך חוקי של XrQrCodeTrackingModeANDROID

XrQrCodeTrackingModeANDROID

ה-enum‏ XrQrCodeTrackingModeANDROID מתאר את מצבי המעקב הנתמכים של קודי 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 | Description XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID ' | XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID | קוד ה-QR הוא דינמי ויכול לזוז. |

קבלת קודי QR

xrGetTrackableQrCodeANDROID

הפונקציה xrGetTrackableQrCodeANDROID מוגדרת כך:

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

תיאורים של פרמטרים

  • ‫tracker הוא XrTrackableTrackerANDROID שאותו רוצים לשאול.
  • ‫getInfo הוא XrTrackableGetInfoANDROID עם המידע שמשמש ליצירת קוד ה-QR שאפשר לעקוב אחריו.
  • ‫qrCodeOutput הוא מצביע למבנה XrTrackableQrCodeANDROID שבו מוחזר קוד ה-QR שאפשר לעקוב אחריו.

הפונקציה בזמן הריצה חייבת להחזיר XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID אם הסוג של הפריט שאפשר לעקוב אחריו XrTrackableANDROID הוא לא XR_TRACKABLE_TYPE_QR_CODE_ANDROID, או אם הסוג של הפריט שאפשר לעקוב אחריו XrTrackableTrackerANDROID הוא לא XR_TRACKABLE_TYPE_QR_CODE_ANDROID.

שימוש תקין (מרומז)

  • חובה להפעיל את התוסף XR_ANDROID_trackables_qr_code לפני שמתקשרים אל xrGetTrackableQrCodeANDROID
  • tracker חייב להיות כינוי חוקי XrTrackableTrackerANDROID
  • ‫getInfo must be a pointer to a valid XrTrackableGetInfoANDROID structure
  • הערך qrCodeOutput חייב להיות מצביע למבנה XrTrackableQrCodeANDROID

XrTrackableQrCodeANDROID

המבנה של XrTrackableQrCodeANDROID מוגדר כך:

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

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת של מבנים. לא מוגדרים מבנים כאלה ב-OpenXR הבסיסי או בתוסף הזה.
  • ‫trackingState הוא XrTrackingStateANDROID של קוד ה-QR.
  • ‫lastUpdatedTime הוא XrTime של העדכון האחרון של קוד ה-QR.
  • ‫centerPose הוא XrPosef של קוד ה-QR שנמצא ב-XrTrackableGetInfoANDROID::baseSpace. קוד ה-QR נמצא במישור XZ, כאשר ציר X מצביע ימינה מקוד ה-QR וציר Z מצביע כלפי מטה.
  • ‫extents הוא המידות של קוד ה-QR‏ XrExtent2Df. הגבול של התיבה התוחמת נמצא בנקודות: centerPose +/-‎(extents / 2).
  • ‫bufferCapacityInput היא היכולת של buffer או 0 לאחזר את היכולת הנדרשת.
  • ‫bufferCountOutput אם הערך של bufferCapacityInput הוא 0, זמן הריצה יכתוב את גודל המאגר הנדרש לתוך bufferCountOutput. אחרת, הוא מכיל את סך הרכיבים שנכתבו ב-buffer.
  • ‫buffer הוא מצביע למערך של char לכתיבת נתוני קוד ה-QR המפוענחים. האפליקציה יכולה להעביר nullptr כדי לקבוע את גודל המאגר הנדרש, או אם לא מתבצעת בקשה לפענוח נתוני קוד ה-QR. נתוני קוד ה-QR מוחזרים כמחרוזת UTF-8 שמסתיימת בערך Null.
  • בקטע פרמטרים של גודל מאגר מוסבר בפירוט איך מאחזרים את הגודל הנדרש של buffer.

שימוש תקין (מרומז)

  • חובה להפעיל את התוסף XR_ANDROID_trackables_qr_code לפני שמשתמשים ב-XrTrackableQrCodeANDROID
  • הערך של type חייב להיות XR_TYPE_TRACKABLE_QR_CODE_ANDROID
  • הפרמטר next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
  • trackingState חייב להיות ערך חוקי של XrTrackingStateANDROID
  • אם bufferCapacityInput הוא לא 0, ‏buffer חייב להיות מצביע למערך של ערכי bufferCapacityInput char

דוגמה לקוד לקבלת קודי QR שאפשר לעקוב אחריהם

בדוגמת הקוד הבאה אפשר לראות איך מקבלים קודי QR שאפשר לעקוב אחריהם.

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

New Enum Constants

הספירה XrStructureType הורחבה עם:

  • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID
  • XR_TYPE_TRACKABLE_QR_CODE_ANDROID

הספירה XrTrackableTypeANDROID הורחבה עם:

  • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

New Enums

  • XrQrCodeTrackingModeANDROID

מבנים חדשים

  • XrSystemQrCodeTrackingPropertiesANDROID
  • XrTrackableQrCodeConfigurationANDROID
  • XrTrackableQrCodeANDROID

פונקציות חדשות

  • xrGetTrackableQrCodeANDROID

בעיות

היסטוריית הגרסאות

  • גרסה 1, ‏ 5 בפברואר 2025 (לבנה חן)
    • התיאור הראשוני של התוסף.

‫OpenXR™‎ והלוגו של OpenXR הם סימנים מסחריים בבעלות The Khronos Group Inc. ‎ והם רשומים כסימן מסחרי בסין, באיחוד האירופי, ביפן ובבריטניה.