XR_EXT_spatial_container

מחרוזת שם

XR_EXT_spatial_container

סוג התוסף

תוסף למכונה

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

811

גרסה

1

סטטוס האישור

לא אושר

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

OpenXR 1.0

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

2026-08-06

סטטוס IP

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

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

Jared Finder, Google
Andreas Loeve Selvik, Meta Platforms
Lachlan Ford, Google
Cass Everitt, Meta Platforms
Adam Gousetis, Meta Platforms
Ankur Agrawal, Unity Technologies
Bjorn Swenson, LÖVR
Denny Rönngren, Varjo Technologies
Fredia Huya-Kouadio, Godot Engine
Guodong Rong, Meta Platforms
Jakob Bornecrantz, NVIDIA
Jian Zhang, ByteDance
John Kearney, Meta Platforms
Jonathan Wright, Meta Platforms
Junfeng She, ByteDance
Kenny Vercaemer, Google
Kurtis Eveleigh, Qualcomm
Mauricio Narvaez, Meta Platforms
Nathan Nuber, Valve Corporation
Nihav Jain, Google
Nikita Lutsenko, Meta Platforms
Praveen Babu J D, ByteDance
Rylie Pavlik, Collabora
Salar Khan, Google
Shuai Liu, ByteDance
Walter Luh, Meta Platforms
Yin Li, Microsoft
Zhipeng Liu, ByteDance

סקירה כללית

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

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

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

התוסף הזה תומך בסוגים החדשים האלה של חוויות עם גבולות מרחביים, בנוסף לחוויות OpenXR סוחפות קיימות. בחוויות OpenXR מוגבלות מותר להציג תוכן תלת-ממדי חלקי (לוחות שטוחים עם עומק קל) או נפחים שמארחים תוכן תלת-ממדי מלא. חוויות סוחפות ב-OpenXR הן האפליקציות הסוחפות הקיימות במסך מלא שנתמכות מאז OpenXR 1.0. האפליקציות יכולות לעבור בין שני סוגי התוכן.

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

שימוש בקונטיינרים מרחביים

‫XrSpatialContainerEXT הוא כינוי שמייצג מאגר מרחבי.

XR_DEFINE_HANDLE(XrSpatialContainerEXT)

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

1. יוצרים קונטיינר מרחבי באמצעות xrCreateSpatialContainerEXT .
2. משנים את המצב של הקונטיינר לתצוגה ראשונית, למשל את מצב הגבולות שלו.
3. מבקשים מסביבת זמן הריצה להציג את הקונטיינר באמצעות xrRequestSpatialContainerVisibleEXT .
4. מחכים עד שסביבת זמן הריצה תהיה מוכנה להציג את הקונטיינר. כשהסביבה מוכנה, היא מוסיפה לתור אירוע XrEventDataSpatialContainerVisibleChangedEXT עם visible שמוגדר ל-XR_TRUE .
5. מתחילים את העיבוד של המאגר המרחבי.

כדי להסיר קונטיינר מרחבי:

1. מבקשים מסביבת זמן הריצה להסתיר את מאגר התגים באמצעות xrRequestSpatialContainerVisibleEXT .
2. ממתינים עד שסביבת זמן הריצה תסיים להסתיר את מאגר התגים. כשהקונטיינר מוסתר לגמרי, זמן הריצה מוסיף לתור אירוע XrEventDataSpatialContainerVisibleChangedEXT עם visible שמוגדר כ-XR_FALSE .
3. סיום העיבוד של המאגר המרחבי.
4. משמידים את הקונטיינר באמצעות xrDestroySpatialContainerEXT .

הערה

התוסף הזה מתוכנן כך שהוא מעביר את ניהול החשיפה והמיקוד לקונטיינרים מרחביים נפרדים. מכיוון שהסשן כולו כבר לא מייצג אובייקט גלוי או ממוקד אחד, הסשן לא עובר דרך מכונת המצבים הרגילה של OpenXR‏ (READY, ‏ SYNCHRONIZED, ‏ VISIBLE, ‏ FOCUSED). במקום זאת, הסשן נשאר במצב XR_SESSION_STATE_IDLE למשך כל הזמן שהוא פעיל, והכללים בקטע שינויים במצב הסשן מציינים איך פעולות הליבה של OpenXR ממופות למצב הזה.

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

הפונקציה xrCreateSpatialContainerEXT יוצרת מאגר מרחבי חדש.

XrResult xrCreateSpatialContainerEXT(
    XrSession                                   session,
    const XrSpatialContainerCreateInfoEXT*      createInfo,
    XrSpatialContainerEXT*                      spatialContainer);

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

• ‫session הוא ה-XrSession שיוצר את מאגר התגים המרחבי.
• ‫createInfo הוא מצביע ל-XrSpatialContainerCreateInfoEXT שמכיל פרמטרים ליצירת מאגר המידע המרחבי.
• ‫spatialContainer הוא מצביע לכינוי שבו מוחזר ה-XrSpatialContainerEXT שנוצר.

XrSpatialContainerEXT חדש שנוצר חייב להיות לא גלוי, לא ניתן לאינטראקציה ובמצב גבולות XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT . אפליקציה שרוצה שקונטיינר מרחבי יתחיל במצב אימרסיבי יכולה לבקש מצב גבולות של XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT לפני שהיא מבקשת להציג קונטיינר מרחבי.

זמני ריצה חייבים להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם אחד מהממדים של XrSpatialContainerCreateInfoEXT :: suggestedBounds הוא שלילי, אינסופי או לא מספר. סביבות זמן ריצה חייבות להחזיר את הערך XR_ERROR_LIMIT_REACHED אם אפליקציה מנסה ליצור יותר מאגרים מרחביים מהמספר שצוין ב-XrSystemSpatialContainerPropertiesEXT :: maxSpatialContainerCount . אם לא הופעלו קונטיינרים מרחביים בסשן הזה , סביבות זמן הריצה חייבות להחזיר את הערך XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT .

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

