XR_EXT_spatial_image_tracking

מחרוזת שם

XR_EXT_spatial_image_tracking

סוג התוסף

תוסף למכונה

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

783

גרסה

1

סטטוס האישור

לא אושר

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

XR_EXT_spatial_entity

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

Daniel Guttenberg, Qualcomm
Nihav Jain, Google
Jared Finder, Google
Zhipeng Liu, ByteDance

סקירה כללית

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

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

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

בדרך כלל, אפליקציות משתמשות בתוסף למעקב אחרי תמונות מרחביות באופן הבא:

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

תמיכה בסביבת זמן הריצה

סביבת זמן הריצה חייבת לפרסם את התמיכה שלה ביכולת מעקב אחר תמונות באמצעות xrEnumerateSpatialCapabilitiesEXT על ידי הצגת היכולת הבאה:

  • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

הגדרות אישיות

כדי להפעיל זיהוי ומעקב אחרי תמונות מישוריות, האפליקציה יכולה להעביר מבני XrSpatialCapabilityConfigurationImageTrackingEXT ב-XrSpatialContextCreateInfoEXT :: capabilityConfigs כשקוראים לפונקציה xrCreateSpatialContextAsyncEXT, ולהעביר מערכים של מבני XrSpatialImageTrackingDatabaseEXT בכל XrSpatialCapabilityConfigurationImageTrackingEXT :: imageTrackingDatabases .

יצירת קבוצת תמונות קלט

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

XR_DEFINE_HANDLE(XrSpatialImageTrackingDatabaseEXT)

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

יצירת מסד נתונים למעקב אחרי תמונות מרחביות

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

XrResult xrCreateSpatialImageTrackingDatabaseAsyncEXT(
    XrSession                                   session,
    const XrSpatialImageTrackingDatabaseCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

  • ‫session הוא XrSession שבו מסד הנתונים של מעקב אחר תמונות מרחביות יהיה פעיל.
  • ‫createInfo הוא XrSpatialImageTrackingDatabaseCreateInfoEXT שמשמש לציון הפרמטרים של מסד הנתונים למעקב אחרי תמונות מרחביות.
  • ‫future הוא מצביע ל-XrFutureEXT .

אפליקציה יכולה ליצור נקודת אחיזה (handle) מסוג XrSpatialImageTrackingDatabaseEXT באמצעות הפונקציה xrCreateSpatialImageTrackingDatabaseAsyncEXT ולהגדיר את קבוצות תמונות הרפרנס של מסד הנתונים למעקב אחרי תמונות באמצעות createInfo .

זמן הריצה חייב להחזיר את הערך XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT אם XrSpatialReferenceImageEXT :: format של אחת מתמונות הרפרנס של הקלט לא מופיע ב-xrEnumerateSpatialReferenceImageFormatsEXT .

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

זמן הריצה חייב להחזיר את הערך XR_ERROR_SPATIAL_IMAGE_INVALID_EXT אם המערך planes של XrSpatialReferenceImageEXT של אחת מתמונות הרפרנס של הקלט לא מספק בדיוק את אותו מספר מישורים כמו מספר ערוצי הצבע של format של XrSpatialReferenceImageEXT.

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

הפונקציה הזו מתחילה פעולה אסינכרונית ויוצרת XrFutureEXT תואם, שאפשר להשתמש בו עם xrPollFutureEXT ופונקציות קשורות. ערך ההחזרה של הפונקציה הזו מציין רק אם הפרמטרים היו קבילים לתזמון הפעולה האסינכרונית. פונקציית ההשלמה המתאימה היא xrCreateSpatialImageTrackingDatabaseCompleteEXT , ואפשר להשתמש בה כש-future מהפונקציה הזו נמצא במצב READY, עם פלטים שאוכלסו על ידי הפונקציה הזו במבנה ההשלמה XrCreateSpatialImageTrackingDatabaseCompletionEXT .

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
  • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialImageTrackingDatabaseCreateInfoEXT {
    XrStructureType                      type;
    const void*                          next;
    uint32_t                             spatialReferenceImageCount;
    const XrSpatialReferenceImageEXT*    spatialReferenceImages;
} XrSpatialImageTrackingDatabaseCreateInfoEXT;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫spatialReferenceImageCount הוא מספר הרכיבים במערך spatialReferenceImages.
  • ‫spatialReferenceImages הוא מערך של XrSpatialReferenceImageEXT .

המבנה XrSpatialImageTrackingDatabaseCreateInfoEXT מתאר את המידע ליצירת נקודת אחיזה (handle) של XrSpatialImageTrackingDatabaseEXT.

כל XrSpatialImageTrackingDatabaseEXT חייב להיווצר עם לפחות XrSpatialReferenceImageEXT אחד במערך XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

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

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

XrResult xrCreateSpatialImageTrackingDatabaseCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialImageTrackingDatabaseCompletionEXT* completion);

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

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

