XR_ANDROID_trackables_image

מחרוזת שם

XR_ANDROID_trackables_image

סוג התוסף

תוסף למכונה

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

710

גרסה

1

סטטוס האישור

לא אושר

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

XR_EXT_future
וגם
XR_ANDROID_trackables

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

2025-04-08

סטטוס IP

אין תלונות ידועות על הפרת קניין רוחני.

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

כריסטופר דור, Google
לבנה חן, Google
ג'ארד פינדר, Google
ספנסר קווין, Google
ניהב ג'יין, Google
דייגו טיפלדי, Google
דניאל גוטנברג, Qualcomm
מארק ואדאסי, Qualcomm
מרקוס בירקנר, Qualcomm
מקסימיליאן מאייר, Qualcomm

סקירה כללית

התוסף הזה מאפשר לעקוב אחרי תמונות מישוריות, כפי שצוין בקבוצות של תמונות רפרנס לקלט.

הרשאות

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

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

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

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

typedef struct XrSystemImageTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsImageTracking;
    XrBool32           supportsPhysicalSizeEstimation;
    uint32_t           maxTrackedImageCount;
    uint32_t           maxLoadedImageCount;
} XrSystemImageTrackingPropertiesANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה. לפרטים נוספים על שרשרת המבנים, אפשר לעיין במבנה המורחב ( XrSystemProperties ).
  • ‫supportsImageTracking הוא XrBool32 שמציין אם המערכת הנוכחית מספקת יכולת מעקב אחרי תמונות.
  • ‫supportsPhysicalSizeEstimation הוא XrBool32 שמציין אם המערכת הנוכחית מספקת הערכה של גודל התמונה.
  • ‫maxTrackedImageCount הוא המספר המקסימלי של תמונות שאפשר לעקוב אחריהן בו-זמנית.
  • ‫maxLoadedImageCount הוא המספר המקסימלי הכולל של תמונות רפרנס שאפשר לטעון בכל מסדי הנתונים.

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

אם סביבת זמן ריצה תומכת במעקב אחר תמונות, היא חייבת לתמוך ב-maxTrackedImageCount תמונות במעקב בכל זמן נתון.

אם סביבת זמן ריצה תומכת במעקב אחר תמונות, היא חייבת לתמוך ב-maxLoadedImageCount תמונות שנטענו בכל זמן נתון.

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

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

יצירת מסדי נתונים

האפליקציה יכולה ליצור נקודת אחיזה (handle) מסוג XrTrackableImageDatabaseANDROID על ידי יצירת מבנה אחד או יותר מסוג XrTrackableImageDatabaseEntryANDROID והעברה שלהם לפונקציה xrCreateTrackableImageDatabaseAsyncANDROID דרך מבנה מסוג XrTrackableImageDatabaseCreateInfoANDROID.

האפליקציה חייבת לספק לפחות ערך אחד של XrTrackableImageDatabaseEntryANDROID כשיוצרים נקודת אחיזה (handle) של XrTrackableImageDatabaseANDROID.

‫XrTrackableImageDatabaseANDROID הוא כינוי שמייצג קבוצה של תמונות רפרנס מעובדות שאפשר לגלות ולעקוב אחריהן בסביבה.

XR_DEFINE_HANDLE(XrTrackableImageDatabaseANDROID)

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