• חובה להפעיל את התוסף XR_EXT_spatial_container לפני שקוראים ל-xrCreateSpatialContainerEXT
• ‫ session חייב להיות כינוי תקין של XrSession
• ‫ createInfo חייב להיות מצביע למבנה XrSpatialContainerCreateInfoEXT תקין
• ‫ spatialContainer חייב להיות מצביע לכינוי XrSpatialContainerEXT

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

נכשל

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

ה-XrSpatialContainerCreateInfoEXT מועבר אל xrCreateSpatialContainerEXT כדי ליצור קונטיינר מרחבי.

typedef struct XrSpatialContainerCreateInfoEXT {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialContainerGraphicsPresentationEXT    graphicsPresentation;
    XrExtent3Df                                  suggestedBounds;
} XrSpatialContainerCreateInfoEXT;

תיאור המשתמש

• ‫type הוא ה-XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
• ‫graphicsPresentation הוא XrSpatialContainerGraphicsPresentationEXT שמתאר איך הקונטיינר המרחבי הזה מציג גרפיקה.
• ‫suggestedBounds הוא XrExtent3Df שמתאר את המידות המבוקשות של המאגר המרחבי במטרים.

אפליקציה שאין לה העדפה לגבי הגודל שלה יכולה להגדיר את suggestedBounds לערך {0, 0, 0}. זמן ריצה עשוי להתעלם מהבקשה suggestedBounds .

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSpatialContainerCreateInfoEXT
• type חייב להיות XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
• graphicsPresentation חייב להיות ערך XrSpatialContainerGraphicsPresentationEXT תקין

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

typedef struct XrEventDataSpatialContainerClosedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerClosedEXT;

תיאור המשתמש

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

קבלת האירוע XrEventDataSpatialContainerClosedEXT מציינת שזמן הריצה לא יכול יותר להציג מאגר מרחבי, למשל כי המשתמש לחץ על כפתור "סגירה" או שהסשן נכנס למצב XR_SESSION_STATE_LOSS_PENDING.

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

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrEventDataSpatialContainerClosedEXT
• type חייב להיות XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

הפונקציה xrDestroySpatialContainerEXT משמידה מאגר מרחבי קיים.

XrResult xrDestroySpatialContainerEXT(
    XrSpatialContainerEXT                       spatialContainer);

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

• ‫spatialContainer הוא XrSpatialContainerEXT שנוצר בעבר על ידי xrCreateSpatialContainerEXT .

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

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

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

• חובה להפעיל את התוסף XR_EXT_spatial_container לפני שקוראים לפונקציה xrDestroySpatialContainerEXT
• ‫ spatialContainer חייב להיות כינוי תקין של XrSpatialContainerEXT

Thread Safety

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

קודי החזרה

הצלחה

• XR_SUCCESS

נכשל

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

המרחב של מאגר התגים המרחבי

הפונקציה xrCreateSpatialContainerSpaceEXT יוצרת נקודת אחיזה (handle) מסוג XrSpace למרחב של מאגר מרחבי ספציפי.

XrResult xrCreateSpatialContainerSpaceEXT(
    XrSession                                   session,
    const XrSpatialContainerSpaceCreateInfoEXT* createInfo,
    XrSpace*                                    space);

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

• ‫session הוא ה-XrSession שיוצר את המרחב.
• ‫createInfo הוא מצביע ל-XrSpatialContainerSpaceCreateInfoEXT שמכיל פרמטרים ליצירת המרחב.
• ‫space הוא מצביע לכינוי שבו מוחזר ה-XrSpace שנוצר.

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

‫+X מצביע על הצד הימני של המאגר, +Y מצביע על הצד העליון של המאגר ו-+Z מצביע על הצד הקדמי של המאגר. לדוגמה, אם מאגר מיושר לפי כוח הכבידה, מול הצופה, והצופה נמצא בתנוחת הזהות ביחס למרחב LOCAL , זמני הריצה חייבים לכוון את מרחב המאגר לפי כיוון הזהות ביחס למרחב LOCAL . סביבות זמן ריצה עשויות להגדיר את התנוחה של מרחב מאגר ביחס למרחב LOCAL לכל תנוחה שרירותית כשהמאגר הזה הופך לגלוי.

ext spatial container space convention

איור 18. מוסכמת הצירים של המרחב המכיל את המרחב

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

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

מרחב של מאגר מרחבי חייב להמשיך להיות נקודת אחיזה תקינה גם אם המאגר המרחבי שהוא מיועד לו נהרס באמצעות xrDestroySpatialContainerEXT . כשהקונטיינר המרחבי לא גלוי או נהרס, אסור שיהיה אפשר לאתר את המרחב של הקונטיינר המרחבי ביחס למרחבים אחרים. ‫XrSpaceLocation :: locationFlags ו-XrViewState ::viewStateFlags יהיו 0.

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

• חובה להפעיל את התוסף XR_EXT_spatial_container לפני שקוראים ל-xrCreateSpatialContainerSpaceEXT
• ‫ session חייב להיות כינוי תקין של XrSession
• createInfo חייב להיות מצביע למבנה XrSpatialContainerSpaceCreateInfoEXT תקין
• ‫ space חייב להיות מצביע לכינוי XrSpace

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

נכשל

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

הפונקציה XrSpatialContainerSpaceCreateInfoEXT משמשת עם xrCreateSpatialContainerSpaceEXT כדי ליצור נקודת אחיזה (handle) של XrSpace.

typedef struct XrSpatialContainerSpaceCreateInfoEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrSpatialContainerSpaceCreateInfoEXT;

תיאור המשתמש

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSpatialContainerSpaceCreateInfoEXT
• type חייב להיות XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
• ‫ spatialContainer חייב להיות כינוי תקין של XrSpatialContainerEXT

