XR_ANDROID_trackables_qr_code

מחרוזת שם

XR_ANDROID_trackables_qr_code

סוג התוסף

הרחבת המכונה

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

709

Revision

1

סטטוס האישור

לא אושר

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

XR_ANDROID_trackables

מצב הוצאה משימוש

  • הוצא משימוש על ידי התוסף XR_EXT_spatial_marker_tracking

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

2025-02-05

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

לא ידוע על תלונות בנושא זכויות יוצרים שקשורות לכתובות IP.

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

‫Christopher Doer, ‏ Google
Levana Chen, ‏ Google
Jared Finder, ‏ Google
Spencer Quin, ‏ Google
Nihav Jain, ‏ Google
Diego Tipaldi, ‏ Google
Ken Mackay, ‏ Google
Daniel Guttenberg, ‏ Qualcomm

סקירה כללית

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

הרשאות

אפליקציות ל-Android חייבות לכלול במניפסט שלהן את ההרשאה android.permission.SCENE_UNDERSTANDING_COARSE, כי התוסף הזה מסתמך על XR_ANDROID_trackables ומציג את הגיאומטריה של הסביבה. ההרשאה android.permission.SCENE_UNDERSTANDING_COARSE נחשבת להרשאה מסוכנת.

(רמת ההגנה: מסוכן)

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

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

typedef struct XrSystemQrCodeTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsQrCodeTracking;
    XrBool32           supportsQrCodeSizeEstimation;
    uint16_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 חייב להיות לפחות 1. אם סביבת זמן ריצה לא תומכת במעקב באמצעות קוד QR, הערך של maxQrCodeCount חייב להיות 0.

שימוש תקף (משתמע)

מעקב אחרי קודי 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 מוגדר כך:

typedef struct XrTrackableQrCodeConfigurationANDROID {
    XrStructureType                type;
    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.0 כדי לציין את השימוש בהערכת הגודל.

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

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

שימוש תקף (משתמע)

ה-enum‏ XrQrCodeTrackingModeANDROID מתאר את מצבי המעקב הנתמכים של קודי QR.

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;

תיאורים של ערכי המנייה

  • XR_QR_CODE_TRACKING_MODE_DYNAMIC_ANDROID — מעקב אחרי קודי QR דינמיים. במצב הזה יש את רמת הדיוק הכי גבוהה, והוא פועל על קודי QR בתנועה ועל קודי QR סטטיים, אבל צריכת החשמל שלו היא הכי גבוהה.
  • ‫XR_QR_CODE_TRACKING_MODE_STATIC_ANDROID — מעקב אחרי קודי QR סטטיים. המצב הזה שימושי בעיקר לקודי QR סטטיים, והוא מוביל לצריכת חשמל נמוכה יותר בהשוואה למצב הדינמי.
  • ‫XR_QR_CODE_TRACKING_MODE_ANCHORED_QCOM – השתמשו במצב הזה לקודי QR סטטיים. בניגוד למצב הסטטי, במצב הזה המערכת תעקוב אחרי קוד ה-QR רק פעם אחת, ואז תעדכן את המיקומים של המקרים המעקב רק על סמך המיקום של המכשיר. כתוצאה מכך, המעקב נמשך גם אם קוד ה-QR יוצא מתחום הראייה של מסגרת ההתייחסות. התוצאה היא צריכת חשמל מינימלית אחרי מעקב אחר קוד ה-QR. (נוסף על ידי התוסף XR_QCOM_trackables_qr_code_operations)

קבלת קודי QR

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

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

תיאורי הפרמטרים

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

שימוש תקף (משתמע)

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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 מוגדר כך:

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. אם הערך של lastUpdatedTime השתנה מאז הקריאה האחרונה, יכול להיות שגם כל השדות האחרים השתנו.
  • ‫centerPose הוא XrPosef של קוד ה-QR שנמצא ב-XrTrackableGetInfoANDROID :: baseSpace . קוד ה-QR נמצא במישור XZ, כאשר ציר X מצביע אל ימין קוד ה-QR, ציר Z מצביע אל החלק התחתון שלו וציר Y יוצא מקוד ה-QR כנורמל.
  • ‫extents הוא המימד XrExtent2Df של קוד ה-QR. הגבול של התיבה התוחמת נמצא בנקודות: centerPose +/- ( extents / 2).
  • ‫bufferCapacityInput היא היכולת של buffer או 0 לאחזר את היכולת הנדרשת.
  • ‫bufferCountOutput אם הערך של bufferCapacityInput הוא 0 , זמן הריצה יכתוב את גודל המאגר הנדרש לתוך bufferCountOutput . אחרת, הוא מכיל את סך כל הרכיבים שנכתבו ב-buffer . אם הנתונים של קוד ה-QR עדיין לא פוענחו, סביבת זמן הריצה חייבת להגדיר את bufferCountOutput ל-0.
  • ‫buffer הוא מצביע למערך של char לכתיבת נתוני קוד ה-QR המפוענחים. אם האפליקציה לא מתייחסת לנתוני קוד ה-QR המפוענחים, היא יכולה להעביר את nullptr ולדלג על השיחה השנייה. נתוני קוד ה-QR מוחזרים כמחרוזת UTF-8 שמסתיימת בערך null.
  • בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של buffer.

שימוש תקף (משתמע)

דוגמה לקוד לקבלת קודי 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, {
  .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));

פקודות חדשות

מבנים חדשים

New Enums

New Enum Constants

  • XR_ANDROID_TRACKABLES_QR_CODE_EXTENSION_NAME
  • XR_ANDROID_trackables_qr_code_SPEC_VERSION

  • הרחבה של XrStructureType :

    • XR_TYPE_SYSTEM_QR_CODE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_ANDROID
    • XR_TYPE_TRACKABLE_QR_CODE_CONFIGURATION_ANDROID

  • הרחבה של XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_QR_CODE_ANDROID

בעיות

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

  • גרסה 1, ‏2025-02-05 (לבנה חן)

    • התיאור הראשוני של התוסף.