לסביבת זמן הריצה אסור לגשת למצביעים של XrSpatialReferenceImagePlaneEXT :: buffer שסופקו על ידי מערך הקלט XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages לקריאה הזו של xrCreateSpatialImageTrackingDatabaseAsyncEXT אחרי שהיא הושלמה. האפליקציה יכולה לפנות את כל הנתונים של XrSpatialReferenceImagePlaneEXT :: buffer אחרי ש-xrCreateSpatialImageTrackingDatabaseAsyncEXT הושלם כדי לצמצם את הזיכרון שבשימוש.

זמן הריצה חייב להחזיר את הערך XR_ERROR_FUTURE_PENDING_EXT אם future לא במצב מוכן. זמן הריצה חייב להחזיר את הערך XR_ERROR_FUTURE_INVALID_EXT אם הפעולה future כבר הושלמה או בוטלה.

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

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

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

typedef struct XrCreateSpatialImageTrackingDatabaseCompletionEXT {
    XrStructureType                      type;
    void*                                next;
    XrResult                             futureResult;
    XrSpatialImageTrackingDatabaseEXT    database;
} XrCreateSpatialImageTrackingDatabaseCompletionEXT;

תיאורי חברים

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

ערכי futureResult:

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
  • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT

אם futureResult הוא קוד הצלחה, database חייב להיות כינוי חוקי. אם database תקין, הוא נשאר תקין רק במהלך מחזור החיים של xrCreateSpatialImageTrackingDatabaseAsyncEXT :: session או עד שהאפליקציה משמידה את database באמצעות xrDestroySpatialImageTrackingDatabaseEXT , המוקדם מביניהם.

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

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

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

XrResult xrDestroySpatialImageTrackingDatabaseEXT(
    XrSpatialImageTrackingDatabaseEXT           database);

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

האפליקציה יכולה להפעיל את הפונקציה xrDestroySpatialImageTrackingDatabaseEXT כדי לשחרר את נקודת האחיזה database ואת המשאבים הבסיסיים כשהיא מסיימת את משימות הגילוי והעדכון של התמונה המרחבית.

האפליקציה יכולה להפעיל את הפונקציה xrDestroySpatialImageTrackingDatabaseEXT לפני שהיא מפעילה את xrDestroySpatialContextEXT . סביבת זמן הריצה לא יכולה לדווח יותר על תמונות שמנוהלות על ידי XrSpatialImageTrackingDatabaseEXT שנהרס. סביבת זמן הריצה חייבת להמשיך לדווח על תמונות שמנוהלות על ידי מסדי נתונים אחרים.

סביבת זמן הריצה חייבת לוודא שתמונות המצב של הגילוי שמוחזרות על ידי xrCreateSpatialDiscoverySnapshotCompleteEXT לא מכילות תמונות שקשורות לכינויים של XrSpatialImageTrackingDatabaseEXT שנהרסו או לא תקינים, גם אם הכינוי נהרס אחרי שהאפליקציה הפעילה את xrCreateSpatialDiscoverySnapshotAsyncEXT . מכיוון שהנתונים בתמונת מצב מרחבית הם לא ניתנים לשינוי, האפליקציה צריכה להשמיד את כל נקודות האחיזה של XrSpatialSnapshotEXT שנוצרו לפני שהיא משמידה את database , אחרת האפליקציה עשויה לקבל נקודות אחיזה לא חוקיות של XrSpatialImageTrackingDatabaseEXT כשמשתמשים ב-xrQuerySpatialComponentDataEXT .

האפליקציה יכולה להפעיל את הפונקציה xrDestroySpatialContextEXT כדי לשחרר את נקודת האחיזה XrSpatialContextEXT לפני שהיא משמידה את נקודות האחיזה XrSpatialImageTrackingDatabaseEXT שבאמצעותן נוצרה XrSpatialContextEXT. סביבת זמן הריצה לא יכולה להרוס באופן משתמע את נקודות האחיזה האלה של XrSpatialImageTrackingDatabaseEXT כשה-XrSpatialContextEXT נהרס.

ניהול משך החיים של XrSpatialContextEXT ו-XrSpatialImageTrackingDatabaseEXT באופן עצמאי מאפשר לאפליקציות לעשות שימוש חוזר בכינויים של XrSpatialImageTrackingDatabaseEXT שנוצרו בעבר, בלי צורך לבצע שוב את הליך היצירה היקר.

לדוגמה, אם משמידים XrSpatialContextEXT ויוצרים מחדש XrSpatialContextEXT אחר עם אותו XrSpatialImageTrackingDatabaseEXT, אפשר להשהות את המעקב אחר התמונות ולהמשיך אותו בלי לבצע הליך אתחול נוסף.

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