הצגת קונטיינר מרחבי

השליחה של תוכן של מאגר מרחבי ל-OpenXR לצורך הצגה מטופלת על ידי תוספים אחרים: XR_EXT_spatial_container_self_rendering .

כדי לאפשר לתוספים אחרים לציין את שיטת הצגת הגרפיקה של מאגר מרחבי, התוסף הזה מגדיר את ה-enum‏ XrSpatialContainerGraphicsPresentationEXT.

typedef enum XrSpatialContainerGraphicsPresentationEXT {
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT = 1000813000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT = 1000814000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1 = 1000815000,
    XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerGraphicsPresentationEXT;

תיאור הטיפוס בן המנייה (enum)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SELF_RENDERING_EXT

הקונטיינר המרחבי משתמש בשכבות קומפוזיציה של OpenXR (נוספו על ידי התוסף XR_EXT_spatial_container_self_rendering)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_CONFORMANCE_AUTOMATION_EXT

המאגר המרחבי נוצר לבדיקת תאימות ואין לו נתיב רינדור (נוסף על ידי התוסף XR_EXT_spatial_container_conformance_automation)

XR_SPATIAL_CONTAINER_GRAPHICS_PRESENTATION_SYSTEM_RENDERING_EXTX1

הקונטיינר המרחבי משתמש ברינדור של מערכת OpenXR (נוסף על ידי התוסף XR_EXTX1_system_renderer)

מצב הקונטיינר המרחבי

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

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

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

XrResult xrGetSpatialContainerStateEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerStateGetInfoEXT*    getInfo,
    XrSpatialContainerStateEXT*                 state);

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

• ‫spatialContainer הוא ה-XrSpatialContainerEXT שרוצים לשלוח אליו שאילתה.
• ‫getInfo הוא XrSpatialContainerStateGetInfoEXT עם המידע שמשמש לקבלת המצב של מאגר הנתונים המרחבי.
• ‫state הוא מצביע אל XrSpatialContainerStateEXT שבו מוחזר המצב של הקונטיינר המרחבי.

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

• צריך להפעיל את התוסף XR_EXT_spatial_container לפני שמפעילים את xrGetSpatialContainerStateEXT
• ‫ spatialContainer חייב להיות כינוי תקין של XrSpatialContainerEXT
• אם getInfo הוא לא NULL, אז getInfo חייב להיות מצביע למבנה XrSpatialContainerStateGetInfoEXT תקין
• state חייב להיות מצביע למבנה XrSpatialContainerStateEXT

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

נכשל

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

הפונקציה XrSpatialContainerStateGetInfoEXT משמשת עם xrGetSpatialContainerStateEXT כדי לשלוח שאילתה ל-XrSpatialContainerStateEXT .

typedef struct XrSpatialContainerStateGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerStateGetInfoEXT;

תיאור המשתמש

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSpatialContainerStateGetInfoEXT
• type חייב להיות XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

typedef struct XrSpatialContainerStateEXT {
    XrStructureType                    type;
    void*                              next;
    XrBool32                           visible;
    XrBool32                           interactable;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerStateEXT;

תיאור המשתמש

• ‫type הוא ה-XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
• המשתנה visible מייצג את הסטטוס של המאגר המרחבי (גלוי או מוסתר).
• ‫interactable מייצג אם קונטיינר מרחבי יכול כרגע לקבל קלט מכל סוג. הוא דומה ל "מיקוד" במערכות חלונות דו-ממדיות במחשב, אבל יש הבדל: יכול להיות שיהיה אפשר לקיים אינטראקציה עם כמה קונטיינרים מרחביים בו-זמנית.
• ‫boundsMode הוא הערך הנוכחי של XrSpatialContainerBoundsModeEXT של מאגר הנתונים המרחבי.

שינויים בסטטוס של מאגר מרחבי מועברים באמצעות אירועים.

אירוע של שינוי שדה

visible

XrEventDataSpatialContainerVisibleChangedEXT

interactable

XrEventDataSpatialContainerInteractableChangedEXT

boundsMode

XrEventDataSpatialContainerBoundsChangedEXT

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSpatialContainerStateEXT
• type חייב להיות XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

חשיפה

אפליקציות מבקשות להציג או להסתיר קונטיינר מרחבי באמצעות xrRequestSpatialContainerVisibleEXT .

XrResult xrRequestSpatialContainerVisibleEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerVisibleRequestInfoEXT* info);

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

• ‫spatialContainer הוא ה-XrSpatialContainerEXT שעבורו מבקשים שינוי.
• ‫info הוא מצביע ל-XrSpatialContainerVisibleRequestInfoEXT שמכיל את מצב החשיפה המבוקש.

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

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

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

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

סביבות זמן ריצה חייבות לדחות בקשות להצגת קונטיינר מרחבי במצב גבולות שלא נתמך על סמך XrSystemSpatialContainerPropertiesEXT :: supportsBounded ו-XrSystemSpatialContainerPropertiesEXT :: supportsImmersive . זה יכול לקרות כשמצב הגבולות שמוגדר כברירת מחדל, XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT , לא נתמך במערכת מסוימת.

הערה

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

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

• חובה להפעיל את התוסף XR_EXT_spatial_container לפני שקוראים ל-xrRequestSpatialContainerVisibleEXT
• ‫ spatialContainer חייב להיות כינוי תקין של XrSpatialContainerEXT
• info חייב להיות מצביע למבנה XrSpatialContainerVisibleRequestInfoEXT תקין

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

נכשל

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

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

typedef struct XrSpatialContainerVisibleRequestInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrBool32           visible;
} XrSpatialContainerVisibleRequestInfoEXT;

תיאור המשתמש

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSpatialContainerVisibleRequestInfoEXT
• type חייב להיות XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

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