typedef struct XrTrackableImageDatabaseEntryANDROID {
    XrStructureType                        type;
    const void*                            next;
    XrTrackableImageTrackingModeANDROID    trackingMode;
    float                                  physicalWidth;
    uint32_t                               imageWidth;
    uint32_t                               imageHeight;
    XrTrackableImageFormatANDROID          format;
    uint32_t                               bufferSize;
    const uint8_t*                         buffer;
} XrTrackableImageDatabaseEntryANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫trackingMode הוא XrTrackableImageTrackingModeANDROID שמציין את המצב הרצוי למעקב.
  • ‫physicalWidth מציין את רוחב התמונה במטרים. אם הערך הוא אפס, גודל התמונה יחושב אונליין.
  • ‫imageWidth מציין את רוחב התמונה בפיקסלים.
  • ‫imageHeight מציין את גובה התמונה בפיקסלים.
  • ‫format הוא XrTrackableImageFormatANDROID שמציין את הפורמט של נתוני התמונה ב-buffer .
  • ‫bufferSize מציין את אורך הבייטים של buffer .
  • ‫buffer הוא מאגר הנתונים (uint8_t) שמכיל את נתוני הפיקסלים של תמונת הרפרנס. התוכן של buffer חייב להיות תקין למשך הפעולה האסינכרונית של יצירת מסד הנתונים, שמתחילה על ידי xrCreateTrackableImageDatabaseAsyncANDROID ומושלמת על ידי xrCreateTrackableImageDatabaseCompleteANDROID .

האפליקציה יכולה להגדיר את physicalWidth ל-0 כדי לבקש הערכת גודל אונליין אם XrSystemImageTrackingPropertiesANDROID :: supportsPhysicalSizeEstimation הוא XR_TRUE .

יכול להיות שזמן הריצה יחזיר את הערך XR_ERROR_VALIDATION_FAILURE מ-xrCreateTrackableImageDatabaseAsyncANDROID אם bufferSize לא תואם לגודל הצפוי על סמך imageWidth , imageHeight ו-format של הרשומה.

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

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

typedef struct XrTrackableImageDatabaseCreateInfoANDROID {
    XrStructureType                                type;
    const void*                                    next;
    uint32_t                                       entryCount;
    const XrTrackableImageDatabaseEntryANDROID*    entries;
} XrTrackableImageDatabaseCreateInfoANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫entryCount הוא uint32_t שמציין את מספר הרכיבים במערך entries.
  • ‫entries הוא מערך של מבני XrTrackableImageDatabaseEntryANDROID.

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

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

typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
    XrStructureType                    type;
    void*                              next;
    XrResult                           futureResult;
    XrTrackableImageDatabaseANDROID    database;
} XrCreateTrackableImageDatabaseCompletionANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫futureResult הוא ה-XrResult של הפעולה האסינכרונית.
  • ‫database הוא נקודת האחיזה שנוצרה ב-XrTrackableImageDatabaseANDROID.

קודי החזרה עתידיים

ערכי futureResult:

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

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

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

XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
    XrSession                                   session,
    const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateTrackableImageDatabaseCompletionANDROID* completion);

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrDestroyTrackableImageDatabaseANDROID(
    XrTrackableImageDatabaseANDROID             database);

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

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

Thread Safety

  • הגישה אל database , ואל כל נקודות האחיזה הצאצאות, חייבת להיות מסונכרנת באופן חיצוני

קודי החזרה

הצלחה

  • XR_SUCCESS

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

תמונות מעקב

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

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

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_FEATURE_UNSUPPORTED אם XrTrackableTrackerCreateInfoANDROID :: trackableType הוא XR_TRACKABLE_TYPE_IMAGE_ANDROID ו-XrSystemImageTrackingPropertiesANDROID :: supportsImageTracking מחזיר את הערך XR_FALSE דרך xrGetSystemProperties .

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

typedef struct XrTrackableImageConfigurationANDROID {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  databaseCount;
    const XrTrackableImageDatabaseANDROID*    databases;
} XrTrackableImageConfigurationANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫databaseCount הוא uint32_t שמציין את מספר הרכיבים ב-databases
  • ‫databases הוא מערך של XrTrackableImageDatabaseANDROID שמציין את מסדי הנתונים שבאמצעותם צריך ליצור את הכלי למעקב.

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

האפליקציה חייבת לספק לפחות מבנה אחד של XrTrackableImageDatabaseANDROID כדי ליצור את הכלי למעקב.

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

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

