XR_ANDROID_trackables_qr_code

מחרוזת שם

XR_ANDROID_trackables_qr_code

סוג התוסף

תוסף למכונה

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

709

גרסה

1

סטטוס האישור

לא אושר

תלויות של תוספים וגרסאות

XR_ANDROID_trackables

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

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

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

2025-02-05

סטטוס 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 סטטיים ונעים, אבל גם צורך הכי הרבה חשמל.
  • 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

נכשל

  • 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 הוא המידות של קוד ה-QR ב-XrExtent2Df. הגבול של התיבה התוחמת נמצא בנקודות: ‎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));

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

קבועי Enum חדשים

  • 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 (Levana Chen)

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