typedef struct XrEventDataSpatialContainerVisibleChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 visible;
} XrEventDataSpatialContainerVisibleChangedEXT;

תיאור המשתמש

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

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

סביבת זמן ריצה עשויה לעכב את העיבוד של מאגר למשך כמה פריימים אחרי הוספת האירוע הזה לתור, כשהערך של visible מוגדר כ-XR_TRUE, כדי להימנע מהצגת מאגר ריק ולתת לאפליקציה זמן לשלוח את התוכן הראשוני שלה. בזמן הזה, הערך של XrSpatialContainerStateEXT ::visible יהיה XR_TRUE . זמני הריצה לא אמורים לעכב את העיבוד של מאגר תגים במשך יותר מחצי שנייה.

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrEventDataSpatialContainerVisibleChangedEXT
• type חייב להיות XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

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

typedef struct XrEventDataSpatialContainerVisibleRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerVisibleRequestDeniedEXT;

תיאור המשתמש

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrEventDataSpatialContainerVisibleRequestDeniedEXT
• type חייב להיות XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

ניתן לאינטראקציה

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

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

typedef struct XrEventDataSpatialContainerInteractableChangedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
    XrBool32                 interactable;
} XrEventDataSpatialContainerInteractableChangedEXT;

תיאור המשתמש

• ‫type הוא ה-XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
• ‫spatialContainer הוא ה-XrSpatialContainerEXT שהאירוע הזה מיועד לו.
• ‫interactable הוא המצב החדש שניתן לאינטראקציה של הקונטיינר המרחבי.

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

סביבות זמן ריצה יכולות להפעיל או להשבית את האינטראקציה עם מאגר מרחבי בכל שלב. אם סביבת זמן הריצה תומכת רק בקונטיינר מרחבי אחד שניתן לאינטראקציה בכל פעם, כשסביבת זמן הריצה משנה את הקונטיינר המרחבי שניתן לאינטראקציה, סביבת זמן הריצה חייבת להוסיף לתור את האירוע של הקונטיינר המרחבי שמפסיק להיות ניתן לאינטראקציה ( interactable מוגדר כ-false) לפני האירוע של הקונטיינר שמתחיל להיות ניתן לאינטראקציה ( interactable מוגדר כ-true).

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrEventDataSpatialContainerInteractableChangedEXT
• type חייב להיות XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

גבולות

למאגר מרחבי יש מצב גבולות ותיבה תוחמת. מצב הגבולות של מאגר מרחבי מתאר את אופן הפעולה של הגבולות. התיבה התוחמת (bounding box) היא האזור שבו המכל המרחבי מצייר.

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

typedef enum XrSpatialContainerBoundsModeEXT {
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT = 1,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT = 2,
    XR_SPATIAL_CONTAINER_BOUNDS_MODE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerBoundsModeEXT;

תיאור הטיפוס בן המנייה (enum)

XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT

המאגר המרחבי מוגבל. הגבולות הם תיבה סופית. הקונטיינר המרחבי יופיע רק באזור הזה.

XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT

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

יש דרישות נוספות לגבי קונטיינרים מרחביים במצב גבולות XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT:

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

הערה

הדרישות שלמעלה מרמזות שכל סביבות זמן הריצה יכולות להטמיע את הנתיב של OpenXR 1.x בלי התוסף הזה, על ידי יצירה מרומזת של קונטיינר מרחבי, הגדרת מצב הגבולות של הקונטיינר כ"אימרסיבי" ובקשה שהוא יהיה גלוי.

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

XrResult xrRequestSpatialContainerBoundsModeEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsModeRequestInfoEXT* info);

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

• ‫spatialContainer הוא ה-XrSpatialContainerEXT שעבורו מבקשים שינוי.
• ‫info הוא מצביע ל-XrSpatialContainerBoundsModeRequestInfoEXT שמכיל את מצב הגבולות המבוקש.

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

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

סביבות זמן ריצה חייבות להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם אפליקציה מבקשת מצב גבולות שלא נתמך על סמך XrSystemSpatialContainerPropertiesEXT :: supportsBounded ו-XrSystemSpatialContainerPropertiesEXT :: supportsImmersive .

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

• חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמפעילים את xrRequestSpatialContainerBoundsModeEXT
• ‫ spatialContainer חייב להיות כינוי תקין של XrSpatialContainerEXT
• ‫ info חייב להיות מצביע למבנה XrSpatialContainerBoundsModeRequestInfoEXT תקין

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

נכשל

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

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

typedef struct XrSpatialContainerBoundsModeRequestInfoEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrSpatialContainerBoundsModeRequestInfoEXT;

תיאור המשתמש

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

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

• צריך להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSpatialContainerBoundsModeRequestInfoEXT
• type חייב להיות XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים
• boundsMode חייב להיות ערך XrSpatialContainerBoundsModeEXT תקין

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

typedef struct XrEventDataSpatialContainerBoundsChangedEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialContainerEXT              spatialContainer;
    XrExtent3Df                        bounds;
    XrBool32                           infiniteBounds;
    XrSpatialContainerBoundsModeEXT    boundsMode;
} XrEventDataSpatialContainerBoundsChangedEXT;

תיאור המשתמש

• ‫type הוא ה-XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
• ‫spatialContainer הוא ה-XrSpatialContainerEXT שהאירוע הזה מיועד לו.
• ‫bounds הוא הרוחב, הגובה והעומק החדשים של גבולות הקונטיינר המרחבי.
• ‫infiniteBounds הוא True אם למאגר יש גבולות אינסופיים.
• ‫boundsMode הוא הערך החדש של XrSpatialContainerBoundsModeEXT של המאגר המרחבי.

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

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

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

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

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