typedef enum XrTrackableImageTrackingModeANDROID {
    XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID = 1,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID = 2,
    XR_TRACKABLE_IMAGE_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageTrackingModeANDROID;

תיאורי ערכים מספריים

  • XR_TRACKABLE_IMAGE_TRACKING_MODE_DYNAMIC_ANDROID – המצב הזה מספק את הדיוק הגבוה ביותר ומאפשר מעקב עם זמן אחזור נמוך אחרי תמונות נעות. במצב הזה צריכת החשמל היא הגבוהה ביותר.
  • XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID — צריך להשתמש במצב הזה לתמונות שידוע שהן סטטיות או חצי סטטיות. המצב הזה מוביל לצריכת חשמל נמוכה יותר בהשוואה למצב הדינמי. אם תמונה סטטית זזה, היא תתעדכן עם זמן אחזור ארוך בהרבה מאשר במצב הדינמי.

ה-enum‏ XrTrackableImageFormatANDROID מתאר את הפורמטים הנתמכים של תמונות.

typedef enum XrTrackableImageFormatANDROID {
    XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID = 1,
    XR_TRACKABLE_IMAGE_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableImageFormatANDROID;

תיאורי ערכים מספריים

  • ‫XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID — פורמט תמונה RGBA עם 8 ביטים לכל ערוץ צבע ונתוני שקיפות.

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

XrResult xrAddTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

כשמוסיפים XrTrackableImageDatabaseANDROID למעקב, חובה להביא בחשבון את תמונות הרפרנס של מסד הנתונים הזה לצורך זיהוי ומעקב, בנוסף לכל מסד נתונים אחר שנוסף קודם לכן באמצעות xrAddTrackableImageDatabaseANDROID או באמצעות המבנה XrTrackableImageConfigurationANDROID במהלך היצירה הראשונית של המעקב.

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrRemoveTrackableImageDatabaseANDROID(
    XrTrackableTrackerANDROID                   tracker,
    XrTrackableImageDatabaseANDROID             database);

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

כשמסירים XrTrackableImageDatabaseANDROID מ-XrTrackableTrackerANDROID, אסור להשתמש יותר במבני XrTrackableImageDatabaseEntryANDROID של מסד הנתונים הזה לזיהוי ולמעקב. אסור לדווח על רשומות שמתבצע אחריהן מעקב פעיל במסד הנתונים הזה. אסור להשמיד באופן משתמע את נקודת האחיזה XrTrackableImageDatabaseANDROID שהוסרה, כחלק מהפעולה הזו.

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

התמונות בתהליך הורדה

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

XrResult xrGetTrackableImageANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableImageANDROID*                    trackable);

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

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrTrackableImageANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrTrackingStateANDROID             trackingState;
    XrTime                             lastUpdatedTime;
    XrTrackableImageDatabaseANDROID    database;
    uint32_t                           databaseEntryIndex;
    XrPosef                            centerPose;
    XrExtent2Df                        extents;
} XrTrackableImageANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • ‫trackingState הוא ה-XrTrackingStateANDROID של התמונה.
  • ‫lastUpdatedTime הוא XrTime של העדכון האחרון של התמונה.
  • ‫database הוא נקודת האחיזה של XrTrackableImageDatabaseANDROID שממנה התמונה הזו נשלפה.
  • ‫databaseEntryIndex הוא האינדקס שממפה למערך entries של database ב-XrTrackableImageDatabaseCreateInfoANDROID :: .
  • ‫centerPose הוא ה-XrPosef של התמונה שנמצאת ב-XrTrackableGetInfoANDROID :: baseSpace . התמונה נמצאת במישור XZ, כאשר X מצביע לצד ימין של התמונה ו-Z מצביע לתחתית שלה.
  • ‫extents הוא המידות של התמונה ב-XrExtent2Df. הגבול של התיבה התוחמת נמצא בנקודות: ‎centerPose +/- ( extents / 2).

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

טיפול בכשלים

האפליקציה חייבת לבצע סקר לאירוע XrEventDataImageTrackingLostANDROID באמצעות xrPollEvent ואסור להתעלם ממנו.

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