Thread Safety

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

קודי החזרה

הצלחה

  • XR_SUCCESS

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

תמיכה בפורמטים של תמונות קלט

האפליקציות צריכות להפעיל את xrEnumerateSpatialReferenceImageFormatsEXT כדי לקבל את רשימת הפורמטים הנתמכים של תמונות הרפרנס.

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

XrResult xrEnumerateSpatialReferenceImageFormatsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    formatCapacityInput,
    uint32_t*                                   formatCountOutput,
    XrSpatialReferenceImageFormatEXT*           formats);

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

  • ‫instance הוא כינוי ל-XrInstance .
  • ‫systemId הוא ה-XrSystemId שפורמטי תמונות הרפרנס שלו יפורטו.
  • ‫capability הוא XrSpatialCapabilityEXT שעבורו יפורטו פורמטי תמונות הרפרנס לקלט.
  • ‫formatCapacityInput הוא הקיבולת של המערך formats, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
  • formatCountOutput הוא מספר הפורמטים, או הקיבולת הנדרשת במקרה ש-formatCapacityInput לא מספיק.
  • ‫formats הוא מערך של XrSpatialReferenceImageFormatEXT . הערך של NULL יכול להיות formatCapacityInput אם הוא 0.
  • בקטע פרמטרים של שטח אחסון זמני יש תיאור מפורט של אחזור הגודל הנדרש של formats.

האפליקציה יכולה למנות את רשימת פורמטי תמונות הרפרנס לקלט שנתמכים על ידי XrSystemId נתון עבור XrSpatialCapabilityEXT נתון באמצעות xrEnumerateSpatialReferenceImageFormatsEXT .

זמן הריצה לא יכול למנות את הפורמטים של התוספים שלא מופעלים עבור instance .

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

קודי החזרה

הצלחה

  • XR_SUCCESS

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

כדי לראות את הרשימה המלאה של כל הפורמטים של תמונות הרפרנס שנתמכים על ידי כל תוסף, אפשר לעיין במאמר XrSpatialReferenceImageFormatEXT.

typedef enum XrSpatialReferenceImageFormatEXT {
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT = 1,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT = 2,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT = 3,
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialReferenceImageFormatEXT;

הספירה XrSpatialReferenceImageFormatEXT מזהה את פורמטי תמונות הרפרנס לקלט שסביבת זמן הריצה עשויה לתמוך בהם.

חייבת להיות תמיכה לפחות בערך XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT ובערך XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT .

המשמעות של הערכים:

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

  • ‫XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT — מאגר נתונים זמני של RGBA. הפורמט לא מבטיח את הפריסה של נתוני הפיקסלים בזיכרון. חובה לגשת לפיקסלים באמצעות המטא-נתונים שסופקו על ידי מבני XrSpatialReferenceImagePlaneEXT התואמים. לכל ערוץ צבע של פיקסל יש גודל של 8 ביט, כך שהגודל של כל פיקסל הוא 32 ביט.
  • ‫XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGB_888_EXT – מאגר RGB. הפורמט לא מבטיח את הפריסה של נתוני הפיקסלים בזיכרון. חובה לגשת לפיקסלים באמצעות המטא-נתונים שסופקו על ידי מבני XrSpatialReferenceImagePlaneEXT התואמים. לכל ערוץ צבע של פיקסל יש גודל של 8 ביט, כך שהגודל של כל פיקסל הוא 24 ביט.
  • ‫XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT — מאגר YUV עם תת-דגימה של Chroma בתבנית 4:2:0. הפורמט לא מבטיח את הפריסה של נתוני הפיקסלים בזיכרון. חובה לגשת לפיקסלים באמצעות המטא-נתונים שסופקו על ידי מבני XrSpatialReferenceImagePlaneEXT התואמים. לכל ערוץ צבע של פיקסל RGB מפוענח יש גודל של 8 ביט, כך שכל פיקסל הוא בגודל 24 ביט.

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

התוסף הזה מספק מבנים אופציונליים שהאפליקציה יכולה להשתמש בהם כדי להגדיר את יכולת מעקב התמונות.

אופטימיזציה של תמונות סטטיות

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

typedef struct XrSpatialImageStaticOptimizationEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           optimizeForStaticImage;
} XrSpatialImageStaticOptimizationEXT;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • optimizeForStaticImage הוא XrBool32 שמציין אם התמונות זזות או לא. הערך XR_TRUE מציין שהתמונות לא זזות.

אם XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT נספר על ידי xrEnumerateSpatialCapabilityFeaturesEXT עבור היכולת XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, האפליקציה יכולה לשרשר את XrSpatialImageStaticOptimizationEXT לשרשרת XrSpatialImageTrackingDatabaseCreateInfoEXT :: next, או XrSpatialReferenceImageEXT :: next .