בזמני ריצה חובה להגדיר את infiniteBounds ל-XR_TRUE ולהגדיר את הרוחב, הגובה והעומק ל-0.0 כדי לייצג גבולות אינסופיים. בסביבות זמן ריצה חובה להגדיר את infiniteBounds ל-XR_FALSE, ולהגדיר את הרוחב, הגובה והעומק למספרים חיוביים סופיים עבור גבולות סופיים.

זמני הריצה חייבים להגדיר את bounds ו-infiniteBounds לפי אותם כללים כמו של XrSpatialContainerBoundsEXT .

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrEventDataSpatialContainerBoundsChangedEXT
• type חייב להיות XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

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

typedef struct XrEventDataSpatialContainerBoundsModeRequestDeniedEXT {
    XrStructureType          type;
    const void*              next;
    XrSpatialContainerEXT    spatialContainer;
} XrEventDataSpatialContainerBoundsModeRequestDeniedEXT;

תיאור המשתמש

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrEventDataSpatialContainerBoundsModeRequestDeniedEXT
• type חייב להיות XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

המבנה XrSpatialContainerBoundsEXT מתאר את התיבה התוחמת (bounding box) של מאגר מרחבי.

typedef struct XrSpatialContainerBoundsEXT {
    XrStructureType    type;
    void*              next;
    XrExtent3Df        bounds;
    XrBool32           infiniteBounds;
} XrSpatialContainerBoundsEXT;

תיאור המשתמש

• ‫type הוא ה-XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
• ‫bounds הוא הרוחב, הגובה והעומק של גבולות המאגר המרחבי. הגבולות הם במטרים.
• ‫infiniteBounds הוא True אם למאגר יש גבולות אינסופיים.

בזמני ריצה חובה להגדיר את infiniteBounds ל-XR_TRUE ולהגדיר את הרוחב, הגובה והעומק ל-0.0 כדי לייצג גבולות אינסופיים. בסביבות זמן ריצה חובה להגדיר את infiniteBounds ל-XR_FALSE, ולהגדיר את הרוחב, הגובה והעומק למספרים חיוביים סופיים עבור גבולות סופיים.

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSpatialContainerBoundsEXT
• type חייב להיות XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

הפונקציה xrGetSpatialContainerBoundsEXT שולחת שאילתה לגבי הגבולות הנוכחיים של מאגר מרחבי.

XrResult xrGetSpatialContainerBoundsEXT(
    XrSpatialContainerEXT                       spatialContainer,
    const XrSpatialContainerBoundsGetInfoEXT*   getInfo,
    XrSpatialContainerBoundsEXT*                bounds);

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

• ‫spatialContainer הוא ה-XrSpatialContainerEXT שרוצים לשלוח אליו שאילתה.
• ‫getInfo הוא XrSpatialContainerBoundsGetInfoEXT עם המידע שמשמש לקבלת המצב של הקונטיינר המרחבי.
• ‫bounds הוא מצביע אל XrSpatialContainerBoundsEXT שבו הגבולות מוחזרים.

כשהקונטיינר המרחבי מוגבל, אסור שיהיו לו גבולות אינסופיים. כשהקונטיינר המרחבי הוא סוחף, חייבים להיות לו גבולות אינסופיים.

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

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שקוראים לפונקציה xrGetSpatialContainerBoundsEXT
• ‫ spatialContainer חייב להיות כינוי תקין של XrSpatialContainerEXT
• אם getInfo הוא לא NULL, אז getInfo חייב להיות מצביע למבנה XrSpatialContainerBoundsGetInfoEXT תקין
• bounds חייב להיות מצביע למבנה XrSpatialContainerBoundsEXT

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

נכשל

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

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

typedef struct XrSpatialContainerBoundsGetInfoEXT {
    XrStructureType    type;
    const void*        next;
} XrSpatialContainerBoundsGetInfoEXT;

תיאור המשתמש

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

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

• חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSpatialContainerBoundsGetInfoEXT
• type חייב להיות XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

הספירה XrSpatialContainerVolumeClippingEXT מזהה התנהגויות שונות של חיתוך עוצמת קול במאגר מרחבי.

typedef enum XrSpatialContainerVolumeClippingEXT {
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT = 0,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT = 1,
    XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialContainerVolumeClippingEXT;

תיאור הטיפוס בן המנייה (enum)

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_NONE_EXT

התוכן לא נחתך לפי נפח הגבולות של המכל המרחבי. התוכן יכול לחרוג מגבולות המכל המרחבי.

XR_SPATIAL_CONTAINER_VOLUME_CLIPPING_STRICT_EXT

התוכן נחתך בדיוק לפי הנפח התחום של הקונטיינר המרחבי.

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

יכולות המערכת

אפליקציה יכולה לבדוק את יכולות המערכת על ידי שרשור של מבנה XrSystemSpatialContainerPropertiesEXT אל XrSystemProperties כשמתבצעת קריאה ל-xrGetSystemProperties .

typedef struct XrSystemSpatialContainerPropertiesEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSpatialContainerCount;
    XrBool32           supportsBounded;
    XrBool32           supportsImmersive;
} XrSystemSpatialContainerPropertiesEXT;

תיאור המשתמש

• ‫type הוא ה-XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. מבנים כאלה לא מוגדרים ב-OpenXR או בתוסף הזה.
• ‫maxSpatialContainerCount הוא המספר המקסימלי של קונטיינרים מרחביים שאפשר ליצור.
• הערך של supportsBounded הוא True אם אפשר להגביל מאגרים מרחביים.
• הערך של supportsImmersive הוא True אם מותר להפעיל קונטיינרים מרחביים במצב סוחף.

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

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSystemSpatialContainerPropertiesEXT
• type חייב להיות XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

הפונקציה xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT מחזירה את שיטות הצגת הגרפיקה שנתמכות במערכת.

XrResult xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    graphicsPresentationCapacityInput,
    uint32_t*                                   graphicsPresentationCountOutput,
    XrSpatialContainerGraphicsPresentationEXT*  graphicsPresentations);

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