typedef struct XrEventDataImageTrackingLostANDROID {
    XrStructureType    type;
    const void*        next;
    XrTime             time;
} XrEventDataImageTrackingLostANDROID;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
  • time XrTime

קבלת האירוע XrEventDataImageTrackingLostANDROID מציינת שהמעקב אחרי התמונה נכשל בגלל תקלה פנימית, וכתוצאה מכך המשאבים הקיימים לא תקפים. האפליקציה חייבת להשמיד את כל נקודות האחיזה של XrTrackableImageDatabaseANDROID וליצור אותן מחדש אם היא רוצה להמשיך במעקב אחרי תמונות. בנוסף, האפליקציה חייבת להשמיד את כל נקודות האחיזה של XrTrackableTrackerANDROID שקשורות למעקב אחרי תמונות, וליצור אותן מחדש אם רוצים להמשיך במעקב אחרי תמונות.

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

קוד לדוגמה לקבלת תמונות שניתן לעקוב אחריהן

הקוד לדוגמה הבא מדגים איך לקבל תמונות שניתנות למעקב.

XrInstance instance;  // Previously initialized.
XrSession session;    // Previously initialized.
XrSystemId systemId;  // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // Previously initialized.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrGetTrackableImageANDROID xrGetTrackableImageANDROID;                                        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // 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
XrSystemImageTrackingPropertiesANDROID imageProperty {
  .type = XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &imageProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!imageProperty.supportsImageTracking) {
    // image tracking is not supported.
    return;
}

uint8_t* imageBuffer; // Load the image buffer.
uint32_t imageBufferSize; // Get the image buffer size.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1] = {
  {
    .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID,
    .next = nullptr,
    .trackingMode = XR_TRACKABLE_IMAGE_TRACKING_MODE_STATIC_ANDROID,
    .physicalWidth = 0.1f, // The width of the image in meters.
    .imageWidth = 640,
    .imageHeight = 480,
    .format = XR_TRACKABLE_IMAGE_FORMAT_R8G8B8A8_ANDROID,
    .bufferSize = imageBufferSize, // RGBA buffer size in bytes.
    .buffer = imageBuffer, // RGBA data.
  }
};

XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
  .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .entryCount = 1,
  .entries = imageDatabaseEntries
};

XrFutureEXT imageDatabaseFuture;
CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

bool keepLooping = true;
bool futureReady = false;
while (keepLooping) {
  XrFuturePollInfoEXT pollInfo{
    .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
    .future = imageDatabaseFuture,
  };
  XrFuturePollResultEXT pollResult{
    .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
  };
  CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

  if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
    futureReady = true;
    keepLooping = false;
  } else {
    // Throttle the loop to not fully expend this CPU core.
    std::this_thread::yield();
  }
}

XrTrackableImageDatabaseANDROID imageDatabase;

if (futureReady) {
  XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
    .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
    .next = nullptr,
  };

  CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
  CHK_XR(imageDatabaseCompletion.futureResult);
  imageDatabase = imageDatabaseCompletion.database;
}

XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &imageDatabase
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

XrTrackableImageDatabaseANDROID anotherImageDatabase; // Load another database.

// ... dynamically add it to the existing tracker
CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

while (1) {
  uint32_t trackableCountOutput = 0;

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, nullptr));

  std::vector<XrTrackableANDROID> allImageTrackables;
  allImageTrackables.resize(trackableCountOutput);

  CHK_XR(xrGetAllTrackablesANDROID(imageTrackableTracker, 0, &trackableCountOutput, allImageTrackables.data()));

  for (XrTrackableANDROID trackable : allImageTrackables) {
    XrTrackableGetInfoANDROID imageGetInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackable,
      .baseSpace = appSpace,
      .time = updateTime
    };

    XrTrackableImageANDROID trackableImage{
      .type = XR_TYPE_TRACKABLE_IMAGE_ANDROID,
    };
    CHK_XR(xrGetTrackableImageANDROID(imageTrackableTracker, &imageGetInfo, &trackableImage));

    // Use XrTrackableImageANDROID data.
    (void)trackableImage.trackingState;
    (void)trackableImage.lastUpdatedTime;
    (void)trackableImage.centerPose;
    (void)trackableImage.extents;

    if (trackableImage.database == imageDatabase && trackableImage.databaseEntryIndex == 0) {
      // Knowing which image the index of 0 maps to, use the specific image database
      // entry (e.g. rendering A for image A).
    }
    // indices 1+N comparisons for another specific image database entry.
  }

  // Throttle the loop to not fully expend this CPU core.
  std::this_thread::yield();
}