אם האפליקציה משרשרת את XrSpatialImageStaticOptimizationEXT למבנה XrSpatialImageTrackingDatabaseCreateInfoEXT, סביבת זמן הריצה חייבת להניח שכל התמונות של XrSpatialImageTrackingDatabaseEXT הן סטטיות אם optimizeForStaticImage מוגדר ל-XR_TRUE . בהתאם, זמן הריצה חייב להניח שכל התמונות של XrSpatialImageTrackingDatabaseEXT לא סטטיות אם optimizeForStaticImage מוגדר כ-XR_FALSE .

אם האפליקציה משרשרת את XrSpatialImageStaticOptimizationEXT למבנה XrSpatialReferenceImageEXT, זמן הריצה חייב להניח שתמונת הרפרנס הזו היא סטטית אם optimizeForStaticImage מוגדר ל-XR_TRUE . בהתאם, זמן הריצה חייב להניח שתמונת הרפרנס הזו לא סטטית אם optimizeForStaticImage מוגדר ל-XR_FALSE . שרשור המבנה XrSpatialImageStaticOptimizationEXT למבנה XrSpatialReferenceImageEXT מקבל עדיפות על פני שרשור שלו למבנה XrSpatialImageTrackingDatabaseCreateInfoEXT.

אם XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT לא מופיע ב-xrEnumerateSpatialCapabilityFeaturesEXT עבור היכולת XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT והאפליקציה משרשרת מבנה XrSpatialImageStaticOptimizationEXT לאחת מהשרשראות הבאות הרלוונטיות, זמן הריצה חייב להחזיר XR_ERROR_VALIDATION_FAILURE מ-xrCreateSpatialImageTrackingDatabaseAsyncEXT .

יכול להיות שזה יאפשר לזמן הריצה ליצור תנוחה וגודל מדויקים יותר.

יכול להיות שזה יאפשר לסביבת זמן הריצה להפחית את צריכת החשמל.

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

רוחב תמונת הרפרנס

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

typedef struct XrSpatialImageSizeEXT {
    XrStructureType    type;
    const void*        next;
    float              physicalWidth;
} XrSpatialImageSizeEXT;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫physicalWidth הוא ערך מסוג float שמייצג את הרוחב הפיזי במטרים שרוצים להגדיר.

אם XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT נספר על ידי xrEnumerateSpatialCapabilityFeaturesEXT עבור היכולת XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, האפליקציה יכולה לשרשר את XrSpatialImageSizeEXT אל XrSpatialImageTrackingDatabaseCreateInfoEXT :: next או אל XrSpatialReferenceImageEXT :: next .

אם האפליקציה משרשרת את XrSpatialImageSizeEXT למבנה XrSpatialImageTrackingDatabaseCreateInfoEXT, זמן הריצה חייב להניח שלכל התמונות של XrSpatialImageTrackingDatabaseEXT יש רוחב של physicalWidth מטרים וגובה בהתאם ליחס הגובה-רוחב שסופק באופן משתמע דרך XrSpatialReferenceImageEXT :: width ו-XrSpatialReferenceImageEXT :: height .

אם האפליקציה משרשרת את XrSpatialImageSizeEXT למבנה XrSpatialReferenceImageEXT, זמן הריצה חייב להניח שלתמונת הרפרנס הזו יש רוחב של physicalWidth מטרים וגובה בהתאם ליחס הגובה-רוחב כפי שסופק באופן משתמע דרך XrSpatialReferenceImageEXT :: width ו-XrSpatialReferenceImageEXT :: height . שרשור המבנה XrSpatialImageSizeEXT למבנה XrSpatialReferenceImageEXT מקבל עדיפות על פני שרשור שלו למבנה XrSpatialImageTrackingDatabaseCreateInfoEXT.

יכול להיות שזה יאפשר לזמן הריצה להחזיר תנוחה וגודל מדויקים יותר.

סביבת זמן הריצה חייבת לכלול את XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT או את XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT או את שניהם.

אם XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT נספר על ידי xrEnumerateSpatialCapabilityFeaturesEXT, זמן הריצה חייב לספק גודלי תמונות באופן אוטומטי לתמונות שהאפליקציה לא סיפקה להן מבני XrSpatialImageSizeEXT כחלק מהשרשראות הבאות הרלוונטיות.

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

אם XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT לא נספר על ידי xrEnumerateSpatialCapabilityFeaturesEXT, האפליקציה חייבת לקשר מבני XrSpatialImageSizeEXT לשרשראות הבאות הרלוונטיות, כך שלכל התמונות יהיה גודל מפורש שסופק להן. אחרת, זמן הריצה חייב להחזיר את XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT מ-xrCreateSpatialImageTrackingDatabaseAsyncEXT .

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

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