• ‫instance הוא ה-XrInstance שממנו אוחזר systemId.
• ‫systemId הוא ה-XrSystemId שנשלחת אליו שאילתה.
• ‫graphicsPresentationCapacityInput הוא הקיבולת של המערך graphicsPresentations, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫graphicsPresentationCountOutput הוא מצביע למספר המצגות הגרפיות שנכתבו, או מצביע לקיבולת הנדרשת במקרה ש-graphicsPresentationCapacityInput הוא 0.
• ‫graphicsPresentations הוא מצביע למערך של ערכי XrSpatialContainerGraphicsPresentationEXT, אבל הוא יכול להיות null אם הערך של graphicsPresentationCapacityInput הוא 0.
• בקטע פרמטרים של שטח אחסון זמני יש תיאור מפורט של אחזור הגודל הנדרש של graphicsPresentations.

סביבות זמן ריצה חייבות תמיד להחזיר תוכן מאגר זהה מהספירה הזו עבור ה-systemId הנתון ולמשך כל חיי המכונה.

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

• חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמפעילים את xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT
• ‫ instance חייב להיות כינוי תקין של XrInstance
• graphicsPresentationCountOutput חייב להיות מצביע לערך uint32_t
• אם graphicsPresentationCapacityInput הוא לא 0 , graphicsPresentations חייב להיות מצביע למערך של ערכי graphicsPresentationCapacityInput XrSpatialContainerGraphicsPresentationEXT

קודי החזרה

הצלחה

• XR_SUCCESS

נכשל

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

שינויים במצב הסשן

כדי להפעיל תמיכה במאגרים מרחביים בסשן, צריך לשרשר XrSessionCreateInfoSpatialContainersEXT כשקוראים ל-xrCreateSession .

typedef struct XrSessionCreateInfoSpatialContainersEXT {
    XrStructureType    type;
    const void*        next;
} XrSessionCreateInfoSpatialContainersEXT;

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

הפעלת התמיכה בקונטיינר מרחבי משנה את ממשקי ה-API העיקריים של OpenXR באופן הבא.

runtime: losing system or device

runtime: losing system or device

xrDestroySession

xrDestroySession

IDLE
(פועל)

לא פעיל…

xrGetSystem
xrCreateSession

xrGetSystem...‎

xrCreateInstance

xrCreateIn...

xrDestroySession

xrDestroySession

LOSS_PENDING
(לא פועל)

LOSS_PENDING...‎

xrDestroyInstance

xrDestroyInstance

אפליקציה: הפעלה מחדש של XR
(אופציונלי)

אפליקציה: אופציונלי...

איור 19. מכונת מצבים חדשה של סשן

• הסשן אף פעם לא נכנס למצבים XR_SESSION_STATE_VISIBLE, XR_SESSION_STATE_FOCUSED או XR_SESSION_STATE_EXITING . זמני ריצה לא צריכים להוסיף אירועים לתור במצבים האלה. המצבים האלה מוחלפים באירועים לכל מאגר מרחבי: XrEventDataSpatialContainerVisibleChangedEXT,‏ XrEventDataSpatialContainerInteractableChangedEXT ו-XrEventDataSpatialContainerClosedEXT, בהתאמה.
• הסשן גם לא נכנס למצבים XR_SESSION_STATE_READY , XR_SESSION_STATE_SYNCHRONIZED , XR_SESSION_STATE_STOPPING . זמני ריצה לא צריכים להוסיף אירועים לתור עבור המצבים האלה. אין תחליף למצבים האלה.
• סביבות זמן ריצה חייבות להתייחס לסשן כפועל כשהוא במצב XR_SESSION_STATE_IDLE .
• זמני ריצה חייבים להתייחס לסשן כממוקד כשהוא במצב XR_SESSION_STATE_IDLE וקיים לפחות מאגר מרחבי אחד שניתן לקיים איתו אינטראקציה.
• אין יותר צורך בפונקציות xrBeginSession ו-xrEndSession. סביבות זמן הריצה חייבות להחזיר את הערך XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT כשקוראים לפונקציות האלה. יכול להיות שתוספים אחרים יספקו תחליפים לפונקציות האלה.
• גם הפונקציה xrRequestExitSession כבר לא נדרשת. סביבות זמן הריצה חייבות להחזיר את הערך XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT כשקוראים לפונקציה הזו. אפליקציות שרוצות לצאת מסשן פעיל יכולות להפעיל את xrRequestSpatialContainerVisibleEXT כדי להסתיר את הקונטיינרים שלהן, ולסגור את הסשן אחרי שכל הקונטיינרים כבר לא גלויים.

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

  אירוע של תוסף

XR_EXT_user_presence

XrEventDataUserPresenceChangedEXT

XR_META_boundary_visibility

XrEventDataBoundaryVisibilityChangedMETA

• אי אפשר להפעיל את הפונקציה xrLocateViews בסשן. זמני ריצה חייבים להחזיר את XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT מ-xrLocateViews . תוספים אחרים עשויים לספק דרכים לאתר את התצוגות של מאגר מרחבי מסוים.
• הפונקציה xrWaitFrame חייבת תמיד להגדיר את XrFrameState :: shouldRender כ-false. תוספים אחרים עשויים לספק דרכים לדעת אם קונטיינר מרחבי מסוים צריך לעדכן את שכבות הקומפוזיציה שלו.
• הפונקציה xrEndFrame היא לא דרך תקינה לשלוח שכבות קומפוזיציה. אם אפליקציה מגדירה את XrFrameEndInfo :: layerCount לערך שאינו אפס, זמני הריצה חייבים להחזיר את XR_ERROR_VALIDATION_FAILURE . תוספים אחרים עשויים לספק דרכים לשליחת שכבות קומפוזיציה למאגר מרחבי מסוים.
• כניסה למצב XR_SESSION_STATE_LOSS_PENDING גם סוגרת את כל הקונטיינרים המרחביים. זמני ריצה חייבים להוסיף לתור אירוע XrEventDataSpatialContainerClosedEXT לכל מאגר מרחבי פעיל לפני הוספה לתור של שינוי מצב סשן עבור XR_SESSION_STATE_LOSS_PENDING .
• הפונקציה xrCreateSession לא צריכה יותר מבנה קישור של ממשק API לגרפיקה. יכול להיות שתוספים אחרים ידרשו קישור גרפי, למשל כדי שקונטיינר מרחבי יעובד באמצעות API גרפי.

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