// Remove image database from an existing tracker to stop tracking the images
// of that specific database. To resume tracking of those images re-add the
// database at a later point.
CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// Destroy the image tracker to stop image tracking completely. Re-creating the
// image tracker with existing image databases will restart image tracking.
CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// Destroy image databases to unload the associated resources. Re-creatingd
// databases requires going through the asynchronous creation procedure again.
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(anotherImageDatabase));
CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

קוד לדוגמה לניהול מסדי נתונים של תמונות בזמן ריצה

בדוגמת הקוד הבאה אפשר לראות איך לשנות את קבוצת התמונות שאחריהן מתבצע מעקב.

XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.
PFN_xrAddTrackableImageDatabaseANDROID xrAddTrackableImageDatabaseANDROID;                        // Previously initialized.
PFN_xrRemoveTrackableImageDatabaseANDROID xrRemoveTrackableImageDatabaseANDROID;                  // Previously initialized.

// See previous C++ sample for database and tracker initialization.
XrTrackableImageDatabaseANDROID imageDatabases[2]; // Previously initialized.
XrTrackableImageDatabaseANDROID anotherImageDatabase; // Previously initialized.

// Create the image tracker config with two input databases to track.
XrTrackableImageConfigurationANDROID imageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 2,
  .databases = imageDatabases
};

XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &imageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

XrTrackableTrackerANDROID imageTrackableTracker;
CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

// The tracker currently tracks the images of the two databases 'imageDatabases[0]' and
// 'imageDatabases[1]' supplied through 'imageConfig'.

CHK_XR(xrRemoveTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is still valid.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]' and 'imageDatabases[1]'.

CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabases[1]));

// The tracker currently tracks 'imageDatabases[0]', but no longer tracks
// 'imageDatabases[1]'.
// The 'imageDatabases[1]' database handle is no longer valid and the corresponding
// resources have been released internally. The database needs to be re-initialized
// and re-added to resume tracking of 'imageDatabases[0]'.

CHK_XR(xrAddTrackableImageDatabaseANDROID(imageTrackableTracker, anotherImageDatabase));

// The tracker currently tracks 'imageDatabases[0]' and 'anotherImageDatabase'.

CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));

// The 'imageTrackableTracker' tracker handle is invalid and image tracking has been
// stopped.
// The 'imageDatabases[0]' and 'anotherImageDatabase' database handles are still valid.

// Create another the image tracker config to re-create the image tracker.
XrTrackableImageConfigurationANDROID anotherImageConfig {
  .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
  .next = nullptr,
  .databaseCount = 1,
  .databases = &anotherImageDatabase
};

XrTrackableTrackerCreateInfoANDROID anotherCreateInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &anotherImageConfig,
  .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
};

CHK_XR(xrCreateTrackableTrackerANDROID(session, &anotherCreateInfo, &imageTrackableTracker));

// The tracker handle has been re-initialized and image tracking has been started again.
// The tracker currently tracks 'anotherImageDatabase'.
// The 'imageDatabases[0]' database handle is still valid, but not currently tracked.

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

קוד הדוגמה הבא מדגים איך לטפל בכשל על ידי דגימה של האירוע XrEventDataImageTrackingLostANDROID.

XrInstance instance; // Previously initialized.
XrSession session; // Previously initialized.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrPollFutureEXT xrPollFutureEXT;                                   // Previously initialized.
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // Previously initialized.
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // Previously initialized.