typedef struct XrSpatialCapabilityConfigurationImageTrackingEXT {
    XrStructureType                             type;
    const void*                                 next;
    XrSpatialCapabilityEXT                      capability;
    uint32_t                                    enabledComponentCount;
    const XrSpatialComponentTypeEXT*            enabledComponents;
    uint32_t                                    imageTrackingDatabaseCount;
    const XrSpatialImageTrackingDatabaseEXT*    imageTrackingDatabases;
} XrSpatialCapabilityConfigurationImageTrackingEXT;

תיאורי חברים

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫capability הוא XrSpatialCapabilityEXT וחייב להיות XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT .
  • ‫enabledComponentCount הוא uint32_t שמציין את מספר הרכיבים ב-enabledComponents .
  • ‫enabledComponents הוא מערך של XrSpatialComponentTypeEXT שמציין את הרכיבים שצריך להפעיל בשביל היכולת הזו.
  • ‫imageTrackingDatabaseCount הוא unint32_t שמציין את מספר הרכיבים ב-imageTrackingDatabases .
  • ‫imageTrackingDatabases הוא מערך של נקודות אחיזה מסוג XrSpatialImageTrackingDatabaseEXT שמציינות את מסדי הנתונים של מעקב אחר תמונות שצריך להפעיל בהקשר המרחבי.

אם יש תמיכה במעקב אחר תמונות, סביבת זמן הריצה חייבת להפעיל מעקב אחר תמונות אם מבנה XrSpatialCapabilityConfigurationImageTrackingEXT מועבר ב-XrSpatialContextCreateInfoEXT :: capabilityConfigs כשקוראים ל-xrCreateSpatialContextAsyncEXT .

המבנה XrSpatialCapabilityConfigurationImageTrackingEXT מאפשר לאפליקציה לגלות את תמונות הרפרנס שמיוצגות על ידי נקודות האחיזה של XrSpatialImageTrackingDatabaseEXT ב-imageTrackingDatabases .

זמן הריצה חייב להחזיר את הערך XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT אם XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT לא מופיע ברשימה של xrEnumerateSpatialCapabilitiesEXT .

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

  • ‫ חובה להפעיל את התוסף XR_EXT_spatial_image_tracking לפני שמשתמשים ב-XrSpatialCapabilityConfigurationImageTrackingEXT
  • type חייב להיות XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
  • next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
  • capability חייב להיות ערך XrSpatialCapabilityEXT תקין
  • ‫ enabledComponents חייב להיות מצביע למערך של ערכי XrSpatialComponentTypeEXT תקינים מסוג enabledComponentCount
  • ‫ imageTrackingDatabases חייב להיות מצביע למערך של imageTrackingDatabaseCount נקודות אחיזה חוקיות של XrSpatialImageTrackingDatabaseEXT
  • ‫ הפרמטר enabledComponentCount חייב להיות גדול מ-0
  • ‫ הפרמטר imageTrackingDatabaseCount חייב להיות גדול מ-0

תמונת רפרנס מרחבית

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

typedef struct XrSpatialReferenceImagePlaneEXT {
    uint32_t    bufferSize;
    uint8_t*    buffer;
    uint32_t    rowStride;
    uint32_t    pixelStride;
} XrSpatialReferenceImagePlaneEXT;

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

  • ‫bufferSize הוא הגודל של המערך buffer.
  • ‫buffer הוא מערך של נתוני uint8_t שמייצגים את נתוני המישור.
  • ‫rowStride הוא המרחק בבייטים בין שתי נקודות התחלה של שורות נתונים עוקבות של פיקסלים.
  • ‫pixelStride הוא המרחק בבייטים בין שני פיקסלים עוקבים.

סביבת זמן הריצה חייבת לגשת אל buffer בהתאם לתבניות שמספקים הפרמטרים rowStride ו-pixelStride.

האפליקציה חייבת להגדיר את rowStride ואת pixelStride כך שרק פיקסלים משמעותיים של XrSpatialReferenceImagePlaneEXT יחולצו על ידי זמן הריצה.

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

  • ‫ חובה להפעיל את התוסף XR_EXT_spatial_image_tracking לפני שמשתמשים ב-XrSpatialReferenceImagePlaneEXT
  • ‫ buffer חייב להיות מצביע למערך של ערכי bufferSize uint8_t
  • ‫ הפרמטר bufferSize חייב להיות גדול מ-0

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

