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.
שימוש תקף (משתמע)
-
XR_ANDROID_trackables_imageהתוסף חייב להיות מופעל לפני השימוש ב-XrSystemImageTrackingPropertiesANDROID -
typeחייב להיותXR_TYPE_SYSTEM_IMAGE_TRACKING_PROPERTIES_ANDROID -
nextחייב להיותNULLאו מצביע תקין אל המבנה הבא בשרשרת המבנים
יצירת מסדי נתונים
האפליקציה יכולה ליצור נקודת אחיזה מסוג 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 של הרשומה .
שימוש תקף (משתמע)
- חובה להפעיל את התוסף
XR_ANDROID_trackables_imageלפני שמשתמשים ב-XrTrackableImageDatabaseEntryANDROID -
typeחייב להיותXR_TYPE_TRACKABLE_IMAGE_DATABASE_ENTRY_ANDROID -
nextחייב להיותNULLאו מצביע תקין אל המבנה הבא בשרשרת המבנים -
trackingModeחייב להיות ערך תקין של XrTrackableImageTrackingModeANDROID -
formatחייב להיות ערך תקין של XrTrackableImageFormatANDROID -
bufferחייב להיות מצביע למערך שלbufferSizeערכים שלuint8_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הוא ה-handle שנוצר 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 -
completionmust be a pointer to an XrCreateTrackableImageDatabaseCompletionANDROID structure
קודי החזרה
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הוא ה-handle של 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או מצביע תקין אל המבנה הבא בשרשרת המבנים -
databasesmust be a pointer to an array ofdatabaseCountvalid XrTrackableImageDatabaseANDROID handles - הפרמטר
databaseCountחייב להיות גדול מ-0
הספירה 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);
תיאורי הפרמטרים
-
trackerהוא ה-handle של XrTrackableTrackerANDROID שאליו רוצים להוסיף אתdatabase. -
databaseהוא ה-handle של 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הוא ה-handle של XrTrackableTrackerANDROID שממנו רוצים להסיר אתdatabase. -
databaseהוא ה-handle של 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 תקין -
trackablemust be a pointer to an XrTrackableImageANDROID structure
קודי החזרה
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הוא ה-handle של XrTrackableImageDatabaseANDROID שממנו בוצע המעקב אחר התמונה הזו. -
databaseEntryIndexהוא האינדקס שממופה למערך XrTrackableImageDatabaseCreateInfoANDROID ::entriesשלdatabase. -
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 וליצור אותן מחדש אם היא רוצה להמשיך במעקב אחרי תמונות. בנוסף, האפליקציה חייבת להרוס את כל ה-handlers של 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 :
New Enums
New Enum Constants
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 (דניאל גוטנברג)
- התיאור הראשוני של התוסף.