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.
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שמשתמשים ב-XrSystemImageTrackingPropertiesANDROID -
typeחייב להיותXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextחייב להיותNULLאו מצביע תקין למבנה הבא בשרשרת מבנים
יצירת מסדי נתונים
האפליקציה יכולה ליצור נקודת אחיזה (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 של הרשומה.
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שמשתמשים ב-XrTrackableImageDatabaseEntryANDROID -
typeחייב להיותXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextחייב להיותNULLאו מצביע תקין למבנה הבא בשרשרת מבנים -
trackingModeחייב להיות ערך XrTrackableImageTrackingModeANDROID תקין -
formatחייב להיות ערך XrTrackableImageFormatANDROID תקין -
bufferחייב להיות מצביע למערך של ערכיbufferSizeuint8_t - הפרמטר
bufferSizeחייב להיות גדול מ-0
המבנה של 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.
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שמשתמשים ב-XrTrackableImageDatabaseCreateInfoANDROID -
typeחייב להיותXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROID -
nextחייב להיותNULLאו מצביע תקין למבנה הבא בשרשרת מבנים -
entriesחייב להיות מצביע למערך של מבניentryCountתקינים מסוג XrTrackableImageDatabaseEntryANDROID - הפרמטר
entryCountחייב להיות גדול מ-0
המבנה של XrCreateTrackableImageDatabaseCompletionANDROID מוגדר כך:
typedef struct XrCreateTrackableImageDatabaseCompletionANDROID {
XrStructureType type;
void* next;
XrResult futureResult;
XrTrackableImageDatabaseANDROID database;
} XrCreateTrackableImageDatabaseCompletionANDROID;
תיאורי חברים
-
typeהוא ה-XrStructureType של המבנה הזה. -
nextהואNULLאו מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה. -
futureResultהוא ה-XrResult של הפעולה האסינכרונית. -
databaseהוא נקודת האחיזה שנוצרה ב-XrTrackableImageDatabaseANDROID.
קודי החזרה עתידיים
ערכי futureResult:
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_RUNTIME_FAILUREXR_ERROR_INSTANCE_LOSTXR_ERROR_SESSION_LOSTXR_ERROR_OUT_OF_MEMORYXR_ERROR_LIMIT_REACHED
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שמשתמשים ב-XrCreateTrackableImageDatabaseCompletionANDROID -
typeחייב להיותXR_TYPE_CREATE_TRACKABLE_IMAGE_DATABASE_COMPLETION_ANDROID -
nextחייב להיותNULLאו מצביע תקין למבנה הבא בשרשרת מבנים -
futureResultחייב להיות ערך XrResult תקין -
databaseחייב להיות נקודת אחיזה חוקית של XrTrackableImageDatabaseANDROID
הפונקציה xrCreateTrackableImageDatabaseAsyncANDROID מוגדרת כך:
XrResult xrCreateTrackableImageDatabaseAsyncANDROID(
XrSession session,
const XrTrackableImageDatabaseCreateInfoANDROID* createInfo,
XrFutureEXT* future);
תיאורי פרמטרים
-
sessionהוא נקודת אחיזה ל-XrSession שנוצר בעבר באמצעות xrCreateSession . -
createInfoהוא מצביע למבנה XrTrackableImageDatabaseCreateInfoANDROID. -
futureהוא מצביע ל-XrFutureEXTשנוצר.
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שקוראים לפונקציה xrCreateTrackableImageDatabaseAsyncANDROID -
sessionחייב להיות כינוי תקין של XrSession -
createInfoחייב להיות מצביע למבנה XrTrackableImageDatabaseCreateInfoANDROID תקין -
futureחייב להיות מצביע לערךXrFutureEXT
קודי החזרה
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FEATURE_UNSUPPORTEDXR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_IMAGE_FORMAT_UNSUPPORTED_ANDROIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
הפונקציה xrCreateTrackableImageDatabaseCompleteANDROID מוגדרת כך:
XrResult xrCreateTrackableImageDatabaseCompleteANDROID(
XrSession session,
XrFutureEXT future,
XrCreateTrackableImageDatabaseCompletionANDROID* completion);
תיאורי פרמטרים
-
sessionהוא נקודת אחיזה ל-XrSession שנוצר בעבר באמצעות xrCreateSession . -
futureהוא הערך שלXrFutureEXTבעתיד שצריך להשלים. -
completionהוא מצביע למבנה XrCreateTrackableImageDatabaseCompletionANDROID שמכיל את תוצאת הפעולה.
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שקוראים לפונקציה xrCreateTrackableImageDatabaseCompleteANDROID -
sessionחייב להיות כינוי תקין של XrSession -
completionחייב להיות מצביע למבנה XrCreateTrackableImageDatabaseCompletionANDROID
קודי החזרה
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_FUTURE_INVALID_EXTXR_ERROR_FUTURE_PENDING_EXTXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
הפונקציה xrDestroyTrackableImageDatabaseANDROID מוגדרת כך:
XrResult xrDestroyTrackableImageDatabaseANDROID(
XrTrackableImageDatabaseANDROID database);
תיאורי פרמטרים
-
databaseהוא נקודת האחיזה של XrTrackableImageDatabaseANDROID שצריך להשמיד.
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שקוראים לפונקציה xrDestroyTrackableImageDatabaseANDROID -
databaseחייב להיות נקודת אחיזה חוקית של XrTrackableImageDatabaseANDROID
Thread Safety
- הגישה אל
database, ואל כל נקודות האחיזה הצאצאות, חייבת להיות מסונכרנת באופן חיצוני
קודי החזרה
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_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 כדי ליצור את הכלי למעקב.
שימוש תקין (משתמע)
- צריך להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שמשתמשים ב-XrTrackableImageConfigurationANDROID -
typeחייב להיותXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROID -
nextחייב להיותNULLאו מצביע תקין למבנה הבא בשרשרת מבנים -
databasesחייב להיות מצביע למערך שלdatabaseCountכינויים תקינים של XrTrackableImageDatabaseANDROID - הפרמטר
databaseCountחייב להיות גדול מ-0
ה-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);
תיאורי פרמטרים
-
trackerהוא נקודת האחיזה של XrTrackableTrackerANDROID שאליה מוסיפים אתdatabase. -
databaseהוא נקודת האחיזה של XrTrackableImageDatabaseANDROID שצריך להוסיף אלtracker.
כשמוסיפים XrTrackableImageDatabaseANDROID למעקב, חובה להביא בחשבון את תמונות הרפרנס של מסד הנתונים הזה לצורך זיהוי ומעקב, בנוסף לכל מסד נתונים אחר שנוסף קודם לכן באמצעות xrAddTrackableImageDatabaseANDROID או באמצעות המבנה XrTrackableImageConfigurationANDROID במהלך היצירה הראשונית של המעקב.
שימוש תקין (משתמע)
- צריך להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שקוראים לפונקציה xrAddTrackableImageDatabaseANDROID -
trackerחייב להיות כינוי חוקי של XrTrackableTrackerANDROID -
databaseחייב להיות נקודת אחיזה חוקית של XrTrackableImageDatabaseANDROID - גם
databaseוגםtrackerחייבים להיווצר, להיות מוקצים או להישלף מאותו XrSession
קודי החזרה
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_LIMIT_REACHEDXR_ERROR_OUT_OF_MEMORYXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
הפונקציה xrRemoveTrackableImageDatabaseANDROID מוגדרת כך:
XrResult xrRemoveTrackableImageDatabaseANDROID(
XrTrackableTrackerANDROID tracker,
XrTrackableImageDatabaseANDROID database);
תיאורי פרמטרים
-
trackerהוא נקודת האחיזה של XrTrackableTrackerANDROID שממנה מסירים אתdatabase. -
databaseהוא נקודת האחיזה של XrTrackableImageDatabaseANDROID שצריך להסיר מ-tracker.
כשמסירים XrTrackableImageDatabaseANDROID מ-XrTrackableTrackerANDROID, אסור להשתמש יותר במבני XrTrackableImageDatabaseEntryANDROID של מסד הנתונים הזה לזיהוי ולמעקב. אסור לדווח על רשומות שמתבצע אחריהן מעקב פעיל במסד הנתונים הזה. אסור להשמיד באופן משתמע את נקודת האחיזה XrTrackableImageDatabaseANDROID שהוסרה, כחלק מהפעולה הזו.
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שקוראים לפונקציה xrRemoveTrackableImageDatabaseANDROID -
trackerחייב להיות כינוי חוקי של XrTrackableTrackerANDROID -
databaseחייב להיות נקודת אחיזה חוקית של XrTrackableImageDatabaseANDROID - גם
databaseוגםtrackerחייבים להיווצר, להיות מוקצים או להישלף מאותו XrSession
קודי החזרה
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_VALIDATION_FAILURE
התמונות בתהליך הורדה
הפונקציה xrGetTrackableImageANDROID מוגדרת כך:
XrResult xrGetTrackableImageANDROID(
XrTrackableTrackerANDROID tracker,
const XrTrackableGetInfoANDROID* getInfo,
XrTrackableImageANDROID* trackable);
תיאורי פרמטרים
-
trackerהוא ה-XrTrackableTrackerANDROID שרוצים לשלוח אליו שאילתה. -
getInfoהוא XrTrackableGetInfoANDROID עם המידע שמשמש לקבלת קוד ה-QR שניתן למעקב. -
trackableהוא מצביע למבנה XrTrackableImageANDROID שבו מוחזרת התמונה שניתן לעקוב אחריה.
זמן הריצה חייב להחזיר את הערך XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID אם הסוג שניתן למעקב של XrTrackableANDROID הוא לא XR_TRACKABLE_TYPE_IMAGE_ANDROID , או אם הסוג שניתן למעקב של XrTrackableTrackerANDROID הוא לא XR_TRACKABLE_TYPE_IMAGE_ANDROID .
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שקוראים לפונקציה xrGetTrackableImageANDROID -
trackerחייב להיות כינוי חוקי של XrTrackableTrackerANDROID -
getInfoחייב להיות מצביע למבנה XrTrackableGetInfoANDROID תקין -
trackableחייב להיות מצביע למבנה XrTrackableImageANDROID
קודי החזרה
XR_SUCCESSXR_SESSION_LOSS_PENDING
XR_ERROR_FUNCTION_UNSUPPORTEDXR_ERROR_HANDLE_INVALIDXR_ERROR_INSTANCE_LOSTXR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROIDXR_ERROR_RUNTIME_FAILUREXR_ERROR_SESSION_LOSTXR_ERROR_TIME_INVALIDXR_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).
שימוש תקין (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שמשתמשים ב-XrTrackableImageANDROID -
typeחייב להיותXR_TYPE_TRACKABLE_IMAGE_ANDROID -
nextחייב להיותNULLאו מצביע תקין למבנה הבא בשרשרת מבנים -
trackingStateחייב להיות ערך XrTrackingStateANDROID תקין -
databaseחייב להיות נקודת אחיזה חוקית של XrTrackableImageDatabaseANDROID
טיפול בכשלים
האפליקציה חייבת לבצע סקר לאירוע XrEventDataImageTrackingLostANDROID באמצעות xrPollEvent ואסור להתעלם ממנו.
המבנה של XrEventDataImageTrackingLostANDROID מוגדר כך:
typedef struct XrEventDataImageTrackingLostANDROID {
XrStructureType type;
const void* next;
XrTime time;
} XrEventDataImageTrackingLostANDROID;
תיאורי חברים
-
typeהוא ה-XrStructureType של המבנה הזה. -
nextהואNULLאו מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה. timeXrTime
קבלת האירוע XrEventDataImageTrackingLostANDROID מציינת שהמעקב אחרי התמונה נכשל בגלל תקלה פנימית, וכתוצאה מכך המשאבים הקיימים לא תקפים. האפליקציה חייבת להשמיד את כל נקודות האחיזה של XrTrackableImageDatabaseANDROID וליצור אותן מחדש אם היא רוצה להמשיך במעקב אחרי תמונות. בנוסף, האפליקציה חייבת להשמיד את כל נקודות האחיזה של XrTrackableTrackerANDROID שקשורות למעקב אחרי תמונות, וליצור אותן מחדש אם רוצים להמשיך במעקב אחרי תמונות.
שימוש תקין (משתמע)
- צריך להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שמשתמשים ב-XrEventDataImageTrackingLostANDROID -
typeחייב להיותXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROID -
nextחייב להיותNULLאו מצביע תקין למבנה הבא בשרשרת מבנים
קוד לדוגמה לקבלת תמונות שניתן לעקוב אחריהן
הקוד לדוגמה הבא מדגים איך לקבל תמונות שניתנות למעקב.
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;
}
}
}
סוגי אובייקטים חדשים
פקודות חדשות
- xrAddTrackableImageDatabaseANDROID
- xrCreateTrackableImageDatabaseAsyncANDROID
- xrCreateTrackableImageDatabaseCompleteANDROID
- xrDestroyTrackableImageDatabaseANDROID
- xrGetTrackableImageANDROID
- xrRemoveTrackableImageDatabaseANDROID
מבנים חדשים
- XrCreateTrackableImageDatabaseCompletionANDROID
- XrEventDataImageTrackingLostANDROID
- XrTrackableImageANDROID
- XrTrackableImageConfigurationANDROID
- XrTrackableImageDatabaseCreateInfoANDROID
- XrTrackableImageDatabaseEntryANDROID
הרחבת XrSystemProperties :
ערכי Enums חדשים
קבועי Enum חדשים
XR_ANDROID_TRACKABLES_IMAGE_EXTENSION_NAMEXR_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_ANDROIDXR_TYPE_EVENT_DATA_IMAGE_TRACKING_LOST_ANDROIDXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROIDXR_TYPE_TRACKABLE_IMAGE_ANDROIDXR_TYPE_TRACKABLE_IMAGE_CONFIGURATION_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_CREATE_INFO_ANDROIDXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID
הרחבה של XrTrackableTypeANDROID :
XR_TRACKABLE_TYPE_IMAGE_ANDROID
בעיות
היסטוריית הגרסאות
גרסה 1, 08.04.2025 (דניאל גוטנברג)
- תיאור התוסף הראשוני.