typedef struct XrSpatialReferenceImageEXT {
    XrStructureType                           type;
    const void*                               next;
    uint32_t                                  width;
    uint32_t                                  height;
    XrSpatialReferenceImageFormatEXT          format;
    uint32_t                                  planeCount;
    const XrSpatialReferenceImagePlaneEXT*    planes;
} XrSpatialReferenceImageEXT;

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

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫width הוא רוחב הפיקסלים של תמונת הרפרנס.
  • ‫height הוא הגובה בפיקסלים של תמונת הרפרנס.
  • ‫format הוא XrSpatialReferenceImageFormatEXT שמייצג את הפורמט של התמונה.
  • ‫planeCount הוא מספר הרכיבים במערך planes.
  • ‫planes הוא מערך של מבני XrSpatialReferenceImagePlaneEXT שמייצגים את המישורים של נתוני התמונה.

האפליקציה יכולה ליצור מבנה אחד או יותר של XrSpatialReferenceImageEXT, שכל אחד מהם מייצג תמונת רפרנס אחת של קלט שמועברת לפונקציה xrCreateSpatialImageTrackingDatabaseAsyncEXT דרך XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages כשיוצרים נקודת אחיזה (handle) של XrSpatialImageTrackingDatabaseEXT.

האפליקציה חייבת לספק את הנתונים של XrSpatialReferenceImagePlaneEXT :: buffer בסדר פיקסלים משמאל לימין ומלמעלה למטה.

האפליקציה חייבת לספק מבנה XrSpatialReferenceImagePlaneEXT במערך XrSpatialReferenceImageEXT :: planes לכל ערוץ צבע של XrSpatialReferenceImageEXT :: format .

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

רכיבים מובטחים

סביבת זמן ריצה שתומכת ב-XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT חייבת לספק את הרכיבים המרחביים הבאים כרכיבים מובטחים של כל הישויות שמתגלות על ידי היכולות האלה, ולמנות אותם ב-xrEnumerateSpatialCapabilityComponentTypesEXT :

  • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  • XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

רכיב תמונה דו-ממדית

מבנה של רשימת רכיבים לשאילתת נתונים

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

typedef struct XrSpatialComponentImage2DListEXT {
    XrStructureType             type;
    const void*                 next;
    uint32_t                    imageCount;
    XrSpatialImage2DDataEXT*    images;
} XrSpatialComponentImage2DListEXT;

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

  • ‫type הוא ה-XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
  • ‫imageCount הוא מספר הרכיבים במערך images.
  • images הוא מערך של XrSpatialImage2DDataEXT .

זמן הריצה חייב להחזיר את הערך XR_ERROR_VALIDATION_FAILURE מ-xrQuerySpatialComponentDataEXT אם XrSpatialComponentImage2DListEXT נמצא בשרשרת XrSpatialComponentDataQueryResultEXT :: next, אבל XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT לא נכלל ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes .

זמן הריצה חייב להחזיר את הערך XR_ERROR_SIZE_INSUFFICIENT מ-xrQuerySpatialComponentDataEXT אם imageCount קטן מ-XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

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

נתוני רכיבים

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

typedef struct XrSpatialImage2DDataEXT {
    XrSpatialImageTrackingDatabaseEXT    imageTrackingDatabase;
    uint32_t                             referenceImageIndex;
} XrSpatialImage2DDataEXT;

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

האפליקציה יכולה להשתמש ב-imageTrackingDatabase כדי לזהות איזה XrSpatialImageTrackingDatabaseEXT שנוצר בעבר מכיל את תמונת הרפרנס של המבנה הזה של XrSpatialImage2DDataEXT. ב-XrSpatialImageTrackingDatabaseEXT הזה, האפליקציה יכולה להשתמש ב-referenceImageIndex כדי לזהות את XrSpatialReferenceImageEXT של המבנה הזה של XrSpatialImage2DDataEXT, על ידי התאמה שלו לסדר הקלט של המערך XrSpatialImageTrackingDatabaseCreateInfoEXT :: spatialReferenceImages.

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

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

הגדרות אישיות

אם XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT מופיע ב-XrSpatialCapabilityComponentTypesEXT :: componentTypes עבור יכולת מסוימת, האפליקציה יכולה להפעיל אותה על ידי הכללת ערך ה-enum ברשימה XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. הרכיב הזה לא דורש הגדרה מיוחדת כדי להיכלל בשרשרת הבאה של XrSpatialCapabilityConfigurationBaseHeaderEXT .

רכיב דו-ממדי מוגבל

הרכיב הדו-ממדי התחום מספק את המרכז וההיקף של התמונה המרחבית שמיוצגת על ידי הישות שעליה הוא נמצא. מידע נוסף על הרכיב "דו-ממדי מוגבל" זמין במאמר דו-ממדי מוגבל.

קוד לדוגמה

חיפוש תמונות מרחביות ושאילתות על נתוני רכיבים

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

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

uint32_t capabilityCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCountOutput, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCountOutput);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilities.size(), &capabilityCountOutput, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT) == capabilities.end()) {
  // Image tracking not supported
}