הערה

כשהמכלים המרחביים מופעלים, הסשן עובר בין שני מצבים בלבד: XR_SESSION_STATE_IDLE (פועל) ו-XR_SESSION_STATE_LOSS_PENDING (לא פועל). כתוצאה מכך, זמני הריצה לא מחזירים יותר את הערכים XR_ERROR_SESSION_RUNNING או XR_ERROR_SESSION_NOT_RUNNING . במקום זאת, כשסשן לא פועל, זמני הריצה מחזירים את הערך XR_ERROR_SESSION_LOST או XR_SESSION_LOSS_PENDING בהתאם לכללים בליבה של OpenXR. בנוסף, הפונקציה xrBeginSession , היחידה שמחזירה את הערך XR_ERROR_SESSION_RUNNING , תחזיר עכשיו תמיד את הערך XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT .

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

• חובה להפעיל את התוסף XR_EXT_spatial_container לפני שמשתמשים ב-XrSessionCreateInfoSpatialContainersEXT
• type חייב להיות XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
• next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים

רשומות במניפסט של Android

לסביבות זמן ריצה שמבוססות על AOSP עשויה להיות התנהגות מותאמת אישית שמבוססת על המצב הראשוני של הקונטיינר המרחבי, שמתחיל לפני הרצת קוד כלשהו של האפליקציה. לדוגמה, זמן ריצה עשוי לשנות את המשאבים שהוקצו לפעילות, להפעיל אנימציות או להציג מסך פתיחה. המאפיינים הבאים מסופקים למטרה הזו. הם מחליפים את התג <category android:name="org.khronos.openxr.intent.category.IMMERSIVE_HMD" />, שאפליקציות שמבוססות על קונטיינר מרחבי לא אמורות לציין, אלא אם הן צריכות תאימות לסביבות הרצה קודמות שמבוססות על AOSP.

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_USED_BOUNDS_MODES"
          android:value="list of modes" />

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

המחרוזות הבאות תקינות למאפיין הזה. כדי להזין כמה ערכים, צריך להפריד ביניהם באמצעות |, למשל "bounded|immersive" .

ערך

תיאור

"2d_panel"

הפעילות מוצגת באמצעות מסגרת התצוגה הדו-ממדית של Android.

"bounded"

הפעילות משתמשת ב-XR_SPATIAL_CONTAINER_BOUNDS_MODE_BOUNDED_EXT .

"immersive"

הפעילות משתמשת ב-XR_SPATIAL_CONTAINER_BOUNDS_MODE_IMMERSIVE_EXT .

<property android:name="org.khronos.openxr.PROPERTY_ACTIVITY_HINT_XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE"
          android:value="XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_BOUNDED|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_IMMERSIVE|
                         XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED" />

המאפיין הזה נותן רמז לזמני הריצה של XrSpatialContainerBoundsModeEXT הראשוני של הפעילות כשהיא נוצרת בפעם הראשונה. כברירת מחדל, המחרוזת היא XR_SPATIAL_CONTAINER_INITIAL_BOUNDS_MODE_UNDEFINED, כלומר אין רמז.

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

קוד לדוגמה

הקוד הבא מראה איך להשתמש בתוסף הזה למקרי שימוש של תפיסה בלבד, בלי רינדור.

XrInstance instance;    // Already initialized


// Create the session with spatial containers enabled
XrSession session;

XrSessionCreateInfoSpatialContainersEXT spatialContainerCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT,
};
XrSessionCreateInfo sessionCreateInfo {
  .type = XR_TYPE_SESSION_CREATE_INFO,
  .next = &spatialContainerCreateInfo,   // Enable spatial containers
};
(void)sessionCreateInfo.systemId;                             // Other create fields set in usual way

CHK_XR(xrCreateSession(instance, &sessionCreateInfo, &session));


// Because spatial containers are enabled, the session is considered
// running. App is able to query perception data such as head poses and hand
// poses.


// Based on app logic or when a system lost event happens, destroy the
// session
CHK_XR(xrDestroySession(session));

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

• XrSpatialContainerEXT

פקודות חדשות

• xrCreateSpatialContainerEXT
• xrCreateSpatialContainerSpaceEXT
• xrDestroySpatialContainerEXT
• xrEnumerateSupportedSpatialContainerGraphicsPresentationsEXT
• xrGetSpatialContainerBoundsEXT
• xrGetSpatialContainerStateEXT
• xrRequestSpatialContainerBoundsModeEXT
• xrRequestSpatialContainerVisibleEXT

מבנים חדשים

• XrEventDataSpatialContainerBoundsChangedEXT
• XrEventDataSpatialContainerBoundsModeRequestDeniedEXT
• XrEventDataSpatialContainerClosedEXT
• XrEventDataSpatialContainerInteractableChangedEXT
• XrEventDataSpatialContainerVisibleChangedEXT
• XrEventDataSpatialContainerVisibleRequestDeniedEXT
• XrSpatialContainerBoundsEXT
• XrSpatialContainerBoundsGetInfoEXT
• XrSpatialContainerBoundsModeRequestInfoEXT
• XrSpatialContainerCreateInfoEXT
• XrSpatialContainerSpaceCreateInfoEXT
• XrSpatialContainerStateEXT
• XrSpatialContainerStateGetInfoEXT
• XrSpatialContainerVisibleRequestInfoEXT