PFN_xrCreateTrackableImageDatabaseAsyncANDROID xrCreateTrackableImageDatabaseAsyncANDROID;        // Previously initialized.
PFN_xrCreateTrackableImageDatabaseCompleteANDROID xrCreateTrackableImageDatabaseCompleteANDROID;  // Previously initialized.
PFN_xrDestroyTrackableImageDatabaseANDROID xrDestroyTrackableImageDatabaseANDROID;                // Previously initialized.

XrTrackableImageDatabaseEntryANDROID imageDatabaseEntries[1]; // Previously initialized.
XrTrackableImageDatabaseANDROID imageDatabase; // Previously initialized.
XrTrackableTrackerANDROID imageTrackableTracker; // Previously initialized.

// Initialize an event buffer to hold the output.
XrEventDataBuffer event = {
  .type = XR_TYPE_EVENT_DATA_BUFFER,
};
XrResult result = xrPollEvent(instance, &event);
if (result == XR_SUCCESS) {
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID: {
      const XrEventDataImageTrackingLostANDROID& eventdata =
        *reinterpret_cast<XrEventDataImageTrackingLostANDROID*>(&event);

      // All existing databases and trackers need to be destroyed.
      CHK_XR(xrDestroyTrackableTrackerANDROID(imageTrackableTracker));
      CHK_XR(xrDestroyTrackableImageDatabaseANDROID(imageDatabase));

      // To resume image tracking, the database(s) and the tracker need to be re-created.

      XrTrackableImageDatabaseCreateInfoANDROID imageDatabaseCreateInfo {
        .type = XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID,
        .next = nullptr,
        .entryCount = 1,
        .entries = imageDatabaseEntries
      };

      XrFutureEXT imageDatabaseFuture;
      CHK_XR(xrCreateTrackableImageDatabaseAsyncANDROID(session, &imageDatabaseCreateInfo, &imageDatabaseFuture));

      while (true) {
        XrFuturePollInfoEXT pollInfo{
          .type = XR_TYPE_FUTURE_POLL_INFO_EXT,
          .future = imageDatabaseFuture,
        };
        XrFuturePollResultEXT pollResult{
          .type = XR_TYPE_FUTURE_POLL_RESULT_EXT,
        };
        CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));

        if (pollResult.state == XR_FUTURE_STATE_READY_EXT) {
          break;
        } else {
          // Throttle the loop to not fully expend this CPU core.
          std::this_thread::yield();
        }
      }

      XrCreateTrackableImageDatabaseCompletionANDROID imageDatabaseCompletion {
        .type = XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID,
        .next = nullptr,
      };

      CHK_XR(xrCreateTrackableImageDatabaseCompleteANDROID(session, imageDatabaseFuture, &imageDatabaseCompletion));
      CHK_XR(imageDatabaseCompletion.futureResult);
      imageDatabase = imageDatabaseCompletion.database;

      XrTrackableImageConfigurationANDROID imageConfig {
       .type = XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID,
       .next = nullptr,
       .databaseCount = 1,
       .databases = &imageDatabase
      };

      XrTrackableTrackerCreateInfoANDROID createInfo {
        .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
        .next = &imageConfig,
        .trackableType = XR_TRACKABLE_TYPE_IMAGE_ANDROID
      };

      XrTrackableTrackerANDROID imageTrackableTracker;
      CHK_XR(xrCreateTrackableTrackerANDROID(session, &createInfo, &imageTrackableTracker));

      break;
    }
  }
}

סוגי אובייקטים חדשים

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

קבועי Enum חדשים

  • XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAME
  • XR_ANDROID_trackables_image_SPEC_VERSION
  • הרחבה של XrObjectType :

    • XR_OBJECT_TYPE_TRACKABLE_IMAGE_DATABASE_ANDROID
  • הרחבת XrResult :

    • XR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROID
  • הרחבה של XrStructureType :

    • XR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID
    • XR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID
    • XR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
  • הרחבה של XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_IMAGE_ANDROID

בעיות

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

  • גרסה 1, 08.04.2025 (דניאל גוטנברג)

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