XrSpatialCapabilityComponentTypesEXT imageTrackingComponents{XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));
std::vector<XrSpatialComponentTypeEXT> imageTrackingCapabilityComponents(imageTrackingComponents.componentTypeCountOutput);
imageTrackingComponents.componentTypes = imageTrackingCapabilityComponents.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, &imageTrackingComponents));

if (std::find(imageTrackingCapabilityComponents.begin(), imageTrackingCapabilityComponents.end(), XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT) == imageTrackingCapabilityComponents.end()) {
  // The image2d component is not supported
}

uint32_t capabilityFeatureCountOutput = 0;
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &capabilityFeatureCountOutput, nullptr));
std::vector<XrSpatialCapabilityFeatureEXT> capabilityFeatures(capabilityFeatureCountOutput);
CHK_XR(xrEnumerateSpatialCapabilityFeaturesEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, capabilityFeatures.size(), &capabilityFeatureCountOutput, capabilityFeatures.data()));

// Helper function to query optional feature support
const auto supportsFeature = [&capabilityFeatures](XrSpatialCapabilityFeatureEXT feature) {
  return std::find(capabilityFeatures.begin(), capabilityFeatures.end(), feature) != capabilityFeatures.end();
};

// supported state for optional features
const bool supportsAutomaticScaleEstimation = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT);
const bool supportsStaticImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT);
const bool supportsFixedSizeImages = supportsFeature(XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT);

uint32_t formatCountOutput = 0;
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, 0, &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(instance, systemId, XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT, formats.size(), &formatCountOutput, formats.data()));

if (std::find(formats.begin(), formats.end(), XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT) == formats.end()) {
  // The desired format is not supported
}

// Helper function to wait for XrFutureEXT completion
auto waitUntilReady = [&](XrFutureEXT future) {
  XrFuturePollInfoEXT pollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
  XrFuturePollResultEXT pollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
  pollInfo.future = future;
  do {
    // sleep(1);
    CHK_XR(xrPollFutureEXT(instance, &pollInfo, &pollResult));
  } while (pollResult.state != XR_FUTURE_STATE_READY_EXT);
};

// Data/metadata about reference images (identifiers, 3D models, trigger functions, etc.)
std::vector<std::string> referenceImageIdentifiers;

XrSpatialImageTrackingDatabaseEXT imageTrackingDatabase{};
{
  uint32_t imgSize; // preloaded interleaved RGBA buffer size
  uint8_t* img; // preloaded interleaved RGBA buffer data

  // interleaved RGBA buffer memory layout and buffer positions

  // first row of pixels
  // img[0] | img[1] | img[2] | img[3] | img[0]+pStride | img[1]+pStride | ...
  //  R0    |   G0   |   B0   |   A0   |       R1       |       G1       | ...

  // second row of pixels
  // img[0]+rStride | img[1]+rStride | img[2]+rStride | img[3]+rStride | img[0]+rStride+pStride | ...
  //      R640      |      G640      |      B640      |      A640      |          R641          | ...

  XrSpatialReferenceImagePlaneEXT spatialReferenceImagePlanes[4];

  for (int i = 0; i < 4; ++i) { // for each plane (0=R, 1=G, 2=B, 3=A)
    spatialReferenceImagePlanes[i].buffer = img + i; // set each plane buffer pointer to the first pixel of the plane
    spatialReferenceImagePlanes[i].bufferSize = imgSize - i; // adjust remeinaing buffer size according to offset applied
    spatialReferenceImagePlanes[i].rowStride = 640 * 4; // set byte offset to start of next row for this plane
    spatialReferenceImagePlanes[i].pixelStride = 4; // set byte offset to next pixel for this plane
  }

  XrSpatialReferenceImageEXT spatialReferenceImage{XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
  spatialReferenceImage.width = 640;
  spatialReferenceImage.height = 480;
  spatialReferenceImage.format = XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT;
  spatialReferenceImage.planeCount = 4;
  spatialReferenceImage.planes = spatialReferenceImagePlanes;

  referenceImageIdentifiers.emplace_back("MyReferenceImage");

  // Helper function to append to the next chain
  XrBaseOutStructure* appendTo = reinterpret_cast<XrBaseOutStructure*>(&spatialReferenceImage);
  const auto appendToNextChain = [&appendTo](XrBaseOutStructure* toAppend) {
    appendTo->next = toAppend;
    appendTo = toAppend;
  };

  XrSpatialImageSizeEXT imageSize{XR_TYPE_SPATIAL_IMAGE_SIZE_EXT};
  imageSize.physicalWidth = 0.1f;

  if (!supportsAutomaticScaleEstimation) {
    if (supportsFixedSizeImages) {
      appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageSize));
    }
  }

  XrSpatialImageStaticOptimizationEXT imageStaticOptimization{XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT};
  imageStaticOptimization.optimizeForStaticImage = XR_TRUE;

  if (supportsStaticImages) {
    appendToNextChain(reinterpret_cast<XrBaseOutStructure*>(&imageStaticOptimization));
  }

  XrSpatialImageTrackingDatabaseCreateInfoEXT spatialImageTrackingDatabaseCreateInfo{XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT};
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImages = &spatialReferenceImage;
  spatialImageTrackingDatabaseCreateInfo.spatialReferenceImageCount = 1;

  XrFutureEXT createImageTrackingDatabaseFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialImageTrackingDatabaseAsyncEXT(session, &spatialImageTrackingDatabaseCreateInfo, &createImageTrackingDatabaseFuture));

  waitUntilReady(createImageTrackingDatabaseFuture);

  XrCreateSpatialImageTrackingDatabaseCompletionEXT imageTrackingCompletion{XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialImageTrackingDatabaseCompleteEXT(session, createImageTrackingDatabaseFuture, &imageTrackingCompletion));
  if (imageTrackingCompletion.futureResult != XR_SUCCESS) {
    // Error, image tracking database creation failed
  }

  imageTrackingDatabase = imageTrackingCompletion.database;
}

XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 2> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT
  };

  // Configure the image tracking capability for the spatial context
  XrSpatialCapabilityConfigurationImageTrackingEXT imageTrackingCapabilityConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT};
  imageTrackingCapabilityConfig.capability = XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT;
  imageTrackingCapabilityConfig.enabledComponentCount = enabledComponents.size();
  imageTrackingCapabilityConfig.enabledComponents = enabledComponents.data();
  imageTrackingCapabilityConfig.imageTrackingDatabaseCount = 1;
  imageTrackingCapabilityConfig.imageTrackingDatabases = &imageTrackingDatabase;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
  capabilityConfigs.push_back(reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&imageTrackingCapabilityConfig));

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    // Error, spatial context creation failed
  }

  spatialContext = completion.spatialContext;
}

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  // We want to look for entities that have the following components
  std::array<XrSpatialComponentTypeEXT, 2> snapshotComponents {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = discoveryFuture;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for the bounded2d component data
    XrSpatialComponentTypeEXT componentsToQuery[] = {XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT, XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT};
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = componentsToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialBounded2DDataEXT> bounded2d(queryResult.entityIdCountOutput);
    XrSpatialComponentBounded2DListEXT boundsList{XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT};
    boundsList.boundCount = bounded2d.size();
    boundsList.bounds = bounded2d.data();
    queryResult.next = &boundsList;

    std::vector<XrSpatialImage2DDataEXT> image2d(queryResult.entityIdCountOutput);
    XrSpatialComponentImage2DListEXT imagesList{XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT};
    imagesList.imageCount = image2d.size();
    imagesList.images = image2d.data();
    queryResult.next = &imagesList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialImage2DDataEXT& currentImage2d = image2d[i];
        const std::string& currentReferenceImageIdentifier = referenceImageIdentifiers[currentImage2d.referenceImageIndex];
        std::cout << currentReferenceImageIdentifier << std::endl; // Outputs the "MyReferenceImage" string the app defined previously; could be any other assocatied data or action.

        // Access bounded2d[i] for image bounds
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // For every frame in frame loop

  XrFrameState frameState;  // Previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata = *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

// Unload spatial image tracking resources internally
CHK_XR(xrDestroySpatialImageTrackingDatabaseEXT(imageTrackingDatabase));

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

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

קבועי Enum חדשים

  • XR_EXT_SPATIAL_IMAGE_TRACKING_EXTENSION_NAME
  • XR_EXT_spatial_image_tracking_SPEC_VERSION

  • הרחבה של XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_EXT

  • הרחבת XrResult :

    • XR_ERROR_SPATIAL_IMAGE_FORMAT_UNSUPPORTED_EXT
    • XR_ERROR_SPATIAL_IMAGE_INVALID_EXT
    • XR_ERROR_SPATIAL_IMAGE_SIZE_MISSING_EXT

  • הרחבה של XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

  • הרחבה של XrSpatialCapabilityFeatureEXT :

    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT
    • XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

  • הרחבה של XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

  • הרחבה של XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_IMAGE_TRACKING_DATABASE_COMPLETION_EXT
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_IMAGE_TRACKING_EXT
    • XR_TYPE_SPATIAL_COMPONENT_IMAGE_2D_LIST_EXT
    • XR_TYPE_SPATIAL_IMAGE_SIZE_EXT
    • XR_TYPE_SPATIAL_IMAGE_STATIC_OPTIMIZATION_EXT
    • XR_TYPE_SPATIAL_IMAGE_TRACKING_DATABASE_CREATE_INFO_EXT
    • XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT

בעיות

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

  • גרסה 1, 22 באפריל 2025 (דניאל גוטנברג, Qualcomm)

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