• הרחבה של XrSessionCreateInfo :

  • XrSessionCreateInfoSpatialContainersEXT

• הרחבת XrSystemProperties :

  • XrSystemSpatialContainerPropertiesEXT

ערכי Enums חדשים

• XrSpatialContainerBoundsModeEXT
• XrSpatialContainerGraphicsPresentationEXT
• XrSpatialContainerVolumeClippingEXT

קבועי Enum חדשים

• XR_EXT_SPATIAL_CONTAINER_EXTENSION_NAME
• XR_EXT_spatial_container_SPEC_VERSION

• הרחבה של XrObjectType :

  • XR_OBJECT_TYPE_SPATIAL_CONTAINER_EXT

• הרחבת XrResult :

  • XR_ERROR_COMPATIBLE_SPATIAL_CONTAINER_MISSING_EXT
  • XR_ERROR_SPATIAL_CONTAINERS_ENABLED_EXT
  • XR_ERROR_SPATIAL_CONTAINERS_NOT_ENABLED_EXT
  • XR_ERROR_SPATIAL_CONTAINER_CLOSED_EXT

• הרחבה של XrStructureType :

  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_CHANGED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_DENIED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_CLOSED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_INTERACTABLE_CHANGED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_CHANGED_EXT
  • XR_TYPE_EVENT_DATA_SPATIAL_CONTAINER_VISIBLE_REQUEST_DENIED_EXT
  • XR_TYPE_SESSION_CREATE_INFO_SPATIAL_CONTAINERS_EXT
  • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_EXT
  • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_GET_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_BOUNDS_MODE_REQUEST_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_CREATE_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_SPACE_CREATE_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_STATE_EXT
  • XR_TYPE_SPATIAL_CONTAINER_STATE_GET_INFO_EXT
  • XR_TYPE_SPATIAL_CONTAINER_VISIBLE_REQUEST_INFO_EXT
  • XR_TYPE_SYSTEM_SPATIAL_CONTAINER_PROPERTIES_EXT

בעיות

• איך אנחנו מטפלים בכמה בקשות גלויות שעדיין לא טופלו? האם האפליקציה צריכה לקבל שינוי אחד / דחייה אחת או כמה? התשובה עשויה להיות שונה אם הקריאות הן על פני כמה פריימים. התשובה עשויה להיות שונה גם אם הבקשות המרובות גורמות ל-noop, כלומר בקשה להפוך מאגר מרחבי לגלוי, ואז לא גלוי, עבור מאגר שמתחיל כלא גלוי.

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

• איך צריך להגדיר תוסף אוטומציה של תאימות כדי שכל הטקסט האופציונלי של המפרט להתנהגויות של מדיניות עדיין יהיה ניתן לבדיקה על ידי CTS?

  • הבעיה נפתרה. תוסף בדיקה נפרד. תהיה סביבת הרצה לבדיקת תוספים שתיושם רק ל-CTS, ותאפשר ל-CTS לשלוט בכל המדיניות של המערכת.

• האם צריך אירוע לשינוי המיקום של מאגר מרחבי?

  • הבעיה נפתרה. לא. המרחב של המכל המרחבי לא נעול לעולם, ומרחבים אחרים כאלה, כמו XR_REFERENCE_SPACE_TYPE_VIEW, לא כוללים אירועים כשהם משתנים.

• איך xrSyncActions פועל אם יש כמה קונטיינרים מרחביים?

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

• איך אפליקציות שמתעדכנות לעיתים רחוקות מטפלות בקלט?

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

• האם צריך להמתין כדי לווסת או לשלוט בתזמון של לולאת הקלט באפליקציות עם לולאות קלט ורינדור נפרדות?

  • הבעיה נפתרה. לא נדרש שינוי. הטיפול בזה אמור להתבצע דרך ערוץ האירועים ותוספי הבקשות הנוכחיים. תוסף הבקשה הנוכחי מאפשר עיבוד (rendering) שמבוסס על אירועים ומנותק מלולאת מסגרת.

• האם קונטיינר מרחבי יכול לקבל את המיקום שלו ביחס לקונטיינרים מרחביים אחרים? נקודות למחשבה: האם יש לנו תרחיש לדוגמה בשביל זה? ואם כן, איך המרחבים של המאגר המרחבי מתחברים ל-LOCAL?

  • הבעיה נפתרה. כן. כבר אפשר לעשות את זה במכלים מרחביים באותו סשן דרך XR_REFERENCE_SPACE_TYPE_VIEW, ורצוי לתמוך בתוכן שתלוי בתצוגה. כדי לשתף תנוחות של קונטיינר מרחבי בין סשנים (למשל, לתהליך אחר), הדרך המומלצת היא להשתמש ב-XR_EXT_spatial_anchor ובדפוסי השמירה והשיתוף הקיימים שלו.

• האם אפשר לאתר את המיקום של המרחב הפרטי אם הוא לא גלוי?

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

• איפה במכל המרחבי אמור להיות ממוקם המרחב של המכל המרחבי? ההצעות היו המרכז או הנקודה המינימלית (minX, ‏ minY, ‏ minZ).

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

• מתי סביבת זמן הריצה צפויה ליצור משאבים שנמצאים בבסיס של מאגר המרחב? לפעמים זה כולל IPC עם שירותי מערכת.

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

• האם אנחנו צריכים אות לכך ש-XrSession ייצור קונטיינרים מרחביים ולכן לא יתמוך בנתיב הרינדור הקודם?

  • הבעיה נפתרה. כן. אנחנו משנים את מכונת המצבים של הסשן באופן מהותי.

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

• גרסה 1, 06.08.2026 (ג'ארד פינדר, Google)

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