XR_ANDROID_trackables_image

מחרוזת שם

XR_ANDROID_trackables_image

סוג התוסף

הרחבת המכונה

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

710

Revision

1

סטטוס האישור

לא אושר

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

XR_EXT_future
וגם
XR_ANDROID_trackables

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

2025-04-08

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

לא ידוע על תלונות בנושא זכויות יוצרים שקשורות לכתובות 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.

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

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

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

האפליקציה חייבת לספק לפחות XrTrackableImageDatabaseEntryANDROID אחד כשיוצרים נקודת אחיזה של 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 הוא ה-handle שנוצר XrTrackableImageDatabaseANDROID.

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

ערכים של futureResult:

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • 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

Failure

  • 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

Failure

  • 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

Failure

  • 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 כדי ליצור את האובייקט למעקב.

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

הספירה 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 — המצב הזה מתאים לתמונות שידוע שהן סטטיות או חצי סטטיות. במצב הזה צריכת החשמל נמוכה יותר בהשוואה למצב הדינמי. אם תמונה סטטית מוזזת, היא תתעדכן עם זמן אחזור גבוה בהרבה מאשר בשימוש במצב דינמי.

הספירה 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

Failure

  • 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

Failure

  • 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

Failure

  • 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 הוא ה-handle של XrTrackableImageDatabaseANDROID שממנו בוצע המעקב אחר התמונה הזו.
  • databaseEntryIndex הוא האינדקס שממופה למערך XrTrackableImageDatabaseCreateInfoANDROID :: entries של database .
  • 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 וליצור אותן מחדש אם היא רוצה להמשיך במעקב אחרי תמונות. בנוסף, האפליקציה חייבת להרוס את כל ה-handlers של 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;
    }
  }
}

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

פקודות חדשות

מבנים חדשים

New Enums

New Enum Constants

  • 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 (דניאל גוטנברג)

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