XR_EXT_spatial_entity

מחרוזת שם

XR_EXT_spatial_entity

סוג התוסף

הרחבת המכונה

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

741

Revision

1

סטטוס האישור

אושר

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

XR_EXT_future

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

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Karthik Kadappan, Magic Leap
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

סקירה כללית

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

החלקים העיקריים של התוסף הזה הם:

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

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

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

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

יישות מרחבית

ישויות מרחביות הן ישויות שקיימות במרחב מסוים, שיש להן נתונים משויכים שונים שמסודרים לרכיבים. הם יכולים להיות כל אחד מהבאים:

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

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

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

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

סוגי רכיבים מרחביים

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

typedef enum XrSpatialComponentTypeEXT {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT = 1,
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT = 2,
    XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT = 3,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT = 4,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT = 1000741000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT = 1000741001,
    XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT = 1000741002,
    XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT = 1000741003,
    XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT = 1000743000,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT = 1000744000,
    XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT = 1000744001,
    XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT = 1000744002,
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT = 1000763000,
    XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT = 1000782000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT = 1000783000,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT = 1000783001,
    XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT = 1000783002,
    XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID = 1000785000,
    XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID = 1000786000,
    XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID = 1000791000,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS = 1000792002,
    XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS = 1000792003,
    XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS = 1000792004,
    XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS = 1000792005,
    XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1 = 1000793000,
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID = 1000794000,
    XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2 = 1000798000,
    XR_SPATIAL_COMPONENT_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialComponentTypeEXT;

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

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

הערכים האפשריים הם:

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

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT

רכיב שמספק את הגבולות הדו-ממדיים של ישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentBounded2DListEXT ; מבנה הנתונים המתאים הוא XrSpatialBounded2DDataEXT

XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT

רכיב שמספק את הגבולות התלת-ממדיים של ישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentBounded3DListEXT ; מבנה הנתונים המתאים הוא XrBoxf

XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT

רכיב שמספק את XrSpatialEntityIdEXT של רכיב ההורה עבור ישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentParentListEXT ; מבנה הנתונים המתאים הוא XrSpatialEntityIdEXT

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT

רכיב שמספק רשת תלת-ממדית לישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentMesh3DListEXT ; מבנה הנתונים המתאים הוא XrSpatialMeshDataEXT

XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT

רכיב שמספק את ה-enum של יישור המישור לישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentPlaneAlignmentListEXT ; מבנה הנתונים המתאים הוא XrSpatialPlaneAlignmentEXT (נוסף על ידי התוסף XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_2D_EXT

רכיב שמספק רשת דו-ממדית לישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentMesh2DListEXT; מבנה הנתונים המתאים הוא XrSpatialMeshDataEXT (נוסף על ידי התוסף XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_POLYGON_2D_EXT

רכיב שמספק פוליגון גבול דו-ממדי לישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentPolygon2DListEXT; מבנה הנתונים המתאים הוא XrSpatialPolygon2DDataEXT (נוסף על ידי התוסף XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT

רכיב שמספק תווית סמנטית למטוס. מבנה הרשימה התואם הוא XrSpatialComponentPlaneSemanticLabelListEXT ; מבנה הנתונים התואם הוא XrSpatialPlaneSemanticLabelEXT (נוסף על ידי התוסף XR_EXT_spatial_plane_tracking)

XR_SPATIAL_COMPONENT_TYPE_MARKER_EXT

רכיב שמתאר את סוג הסמן, המזהה והמיקום. מבנה הרשימה התואם הוא XrSpatialComponentMarkerListEXT ; מבנה הנתונים התואם הוא XrSpatialMarkerDataEXT (נוסף על ידי התוסף XR_EXT_spatial_marker_tracking)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_EXT

רכיב שמספק תווית סמנטית לסצנה. מבנה הרשימה התואם הוא XrSpatialComponentObjectSemanticLabelListEXT. מבנה הנתונים התואם הוא XrSpatialObjectSemanticLabelEXT . (נוסף על ידי התוסף XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_KEYBOARD_SEMANTIC_LABEL_EXT

רכיב שמספק תווית סמנטית למקלדת. מבנה הרשימה התואם הוא XrSpatialComponentKeyboardSemanticLabelListEXT. מבנה הנתונים המתאים הוא XrSpatialKeyboardSemanticLabelEXT (נוסף על ידי התוסף XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_MOUSE_SEMANTIC_LABEL_EXT

רכיב שמספק תווית סמנטית לעכבר. מבנה הרשימה המתאים הוא XrSpatialComponentMouseSemanticLabelListEXT. מבנה הנתונים התואם הוא XrSpatialMouseSemanticLabelEXT (נוסף על ידי התוסף XR_EXT_spatial_object_tracking)

XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT

רכיב שמספק את המיקום של העוגן. מבנה הרשימה המתאים הוא XrSpatialComponentAnchorListEXT ; מבנה הנתונים המתאים הוא XrPosef (נוסף על ידי התוסף XR_EXT_spatial_anchor)

XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

רכיב שמספק את המזהה הייחודי האוניברסלי (UUID) שנשמר עבור ישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentPersistenceListEXT ; מבנה הנתונים המתאים הוא XrSpatialPersistenceDataEXT (נוסף על ידי התוסף XR_EXT_spatial_persistence)

XR_SPATIAL_COMPONENT_TYPE_IMAGE_2D_EXT

רכיב שמתאר את סוג התמונה המישורית. מבנה הרשימה המתאים הוא XrSpatialComponentImage2DListEXT ומבנה הנתונים המתאים הוא XrSpatialImageSizeEXT . (נוסף על ידי התוסף XR_EXT_spatial_image_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_NORMALS_EXT

רכיב שמספק את הנורמלים של רשת התלת-ממד של ישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentMesh3DNormalsListEXT ; מבנה הנתונים המתאים הוא XrSpatialBufferEXT (נוסף על ידי התוסף XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_VERTEX_SEMANTIC_LABELS_EXT

רכיב שמספק את התוויות הסמנטיות לכל קודקוד ברשת התלת-ממדית של ישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentMesh3DVertexSemanticLabelsListEXT; מבנה הנתונים המתאים הוא XrSpatialBufferEXT; הנתונים בתוך המאגר ממופים ל-XrSpatialMeshSemanticLabelEXT (נוסף על ידי התוסף XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_MESH_3D_TRIANGLE_SEMANTIC_LABELS_EXT

רכיב שמספק את התוויות הסמנטיות לכל משולש בפנים של רשת תלת-ממדית של ישות מרחבית. מבנה הרשימה המתאים הוא XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT; מבנה הנתונים המתאים הוא XrSpatialBufferEXT; הנתונים בתוך מאגר הנתונים הזמני ממופים ל-XrSpatialMeshSemanticLabelEXT (נוסף על ידי התוסף XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_COMPONENT_TYPE_OBJECT_SEMANTIC_LABEL_ANDROID

רכיב שמספק תווית סמנטית לאובייקט. מבנה הרשימה המתאים הוא XrSpatialComponentObjectSemanticLabelListANDROID. מבנה הנתונים המתאים הוא XrSpatialObjectSemanticLabelANDROID (נוסף על ידי התוסף XR_ANDROID_spatial_object_tracking).

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

רכיב שמספק את המיקום של פגיעה בקרן ביישות. מבנה הרשימה המתאים הוא XrSpatialComponentRaycastResultListANDROID ; מבנה הנתונים המתאים הוא XrSpatialRaycastResultDataANDROID (נוסף על ידי התוסף XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_COMPONENT_TYPE_SUBSUMED_BY_ANDROID

רכיב שמספק את מזהה הישות של הישות שכוללת את הישות המצורפת. מבנה הרשימה המתאים הוא XrSpatialComponentSubsumedByListANDROID ; מבנה הנתונים המתאים הוא XrSpatialEntityIdEXT (נוסף על ידי התוסף XR_ANDROID_spatial_component_subsumed_by)

XR_SPATIAL_COMPONENT_TYPE_ROOM_ANDROIDSYS

רכיב שמספק את המידות ואת סוג החדר של קופסת נעליים; מבנה הרשימה המתאים הוא XrSpatialComponentRoomListANDROIDSYS; מבנה הנתונים המתאים הוא XrSpatialRoomDataANDROIDSYS (נוסף על ידי התוסף XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_MATERIAL_TYPE_ANDROIDSYS

רכיב שמספק את סוג החומר של משטח גבול; מבנה הרשימה המתאים הוא XrSpatialComponentMaterialTypeListANDROIDSYS; מבנה הנתונים המתאים הוא XrSpatialMaterialTypeANDROIDSYS (נוסף על ידי התוסף XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_CONFIDENCE_ANDROIDSYS

רכיב שמספק את רמת הסמך של רכיב שאפשר לעקוב אחריו; מבנה הרשימה המתאים הוא XrSpatialComponentConfidenceListANDROIDSYS; מבנה הנתונים המתאים הוא float (נוסף על ידי התוסף XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_ROOM_EMPTINESS_ANDROIDSYS

רכיב שמספק את הנתונים לגבי המרחב הפנוי בחדר; מבנה הרשימה המתאים הוא XrSpatialComponentRoomEmptinessListANDROIDSYS; מבנה הנתונים המתאים הוא float (נוסף על ידי התוסף XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_COMPONENT_TYPE_OCCUPANCY_GRID_ANDROIDX1

רכיב שמספק מידע על רשת תאים לציון תפוסה בישות המצורפת. מבנה הרשימה המתאים הוא XrSpatialComponentOccupancyGridListANDROIDX1 ; מבנה הנתונים המתאים הוא XrSpatialOccupancyGridDataANDROIDX1 (נוסף על ידי התוסף XR_ANDROIDX1_spatial_occupancy_grid)

XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

רכיב שמתאר הערה של ריבוע. מבנה הרשימה המתאים הוא XrSpatialComponentAnnotationQuadListANDROID ; מבנה הנתונים המתאים הוא XrSpatialAnnotationQuadDataANDROID (נוסף על ידי התוסף XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_COMPONENT_TYPE_STREETSCAPE_GEOMETRY_METADATA_ANDROIDX2

רכיב שמספק את המטא-נתונים של גיאומטריית נוף רחוב. מבנה הרשימה התואם הוא XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 ומבנה הנתונים התואם הוא XrSpatialStreetscapeGeometryMetadataANDROIDX2 (נוסף על ידי התוסף XR_ANDROIDX2_geospatial_streetscape)

יכולות מרחביות והגדרה

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

typedef enum XrSpatialCapabilityEXT {
    XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT = 1000741000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT = 1000743002,
    XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT = 1000743003,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_ANCHOR_EXT = 1000762000,
    XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID = 1000785000,
    XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID = 1000786000,
    XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS = 1000792000,
    XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS = 1000792001,
    XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID = 1000794000,
    XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2 = 1000798000,
    XR_SPATIAL_CAPABILITY_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityEXT;

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

הערכים האפשריים הם:

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

XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT

מעקב אחרי מטוסים (נוסף על ידי התוסף XR_EXT_spatial_plane_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_QR_CODE_EXT

יכולת לזהות ולעקוב אחרי קודי QR. (נוסף על ידי התוסף XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_MICRO_QR_CODE_EXT

יכולת לזהות ולעקוב אחרי קודי מיקרו QR. (נוסף על ידי התוסף XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_ARUCO_MARKER_EXT

יכולת לזהות ולעקוב אחרי סמני Aruco. (נוסף על ידי התוסף XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_MARKER_TRACKING_APRIL_TAG_EXT

יכולת לזהות ולעקוב אחרי תגי AprilTag. (נוסף על ידי התוסף XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_EXT

מעקב אחרי אובייקטים (נוסף על ידי התוסף XR_EXT_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_ANCHOR_EXT

יכולת ליצור עוגנים מרחביים (נוספה על ידי התוסף XR_EXT_spatial_anchor)

XR_SPATIAL_CAPABILITY_IMAGE_TRACKING_EXT

יכולת לזהות ולעקוב אחרי תמונות מישוריות להשוואה. (נוסף על ידי התוסף XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_MESH_TRACKING_EXT

יכולת לעקוב אחרי הרשת של סביבה. (נוסף על ידי התוסף XR_EXT_spatial_mesh_tracking)

XR_SPATIAL_CAPABILITY_OBJECT_TRACKING_ANDROID

מעקב אחרי אובייקטים (נוסף על ידי התוסף XR_ANDROID_spatial_object_tracking)

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

Raycast against depth buffer (נוסף על ידי התוסף XR_ANDROID_spatial_discovery_raycast)

XR_SPATIAL_CAPABILITY_ROOM_TRACKING_ANDROIDSYS

היכולת לעקוב אחרי חדר (נוספה על ידי התוסף XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ROOM_BOUNDARY_TRACKING_ANDROIDSYS

אפשרות לעקוב אחרי גבולות החדר (נוספה על ידי התוסף XR_ANDROIDSYS_spatial_room_tracking)

XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

מעקב אחר הערות (נוסף על ידי התוסף XR_ANDROID_spatial_annotation_tracking)

XR_SPATIAL_CAPABILITY_STREETSCAPE_GEOMETRY_ANDROIDX2

גיאומטריית נוף רחוב (נוספה על ידי התוסף XR_ANDROIDX2_geospatial_streetscape)

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

XrResult xrEnumerateSpatialCapabilitiesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    capabilityCapacityInput,
    uint32_t*                                   capabilityCountOutput,
    XrSpatialCapabilityEXT*                     capabilities);

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

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

האפליקציה יכולה למנות את רשימת היכולות המרחביות שנתמכות על ידי XrSystemId נתון באמצעות xrEnumerateSpatialCapabilitiesEXT .

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

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני שמבצעים קריאה ל-xrEnumerateSpatialCapabilitiesEXT
• ‫ instance חייב להיות ידית XrInstance תקינה
• ‫ capabilityCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם capabilityCapacityInput לא שווה ל-0 , ‏ capabilities חייב להיות מצביע למערך של capabilityCapacityInput ערכים מסוג XrSpatialCapabilityEXT

קודי החזרה

הצלחה

• XR_SUCCESS

Failure

• 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

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

XrResult xrEnumerateSpatialCapabilityComponentTypesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    XrSpatialCapabilityComponentTypesEXT*       capabilityComponents);

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

• ‫instance הוא כינוי ל-XrInstance .
• ‫systemId הוא XrSystemId שהרכיבים של יכולת המיקום שלו יפורטו.
• ‫capability הוא XrSpatialCapabilityEXT שעבורו יפורטו הרכיבים.
• ‫capabilityComponents הוא מצביע אל XrSpatialCapabilityComponentTypesEXT , שהוא מבנה קלט/פלט שבו מאוכלס מערך שהוקצה לאפליקציה.

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

האפליקציה יכולה להשתמש בסוגי הרכיבים שמפורטים ב-XrSpatialCapabilityComponentTypesEXT :: componentTypes כדי להבין את כל הרכיבים ש-systemId תומך בהם עבור capability, ויכולה להשתמש ברשימה הזו כדי לקבוע מהי הגדרה תקינה של capability כשיוצרים עבורו XrSpatialContextEXT.

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT אם capability לא מפורט על ידי xrEnumerateSpatialCapabilitiesEXT .

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

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

• ‫ XR_EXT_spatial_entity התוסף חייב להיות מופעל לפני הקריאה ל-xrEnumerateSpatialCapabilityComponentTypesEXT
• ‫ instance חייב להיות ידית XrInstance תקינה
• ‫ capability חייב להיות ערך תקין של XrSpatialCapabilityEXT
• ‫ capabilityComponents צריך להיות מצביע למבנה XrSpatialCapabilityComponentTypesEXT

קודי החזרה

הצלחה

• XR_SUCCESS

Failure

• 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

המבנה XrSpatialCapabilityComponentTypesEXT מוגדר כך:

typedef struct XrSpatialCapabilityComponentTypesEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      componentTypeCapacityInput;
    uint32_t                      componentTypeCountOutput;
    XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialCapabilityComponentTypesEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. לא מוגדרים מבנים כאלה ב-OpenXR הבסיסי או בתוסף הזה.
• ‫componentTypeCapacityInput הוא הקיבולת של המערך, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫componentTypeCountOutput הוא מספר סוגי הרכיבים, או הקיבולת הנדרשת במקרה ש-componentTypeCapacityInput לא מספיק.
• ‫componentTypes הוא מערך של XrSpatialComponentTypeEXT . הערך יכול להיות NULL אם componentTypeCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של componentTypes.

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

• התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrSpatialCapabilityComponentTypesEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ אם componentTypeCapacityInput לא שווה ל-0 , ‏ componentTypes חייב להיות מצביע למערך של ערכי componentTypeCapacityInput XrSpatialComponentTypeEXT

תכונות של יכולת מרחבית

typedef enum XrSpatialCapabilityFeatureEXT {
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT = 1000743000,
    XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT = 1000743001,
    XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT = 1000744000,
    XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID = 1000761000,
    XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID = 1000761001,
    XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID = 1000761002,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT = 1000782000,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT = 1000782001,
    XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT = 1000782002,
    XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT = 1000783000,
    XR_SPATIAL_CAPABILITY_FEATURE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialCapabilityFeatureEXT;

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

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

תכונות כאלה מיוצגות על ידי XrSpatialCapabilityFeatureEXT והאפליקציה מפרטת אותן באמצעות xrEnumerateSpatialCapabilityFeaturesEXT .

לכל תכונת יכולת יש מבנה הגדרה תואם שמאפשר להפעיל אותה. מבני ההגדרות האלה חייבים להיות משורשרים אל XrSpatialCapabilityConfigurationBaseHeaderEXT :: next של היכולת המתאימה.

הערכים האפשריים הם:

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

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_FIXED_SIZE_MARKERS_EXT

תכונת יכולת שמאפשרת לאפליקציות לציין את הגודל של הסמנים. מבנה ההגדרה המתאים הוא XrSpatialMarkerSizeEXT (נוסף על ידי התוסף XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_MARKER_TRACKING_STATIC_MARKERS_EXT

תכונת יכולת שמאפשרת לאפליקציות לציין אם הסמנים הם סטטיים. מבנה ההגדרה המתאים הוא XrSpatialMarkerStaticOptimizationEXT (נוסף על ידי התוסף XR_EXT_spatial_marker_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_OBJECT_SEMANTIC_LABEL_SUBSET_EXT

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

XR_SPATIAL_CAPABILITY_FEATURE_SPHERE_BOUNDS_FILTER_ANDROID

סביבת זמן הריצה תומכת במסנן XrSpatialBoundsSpherefANDROID עבור XrSpatialDiscoverySnapshotCreateInfoEXT. לא נדרש לכלול מבנה הגדרה במהלך יצירת ההקשר המרחבי. (נוסף על ידי התוסף XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_BOX_BOUNDS_FILTER_ANDROID

סביבת זמן הריצה תומכת במסנן XrSpatialBoundsBoxfANDROID עבור XrSpatialDiscoverySnapshotCreateInfoEXT. לא נדרש לכלול מבנה הגדרה כלשהו במהלך יצירת ההקשר המרחבי. (נוסף על ידי התוסף XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_FRUSTUM_BOUNDS_FILTER_ANDROID

סביבת זמן הריצה תומכת במסנן XrSpatialBoundsFrustumfANDROID עבור XrSpatialDiscoverySnapshotCreateInfoEXT. לא נדרש לכלול מבנה הגדרה במהלך יצירת ההקשר המרחבי. (נוסף על ידי התוסף XR_ANDROID_spatial_discovery_bounds)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_AUTOMATIC_SIZE_IMAGES_EXT

סביבת זמן הריצה תומכת בהסקה אוטומטית של הגודל הפיזי של תמונות שזוהו ועברו מעקב. מבנה ההגדרה התואם הוא XrSpatialImageSizeEXT (נוסף על ידי התוסף XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_STATIC_IMAGES_EXT

סביבת זמן הריצה תומכת ב-XrSpatialImageStaticOptimizationEXT . מבנה ההגדרה המתאים הוא XrSpatialImageStaticOptimizationEXT . (נוסף על ידי התוסף XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_IMAGE_TRACKING_FIXED_SIZE_IMAGES_EXT

סביבת זמן הריצה תומכת ב-XrSpatialImageSizeEXT . מבנה ההגדרה התואם הוא XrSpatialImageSizeEXT (נוסף על ידי התוסף XR_EXT_spatial_image_tracking)

XR_SPATIAL_CAPABILITY_FEATURE_TRACK_WATERTIGHT_MESH_EXT

תכונת יכולת למעקב אחרי רשת אטומה של הסביבה. מבנה ההגדרה המתאים הוא XrSpatialFeatureTrackWatertightMeshEXT . (נוסף על ידי התוסף XR_EXT_spatial_mesh_tracking)

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

XrResult xrEnumerateSpatialCapabilityFeaturesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    capabilityFeatureCapacityInput,
    uint32_t*                                   capabilityFeatureCountOutput,
    XrSpatialCapabilityFeatureEXT*              capabilityFeatures);

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

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

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

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

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

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

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני הקריאה ל-xrEnumerateSpatialCapabilityFeaturesEXT
• ‫ instance חייב להיות ידית XrInstance תקינה
• ‫ capability חייב להיות ערך תקין של XrSpatialCapabilityEXT
• ‫ capabilityFeatureCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם capabilityFeatureCapacityInput לא שווה ל-0 , ‏ capabilityFeatures חייב להיות מצביע למערך של capabilityFeatureCapacityInput ערכים מסוג XrSpatialCapabilityFeatureEXT

קודי החזרה

הצלחה

• XR_SUCCESS

Failure

• 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

הקשר מרחבי

יצירת הקשר מרחבי

XR_DEFINE_HANDLE(XrSpatialContextEXT)

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

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

XrResult xrCreateSpatialContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialContextCreateInfoEXT*        createInfo,
    XrFutureEXT*                                future);

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

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

האפליקציה יכולה ליצור נקודת אחיזה של XrSpatialContextEXT על ידי:

• העברת מבנים שנגזרים מ-XrSpatialCapabilityConfigurationBaseHeaderEXT ב-XrSpatialContextCreateInfoEXT :: capabilityConfigs כדי להפעיל יכולות ולהפעיל רכיבים של היכולת הזו.
• הגדרת היכולות עצמן באמצעות מבני ההגדרה התואמים של XrSpatialCapabilityFeatureEXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT אם XrSpatialContextCreateInfoEXT ::capabilityConfigCount הוא 0. ל-handle של הקשר המרחבי צריך להיות לפחות יכולת אחת.

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT אם אף אחת מהיכולות במערך XrSpatialContextCreateInfoEXT :: capabilityConfigs לא מפורטת על ידי xrEnumerateSpatialCapabilitiesEXT .

הפונקציה בזמן הריצה חייבת להחזיר XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT אם אחד מהערכים של XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponentCount ב-XrSpatialContextCreateInfoEXT :: capabilityConfigs הוא 0. הגדרת יכולת לא שלמה בלי רשימה של סוגי רכיבים שצריך להפעיל עבור היכולת הזו.

סביבת הריצה חייבת להחזיר XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT אם אף אחד מסוגי הרכיבים שמפורטים ב-XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents לא ממוספר עבור XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability ב-xrEnumerateSpatialCapabilityComponentTypesEXT .

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

סביבת זמן הריצה חייבת להחזיר XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT אם XrSpatialContextCreateInfoEXT :: capabilityConfigs מכיל כמה מבנים עם אותו XrSpatialCapabilityConfigurationBaseHeaderEXT :: capability .

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

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

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

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

• צריך להפעיל את התוסף XR_EXT_spatial_entity לפני הקריאה ל-xrCreateSpatialContextAsyncEXT
• ‫ session חייב להיות נקודת אחיזה חוקית של XrSession
• ‫ createInfo must be a pointer to a valid XrSpatialContextCreateInfoEXT structure
• ‫ future חייב להיות מצביע לערך XrFutureEXT

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_PERMISSION_INSUFFICIENT
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT
• XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT
• XR_ERROR_SPATIAL_COMPONENT_UNSUPPORTED_FOR_CAPABILITY_EXT
• XR_ERROR_VALIDATION_FAILURE

המבנה XrSpatialContextCreateInfoEXT מוגדר כך:

typedef struct XrSpatialContextCreateInfoEXT {
    XrStructureType                                                type;
    const void*                                                    next;
    uint32_t                                                       capabilityConfigCount;
    const XrSpatialCapabilityConfigurationBaseHeaderEXT* const*    capabilityConfigs;
} XrSpatialContextCreateInfoEXT;

תיאורים של חברי הקבוצה

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

המבנה XrSpatialContextCreateInfoEXT מתאר את המידע ליצירת נקודת אחיזה XrSpatialContextEXT.

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrSpatialContextCreateInfoEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים . ראו גם: XrSpatialContextPersistenceConfigEXT
• ‫ capabilityConfigs must be a pointer to an array of capabilityConfigCount valid XrSpatialCapabilityConfigurationBaseHeaderEXT -based structures. ראו גם: XrSpatialCapabilityConfigurationAnchorEXT , XrSpatialCapabilityConfigurationAprilTagEXT , XrSpatialCapabilityConfigurationArucoMarkerEXT , XrSpatialCapabilityConfigurationDepthRaycastANDROID , XrSpatialCapabilityConfigurationImageTrackingEXT , XrSpatialCapabilityConfigurationMeshTrackingEXT , XrSpatialCapabilityConfigurationMicroQrCodeEXT , XrSpatialCapabilityConfigurationObjectTrackingANDROID , XrSpatialCapabilityConfigurationObjectTrackingEXT , XrSpatialCapabilityConfigurationPlaneTrackingEXT , XrSpatialCapabilityConfigurationQrCodeEXT , XrSpatialCapabilityConfigurationRoomBoundaryTrackingANDROIDSYS , XrSpatialCapabilityConfigurationRoomTrackingANDROIDSYS , XrSpatialCapabilityConfigurationStreetscapeGeometryANDROIDX2
• ‫ הפרמטר capabilityConfigCount חייב להיות גדול מ-0

המבנה XrSpatialCapabilityConfigurationBaseHeaderEXT מוגדר כך:

typedef struct XrSpatialCapabilityConfigurationBaseHeaderEXT {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationBaseHeaderEXT;

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

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫capability הוא XrSpatialCapabilityEXT .
• ‫enabledComponentCount הוא uint32_t שמתאר את מספר האלמנטים במערך enabledComponents.
• ‫enabledComponents הוא מצביע למערך של XrSpatialComponentTypeEXT .

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

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrSpatialCapabilityConfigurationBaseHeaderEXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ capability חייב להיות ערך תקין של XrSpatialCapabilityEXT
• ‫ enabledComponents must be a pointer to an array of enabledComponentCount valid XrSpatialComponentTypeEXT values
• ‫ הפרמטר enabledComponentCount חייב להיות גדול מ-0

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

XrResult xrCreateSpatialContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialContextCompletionEXT*        completion);

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

• ‫session הוא XrSession שהועבר קודם אל xrCreateSpatialContextAsyncEXT :: session .
• ‫future הוא XrFutureEXT שהתקבל מ-xrCreateSpatialContextAsyncEXT .
• ‫completion הוא מצביע אל XrCreateSpatialContextCompletionEXT .

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

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

• צריך להפעיל את התוסף XR_EXT_spatial_entity לפני הקריאה ל-xrCreateSpatialContextCompleteEXT
• ‫ session חייב להיות נקודת אחיזה חוקית של XrSession
• ‫ completion must be a pointer to an XrCreateSpatialContextCompletionEXT structure

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

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

המבנה XrCreateSpatialContextCompletionEXT מוגדר כך:

typedef struct XrCreateSpatialContextCompletionEXT {
    XrStructureType        type;
    void*                  next;
    XrResult               futureResult;
    XrSpatialContextEXT    spatialContext;
} XrCreateSpatialContextCompletionEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫futureResult הוא XrResult של פעולת יצירת ההקשר המרחבי.
• ‫spatialContext הוא XrSpatialContextEXT שנוצר באמצעות הנתונים וההגדרות ב-xrCreateSpatialContextAsyncEXT :: createInfo .

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

ערכים של futureResult:

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT

אם futureResult הוא קוד הצלחה, spatialContext חייב להיות תקין. אם spatialContext תקף, הוא יישאר תקף רק במהלך מחזור החיים של xrCreateSpatialContextAsyncEXT :: session או עד שהאפליקציה תשמיד את spatialContext באמצעות xrDestroySpatialContextEXT , לפי המוקדם מביניהם.

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrCreateSpatialContextCompletionEXT
• ‫ type חייב להיות XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ futureResult חייב להיות ערך תקין של XrResult
• ‫ אם spatialContext הוא לא XR_NULL_HANDLE , ‏ spatialContext חייב להיות נקודת אחיזה (handle) חוקית של XrSpatialContextEXT

כיבוי סופי של ההקשר המרחבי

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

XrResult xrDestroySpatialContextEXT(
    XrSpatialContextEXT                         spatialContext);

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

• ‫spatialContext הוא XrSpatialContextEXT שנוצר קודם על ידי xrCreateSpatialContextAsyncEXT .

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

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

• ‫ XR_EXT_spatial_entity התוסף חייב להיות מופעל לפני הקריאה ל-xrDestroySpatialContextEXT
• ‫ spatialContext must be a valid XrSpatialContextEXT handle

Thread Safety

• הגישה אל spatialContext ואל כל הכינויים של הילדים חייבת להיות מסונכרנת חיצונית

קודי החזרה

הצלחה

• XR_SUCCESS

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

ייצוגים של ישויות מרחביות

מזהה ישות מרחבית

XR_DEFINE_ATOM(XrSpatialEntityIdEXT)

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

#define XR_NULL_SPATIAL_ENTITY_ID_EXT 0

‫XR_NULL_SPATIAL_ENTITY_ID_EXT הוא ערך שמור שמייצג XrSpatialEntityIdEXT לא תקין . יכול להיות שהערך יועבר לפונקציות API ויוחזר מהן רק אם הדבר מותר באופן ספציפי.

ידית של ישות מרחבית

XR_DEFINE_HANDLE(XrSpatialEntityEXT)

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

יצירת Spatial Entity Handle ממזהה

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

XrResult xrCreateSpatialEntityFromIdEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialEntityFromIdCreateInfoEXT*   createInfo,
    XrSpatialEntityEXT*                         spatialEntity);

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

• ‫spatialContext הוא XrSpatialContextEXT שנוצר קודם באמצעות xrCreateSpatialContextAsyncEXT .
• ‫createInfo הוא מצביע למבנה XrSpatialEntityFromIdCreateInfoEXT.
• ‫spatialEntity הוא ה-handle של XrSpatialEntityEXT שמוחזר.

האפליקציה יכולה להשתמש ב-xrCreateSpatialEntityFromIdEXT כדי ליצור נקודת אחיזה של XrSpatialEntityEXT, שהיא הפניה לישות שקיימת בסביבת המשתמש.

סביבת זמן הריצה חייבת להחזיר XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT אם XrSpatialEntityFromIdCreateInfoEXT :: entityId הוא לא מזהה תקין של spatialContext .

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני שמבצעים קריאה ל-xrCreateSpatialEntityFromIdEXT
• ‫ spatialContext must be a valid XrSpatialContextEXT handle
• ‫ createInfo must be a pointer to a valid XrSpatialEntityFromIdCreateInfoEXT structure
• ‫ spatialEntity must be a pointer to an XrSpatialEntityEXT handle

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

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

המבנה XrSpatialEntityFromIdCreateInfoEXT מוגדר כך:

typedef struct XrSpatialEntityFromIdCreateInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    entityId;
} XrSpatialEntityFromIdCreateInfoEXT;

תיאורים של חברי הקבוצה

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

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

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

השמדה של ידית של ישות מרחבית

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

XrResult xrDestroySpatialEntityEXT(
    XrSpatialEntityEXT                          spatialEntity);

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

• ‫spatialEntity הוא שם של XrSpatialEntityEXT שנוצר קודם על ידי פונקציה כמו xrCreateSpatialEntityFromIdEXT .

האפליקציה יכולה להשתמש ב-xrDestroySpatialEntityEXT כדי לשחרר את ה-handle של spatialEntity כשהיא כבר לא מתעניינת בישות שאליה מתייחס ה-handle הזה.

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני הקריאה ל-xrDestroySpatialEntityEXT
• ‫ spatialEntity חייב להיות נקודת אחיזה (handle) חוקית של XrSpatialEntityEXT

Thread Safety

• הגישה אל spatialEntity ואל כל הכינויים של הילדים חייבת להיות מסונכרנת חיצונית

קודי החזרה

הצלחה

• XR_SUCCESS

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

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

XR_DEFINE_HANDLE(XrSpatialSnapshotEXT)

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

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

יצירת תמונת מצב של Discovery

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

XrResult xrCreateSpatialDiscoverySnapshotAsyncEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialDiscoverySnapshotCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

• ‫spatialContext הוא XrSpatialContextEXT שנוצר קודם באמצעות xrCreateSpatialContextAsyncEXT .
• ‫createInfo הוא מצביע אל XrSpatialDiscoverySnapshotCreateInfoEXT .
• ‫future הוא מצביע ל-XrFutureEXT .

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

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

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

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

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT אם אף אחד מהערכים של XrSpatialComponentTypeEXT ב-XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes לא מופעל עבור היכולות המרחביות שמועברות אל XrSpatialContextCreateInfoEXT :: capabilityConfigs כשיוצרים את spatialContext .

אם האפליקציה לא מספקת רשימה של סוגי רכיבים מרחביים ב-XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes , סביבת הריצה חייבת לכלול בתמונה את כל הישויות המרחביות שיש להן את קבוצת הרכיבים שמפורטים ב-XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents עבור היכולות שהוגדרו ל-spatialContext . סביבת זמן הריצה חייבת לכלול את הנתונים של כל הרכיבים המופעלים של היכולות שהוגדרו עבור spatialContext .

אם XrEventDataReferenceSpaceChangePending מתווסף לתור לפני השלמת future, ו-XrEventDataReferenceSpaceChangePending :: poseValid הוא false, אז זמן הריצה עשוי ליצור XrSpatialSnapshotEXT שלא מכיל ישויות, או להגדיר את XrSpatialEntityTrackingStateEXT של הישויות שכבר לא ניתן לאתר ב-XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace ב-XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time ל-XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT או ל-XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT . זמן הריצה לא יכול להגדיר את XrCreateSpatialContextCompletionEXT :: futureResult לקוד שגיאה בגלל XrEventDataReferenceSpaceChangePending .

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמתקשרים אל xrCreateSpatialDiscoverySnapshotAsyncEXT
• ‫ spatialContext must be a valid XrSpatialContextEXT handle
• ‫ createInfo must be a pointer to a valid XrSpatialDiscoverySnapshotCreateInfoEXT structure
• ‫ future חייב להיות מצביע לערך XrFutureEXT

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

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

המבנה XrSpatialDiscoverySnapshotCreateInfoEXT מוגדר כך:

typedef struct XrSpatialDiscoverySnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialDiscoverySnapshotCreateInfoEXT;

תיאורים של חברי הקבוצה

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

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

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני השימוש ב-XrSpatialDiscoverySnapshotCreateInfoEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים . ראו גם: XrSpatialBoundsBoxfANDROID , ‏ XrSpatialBoundsFrustumfANDROID , ‏ XrSpatialBoundsSpherefANDROID , ‏ XrSpatialDiscoveryPersistenceUuidFilterEXT , ‏ XrSpatialDiscoveryRoomBoundaryFilterANDROIDSYS , ‏ XrSpatialDiscoveryUniqueEntitiesFilterANDROID , ‏ XrSpatialFilterTrackingStateEXT , ‏ XrSpatialRaycastInfoANDROID
• ‫ אם componentTypeCount לא 0 , ‏ componentTypes חייב להיות מצביע למערך של componentTypeCount ערכים תקינים של XrSpatialComponentTypeEXT

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

XrResult xrCreateSpatialDiscoverySnapshotCompleteEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrCreateSpatialDiscoverySnapshotCompletionInfoEXT* createSnapshotCompletionInfo,
    XrCreateSpatialDiscoverySnapshotCompletionEXT* completion);

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

• ‫spatialContext הוא XrSpatialContextEXT שהועבר קודם אל xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext .
• ‫createSnapshotCompletionInfo הוא מצביע אל XrCreateSpatialDiscoverySnapshotCompletionInfoEXT שמספק מידע על השלמת הבקשה ליצירת תמונת מצב של גילוי מרחבי.
• ‫completion הוא מצביע אל XrCreateSpatialDiscoverySnapshotCompletionEXT .

‫xrCreateSpatialDiscoverySnapshotCompleteEXT משלים את הפעולה האסינכרונית שהתחילה על ידי xrCreateSpatialDiscoverySnapshotAsyncEXT . סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_FUTURE_PENDING_EXT אם XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future לא במצב מוכן. סביבת זמן הריצה חייבת להחזיר XR_ERROR_FUTURE_INVALID_EXT אם הפונקציה XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: future כבר הושלמה או בוטלה.

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני שמתקשרים אל xrCreateSpatialDiscoverySnapshotCompleteEXT
• ‫ spatialContext must be a valid XrSpatialContextEXT handle
• ‫ createSnapshotCompletionInfo must be a pointer to a valid XrCreateSpatialDiscoverySnapshotCompletionInfoEXT structure
• ‫ completion must be a pointer to an XrCreateSpatialDiscoverySnapshotCompletionEXT structure

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

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

המבנה XrCreateSpatialDiscoverySnapshotCompletionInfoEXT מוגדר כך:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionInfoEXT {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrFutureEXT        future;
} XrCreateSpatialDiscoverySnapshotCompletionInfoEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫baseSpace הוא XrSpace שבו ימוקמו כל המיקומים של XrSpatialSnapshotEXT.
• ‫time הוא XrTime שבו ימוקמו כל המיקומים של החשיפה XrSpatialSnapshotEXT.
• ‫future הוא XrFutureEXT שהתקבל מ-xrCreateSpatialDiscoverySnapshotAsyncEXT

המיקומים בנתוני הרכיבים השונים שנכללים בתמונת המצב שנוצרה ייוצגו ב-baseSpace , שנמצא ב-time .

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
• ‫ type חייב להיות XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• baseSpace חייב להיות כינוי תקין ב-XrSpace

המבנה XrCreateSpatialDiscoverySnapshotCompletionEXT מוגדר כך:

typedef struct XrCreateSpatialDiscoverySnapshotCompletionEXT {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialSnapshotEXT    snapshot;
} XrCreateSpatialDiscoverySnapshotCompletionEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫futureResult הוא XrResult של פעולת יצירת תמונת מצב של גילוי מרחבי.
• ‫snapshot הוא XrSpatialSnapshotEXT שאפשר להשתמש בו כדי לשלוח שאילתות לגבי נתוני הרכיבים של הישויות המרחביות שזוהו.

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

ערכים של futureResult:

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_SESSION_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_LIMIT_REACHED

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrCreateSpatialDiscoverySnapshotCompletionEXT
• ‫ type חייב להיות XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ futureResult חייב להיות ערך תקין של XrResult
• ‫ אם snapshot הוא לא XR_NULL_HANDLE , ‏ snapshot חייב להיות נקודת אחיזה (handle) חוקית של XrSpatialSnapshotEXT

אירוע המלצה על גילוי

המבנה XrEventDataSpatialDiscoveryRecommendedEXT מוגדר כך:

typedef struct XrEventDataSpatialDiscoveryRecommendedEXT {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
} XrEventDataSpatialDiscoveryRecommendedEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫spatialContext הוא XrSpatialContextEXT שהסביבה בזמן הריצה ממליצה עליו.

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

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

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

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

זמן הריצה לא יכול להוסיף את האירוע הזה לתור עבור spatialContext עד שהאפליקציה מסיימת את היצירה שלה באמצעות xrCreateSpatialContextCompleteEXT .

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

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

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

שאילתות לגבי נתוני רכיבים

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

XrResult xrQuerySpatialComponentDataEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialComponentDataQueryConditionEXT* queryCondition,
    XrSpatialComponentDataQueryResultEXT*       queryResult);

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

• ‫snapshot הוא XrSpatialSnapshotEXT שסופק בעבר על ידי xrCreateSpatialDiscoverySnapshotCompleteEXT או xrCreateSpatialUpdateSnapshotEXT .
• ‫queryCondition הוא מצביע למבנה XrSpatialComponentDataQueryConditionEXT.
• ‫queryResult הוא מצביע למבנה XrSpatialComponentDataQueryResultEXT.

האפליקציה יכולה להשתמש ב-xrQuerySpatialComponentDataEXT כדי לשלוח שאילתה לגבי נתוני הרכיבים של הישויות בתמונת המצב. לשם כך, צריך לצרף מבנה רשימה ל-XrSpatialComponentDataQueryResultEXT :: next שמתאים לכל XrSpatialComponentTypeEXT ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes .

אם האפליקציה מצרפת מבנה רשימה אל XrSpatialComponentDataQueryResultEXT :: next שלא תואם לאף אחד מהרכיבים שמופיעים ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes , סביבת הריצה חייבת להחזיר XR_ERROR_VALIDATION_FAILURE .

האפליקציה יכולה לבחור לצרף את מבני הרשימה שמתאימים רק לקבוצת משנה של רכיבים שמופיעים ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes . האפליקציה יכולה לבחור להשמיט לחלוטין את מבני הרשימה אם היא רוצה לדעת רק את המזהים ואת מצב המעקב של הישויות המרחביות שעומדות בדרישות של queryCondition . זמן הריצה לא יכול להתייחס להיעדר מבני רשימה מהשרשרת XrSpatialComponentDataQueryResultEXT :: next כאל כשל.

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

סביבת זמן הריצה חייבת לאכלס את XrSpatialComponentDataQueryResultEXT :: entityIds רק עם ישויות שיש להן את כל הרכיבים שצוינו ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes . אם הערך של XrSpatialComponentDataQueryConditionEXT :: componentTypeCount הוא 0, סביבת הריצה חייבת לאכלס את queryResult בכל הישויות (ומצבי המעקב שלהן) שנמצאות בתמונת המצב. אם מוסיפים תנאי שאילתה נוספים ל-XrSpatialComponentDataQueryConditionEXT :: next , סביבת הריצה חייבת להתייחס אליהם כאל 'AND' עם הזמינות של סוגי הרכיבים, כלומר סביבת הריצה חייבת לאכלס את XrSpatialComponentDataQueryResultEXT ::entityIds רק עם ישויות שעומדות בכל התנאים שסופקו. סביבת הריצה חייבת לאכלס את נתוני הרכיב במבני הרשימה באותו סדר שבו הישויות מופיעות ב-XrSpatialComponentDataQueryResultEXT :: entityIds כלומר, נתוני הרכיב באינדקס נתון במערך מבנה הרשימה חייבים להתאים לישות באותו אינדקס.

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

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני הקריאה ל-xrQuerySpatialComponentDataEXT
• ‫ snapshot חייב להיות נקודת אחיזה (handle) תקינה של XrSpatialSnapshotEXT
• ‫ queryCondition must be a pointer to a valid XrSpatialComponentDataQueryConditionEXT structure
• ‫ queryResult must be a pointer to an XrSpatialComponentDataQueryResultEXT structure

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_VALIDATION_FAILURE

לדוגמה, האפליקציה יוצרת XrSpatialSnapshotEXT שמכיל 5 ישויות, כאשר –

• לישות 1 ולישות 2 יש רכיבים XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT ו-XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT
• לישויות 3 ו-4 יש רכיבים XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT ו-XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT
• לישות 5 יש רכיבים XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT ו-XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT .

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

3

3

4

4

5

5

Bounded2D

Bounded2D

כן

כן

כן

כן

לא

לא

לא

לא

כן

כן

הורה

הורה

כן

כן

כן

כן

לא

לא

לא

לא

לא

לא

Mesh3D

Mesh3D

לא

לא

לא

לא

כן

כן

כן

כן

כן

כן

Bounded3D

Bounded3D

לא

לא

לא

לא

כן

כן

כן

כן

לא

No Text is not SVG - cannot display

איור 20. תמונת מצב לדוגמה

‫xrQuerySpatialComponentDataEXT בתמונת המצב שלמעלה עם XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT שמופיע בתנאי השאילתה יחזיר את ישות מס' 1, מס' 2 ומס' 5 לאפליקציה, והאפליקציה יכולה לצרף מערך של XrSpatialBounded2DDataEXT כחלק מהמבנה XrSpatialComponentBounded2DListEXT לשרשרת הבאה של XrSpatialComponentDataQueryResultEXT כדי לקבל את נתוני ה-bounded2D.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

1

1

2

2

5

5

Bounded2D

Bounded2D

נתונים של entityId מספר 1

נתונים של ישות...

נתונים של entityId מספר 2

נתונים של ישות...

נתונים של entityId מספר 5

נתונים של ישות...

entityIds

entityIds

הבא

הבא

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Dat...

גבולות

גבולות

XrSpatialComponent
Bounded2DListEXT

XrSpatialComponent
Bou... הטקסט הוא לא SVG – אי אפשר להציג אותו

איור 21. תוצאה לדוגמה של שאילתה

‫xrQuerySpatialComponentDataEXT בתמונת המצב שלמעלה עם רכיבים XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT ו-XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT שמופיעים בתנאי השאילתה יגרמו להחזרת ישות מס' 3 ומס' 4 לאפליקציה, והאפליקציה יכולה לצרף מערכים של XrBoxf ו-XrSpatialMeshDataEXT כחלק מהמבנים XrSpatialComponentBounded3DListEXT ו-XrSpatialComponentMesh3DListEXT בהתאמה לשרשרת הבאה של XrSpatialComponentDataQueryResultEXT כדי לקבל את נתוני הרכיב.

XrSpatialEntityIdEXT

XrSpatialEntityIdEXT

3

3

4

4

Bounded3D

Bounded3D

נתונים של entityId מס' 3

נתונים של ישות...

נתונים של entityId מספר 4

נתונים של ישות...

Mesh3D

Mesh3D

נתונים של entityId מס' 3

נתונים של ישות...

נתונים של entityId מספר 4

נתונים של ישות...

entityIds

entityIds

הבא

הבא

XrSpatialComponent
DataQueryResultEXT

XrSpatialComponent
Da...

גבולות

גבולות

הבא

הבא

XrSpatialComponent
Bounded3DListEXT

XrSpatialComponent
Bo...

XrSpatialComponent
Mesh3DListEXT

XrSpatialComponent
Me...

רשתות

meshes Text is not SVG - cannot display

איור 22. תוצאה לדוגמה של שאילתה

המבנה XrSpatialComponentDataQueryConditionEXT מוגדר כך:

typedef struct XrSpatialComponentDataQueryConditionEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
} XrSpatialComponentDataQueryConditionEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫componentTypeCount הוא uint32_t שמתאר את מספר האלמנטים במערך componentTypes.
• ‫componentTypes הוא מערך של XrSpatialComponentTypeEXT שמהם רוצים לקבל את הנתונים מהתמונה.

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrSpatialComponentDataQueryConditionEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים . ראו גם: XrSpatialDiscoveryPersistenceUuidFilterEXT , XrSpatialFilterArchetypeEXT , XrSpatialFilterTrackingStateEXT
• ‫ אם componentTypeCount לא 0 , ‏ componentTypes חייב להיות מצביע למערך של componentTypeCount ערכים תקינים של XrSpatialComponentTypeEXT

המבנה XrSpatialComponentDataQueryResultEXT מוגדר כך:

typedef struct XrSpatialComponentDataQueryResultEXT {
    XrStructureType                     type;
    void*                               next;
    uint32_t                            entityIdCapacityInput;
    uint32_t                            entityIdCountOutput;
    XrSpatialEntityIdEXT*               entityIds;
    uint32_t                            entityStateCapacityInput;
    uint32_t                            entityStateCountOutput;
    XrSpatialEntityTrackingStateEXT*    entityStates;
} XrSpatialComponentDataQueryResultEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫entityIdCapacityInput הוא הקיבולת של המערך entityIds, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫entityIdCountOutput הוא מספר XrSpatialEntityIdEXT ב-entityIds , או הקיבולת הנדרשת במקרה ש-entityIdCapacityInput לא מספיק.
• ‫entityIds הוא מערך של XrSpatialEntityIdEXT . הערך יכול להיות NULL אם entityIdCapacityInput הוא 0.
• ‫entityStateCapacityInput הוא הקיבולת של המערך entityStates, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫entityStateCountOutput הוא מספר XrSpatialEntityTrackingStateEXT ב-entityStates , או הקיבולת הנדרשת במקרה ש-entityStateCapacityInput לא מספיק. הערך הזה חייב להיות תמיד זהה לערך של entityIdCountOutput .
• ‫entityStates הוא מערך של XrSpatialEntityTrackingStateEXT . הערך יכול להיות NULL אם entityStateCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של entityIds.

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

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrSpatialComponentDataQueryResultEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT
• ‫ next חייב להיות NULL או מצביע תקין למבנה הבא בשרשרת מבנים . ראו גם: XrSpatialComponentAnchorListEXT , XrSpatialComponentAnnotationQuadListANDROID , XrSpatialComponentBounded2DListEXT , XrSpatialComponentBounded3DListEXT , XrSpatialComponentConfidenceListANDROIDSYS , XrSpatialComponentImage2DListEXT , XrSpatialComponentKeyboardSemanticLabelListEXT , XrSpatialComponentMarkerListEXT , XrSpatialComponentMaterialTypeListANDROIDSYS , XrSpatialComponentMesh2DListEXT , XrSpatialComponentMesh3DListEXT , XrSpatialComponentMesh3DNormalsListEXT , XrSpatialComponentMesh3DTriangleSemanticLabelsListEXT , XrSpatialComponentMesh3DVertexSemanticLabelsListEXT , XrSpatialComponentMouseSemanticLabelListEXT , XrSpatialComponentObjectSemanticLabelListANDROID , XrSpatialComponentObjectSemanticLabelListEXT , XrSpatialComponentOccupancyGridListANDROIDX1 , XrSpatialComponentParentListEXT , XrSpatialComponentPersistenceListEXT , XrSpatialComponentPlaneAlignmentListEXT , XrSpatialComponentPlaneSemanticLabelListEXT , XrSpatialComponentPolygon2DListEXT , XrSpatialComponentRaycastResultListANDROID , XrSpatialComponentRoomEmptinessListANDROIDSYS , XrSpatialComponentRoomListANDROIDSYS , XrSpatialComponentStreetscapeGeometryMetadataListANDROIDX2 , XrSpatialComponentSubsumedByListANDROID
• ‫ אם entityIdCapacityInput לא שווה ל-0 , entityIds חייב להיות מצביע למערך של entityIdCapacityInput ערכי XrSpatialEntityIdEXT
• ‫ אם entityStateCapacityInput לא שווה ל-0 , ‏ entityStates חייב להיות מצביע למערך של entityStateCapacityInput ערכים מסוג XrSpatialEntityTrackingStateEXT

typedef enum XrSpatialEntityTrackingStateEXT {
    XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT = 1,
    XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT = 2,
    XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT = 3,
    XR_SPATIAL_ENTITY_TRACKING_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialEntityTrackingStateEXT;

הספירה XrSpatialEntityTrackingStateEXT מפרטת את המצבים האפשריים של מעקב אחר ישויות מרחביות:

המשמעויות של ה-enums הן:

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

XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT

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

XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT

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

XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT

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

מעקב

מושהה

הופסקה

איור 23. XrSpatialEntityTrackingStateEXT

• סביבת זמן הריצה עשויה לשנות את הסטטוס של הישות המרחבית מ-XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT ל-XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT אם היא משעה את המעקב אחרי הישות המרחבית הזו, אבל יש אפשרות לחדש את המעקב בעתיד. דוגמאות למקרים שבהם סביבת זמן הריצה עשויה לעשות זאת כוללות (אך לא מוגבלות למקרים הבאים): אם האפליקציה מאבדת את מיקוד הקלט, אם הישות המרחבית שצוינה רחוקה מדי מהמשתמש כדי לעקוב אחריה בצורה מדויקת, או אם יש יותר מדי ישויות במעקב וסביבת זמן הריצה רוצה להפחית את עלות המעקב. ‫XrSpatialEntityTrackingStateEXT עוזר לאפליקציה לבודד את עצמה ממדיניות המעקב השונה של כל זמן ריצה.
• סביבת זמן הריצה עשויה לשנות את המצב של ישות מ-XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT ל-XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT או ל-XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT .
• סביבת זמן הריצה חייבת לשנות את המצב של הישות המרחבית מ-XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT או מ-XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT ל-XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT אם הישות המרחבית אבדה ולא ניתן לשחזר או לחדש את המעקב אחריה. דוגמה למקרה כזה היא אם המעקב אחר המכשיר נפסק, סשן המעקב מופעל מחדש אבל המכשיר לא מצליח לאתר את עצמו מחדש בסביבה שלו, ולכן הוא מתייחס לישויות שזוהו בסשן המעקב הזה כישויות חדשות.
• אחרי שסטטוס המעקב של ישות מוגדר ל-XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT , זמן הריצה אף פעם לא יכול לשנות אותו לסטטוס אחר.
• כששולחים שאילתה לנתוני הרכיב של ישות מרחבית באמצעות xrQuerySpatialComponentDataEXT , סביבת זמן הריצה חייבת להגדיר נתונים תקינים בתוכן של המאגרים שסופקו על ידי האפליקציה בשרשרת הבאה של XrSpatialComponentDataQueryResultEXT אם מצב הישות הוא XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT . אם מצב הישות הוא XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT או XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT , סביבת זמן הריצה לא יכולה לשנות את תוכן המאגרים.

שתי קריאות לנתוני רכיב

המבנה XrSpatialBufferEXT מוגדר כך:

typedef struct XrSpatialBufferEXT {
    XrSpatialBufferIdEXT      bufferId;
    XrSpatialBufferTypeEXT    bufferType;
} XrSpatialBufferEXT;

תיאורים של חברי הקבוצה

• bufferId של נתוני המאגר.XrSpatialBufferIdEXT
• ‫bufferType הוא XrSpatialBufferTypeEXT כדי לציין את סוג הנתונים ב-bufferId . האפליקציה יכולה להשתמש ב-bufferType כדי לקבוע באיזו פונקציה להשתמש כדי לאחזר את הנתונים בפועל של המאגר.

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

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

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrSpatialBufferEXT
• ‫ bufferType חייב להיות ערך תקין של XrSpatialBufferTypeEXT

XR_DEFINE_ATOM(XrSpatialBufferIdEXT)

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

סביבת זמן הריצה חייבת לשמור את XrSpatialBufferIdEXT ואת הנתונים שלו בזיכרון למשך מחזור החיים של XrSpatialSnapshotEXT שמכיל אותו. סביבת הריצה עשויה לשמור את XrSpatialBufferIdEXT ואת הנתונים שלו בזיכרון למשך זמן ארוך יותר ממחזור החיים של XrSpatialSnapshotEXT כדי להחזיר את אותו מזהה כחלק מתמונות מצב שנוצרו בהמשך על ידי האפליקציה. עבור אותו XrSpatialBufferIdEXT , זמן הריצה חייב תמיד להחזיר את אותם נתונים באמצעות הפונקציה המתאימה xrGetSpatialBuffer*.

typedef enum XrSpatialBufferTypeEXT {
    XR_SPATIAL_BUFFER_TYPE_UNKNOWN_EXT = 0,
    XR_SPATIAL_BUFFER_TYPE_STRING_EXT = 1,
    XR_SPATIAL_BUFFER_TYPE_UINT8_EXT = 2,
    XR_SPATIAL_BUFFER_TYPE_UINT16_EXT = 3,
    XR_SPATIAL_BUFFER_TYPE_UINT32_EXT = 4,
    XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT = 5,
    XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT = 6,
    XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT = 7,
    XR_SPATIAL_BUFFER_TYPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialBufferTypeEXT;

הספירה XrSpatialBufferTypeEXT מזהה את סוגי הנתונים השונים של המאגר שמיוצג על ידי XrSpatialBufferIdEXT .

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

• XR_SPATIAL_BUFFER_TYPE_STRING_EXT . אפשר להעביר את XrSpatialBufferIdEXT can אל xrGetSpatialBufferStringEXT כדי לאחזר מאגר מחרוזות.
• XR_SPATIAL_BUFFER_TYPE_UINT8_EXT . אפשר להעביר את XrSpatialBufferIdEXT ל-xrGetSpatialBufferUint8EXT כדי לאחזר מאגר uint8_t.
• XR_SPATIAL_BUFFER_TYPE_UINT16_EXT . אפשר להעביר את XrSpatialBufferIdEXT ל-xrGetSpatialBufferUint16EXT כדי לאחזר מאגר uint16_t.
• XR_SPATIAL_BUFFER_TYPE_UINT32_EXT . אפשר להעביר את XrSpatialBufferIdEXT can אל xrGetSpatialBufferUint32EXT כדי לאחזר מאגר uint32_t.
• XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT . אפשר להעביר את XrSpatialBufferIdEXT can אל xrGetSpatialBufferFloatEXT כדי לאחזר מאגר float.
• XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT . אפשר להעביר את XrSpatialBufferIdEXT ל-xrGetSpatialBufferVector2fEXT כדי לאחזר מאגר XrVector2f.
• XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT . אפשר להעביר את XrSpatialBufferIdEXT can אל xrGetSpatialBufferVector3fEXT כדי לאחזר מאגר XrVector3f.

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

XrResult xrGetSpatialBufferStringEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    char*                                       buffer);

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

• ‫snapshot הוא נקודת אחיזה ל-XrSpatialSnapshotEXT .
• info מכיל את המידע על המאגר שאותו רוצים לשאול.
• ‫bufferCapacityInput הוא הקיבולת של המערך, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫bufferCountOutput הוא מספר התווים, או הקיבולת הנדרשת במקרה ש-bufferCapacityInput לא מספיק.
• ‫buffer הוא מערך של char . הערך יכול להיות NULL אם bufferCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של buffer.

האפליקציה יכולה לקבל את הנתונים של XrSpatialBufferEXT שסופק על ידי רכיב, כאשר XrSpatialBufferEXT :: bufferType הוא XR_SPATIAL_BUFFER_TYPE_STRING_EXT באמצעות xrGetSpatialBufferStringEXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialBufferTypeEXT עבור XrSpatialBufferGetInfoEXT :: bufferId הוא לא XR_SPATIAL_BUFFER_TYPE_STRING_EXT .

סביבת זמן הריצה חייבת להחזיר XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT אם XrSpatialBufferGetInfoEXT :: bufferId לא שייך ל-snapshot .

buffer שמוזן על ידי זמן הריצה חייב להיות מחרוזת UTF-8 שמסתיימת בערך null.

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני הקריאה ל-xrGetSpatialBufferStringEXT
• ‫ snapshot חייב להיות נקודת אחיזה (handle) תקינה של XrSpatialSnapshotEXT
• ‫ info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
• ‫ bufferCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם bufferCapacityInput לא שווה ל-0 , ‏ buffer חייב להיות מצביע למערך של ערכי char‏ bufferCapacityInput

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
• XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferUint8EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint8_t*                                    buffer);

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

• ‫snapshot הוא נקודת אחיזה ל-XrSpatialSnapshotEXT .
• info מכיל את המידע על המאגר שאותו רוצים לשאול.
• ‫bufferCapacityInput הוא הקיבולת של המערך, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫bufferCountOutput הוא מספר הרכיבים במערך buffer, או הקיבולת הנדרשת במקרה ש-bufferCapacityInput לא מספיק.
• ‫buffer הוא מערך של uint8_t . הערך יכול להיות NULL אם bufferCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של buffer.

האפליקציה יכולה לקבל את הנתונים של XrSpatialBufferEXT שסופק על ידי רכיב, כאשר XrSpatialBufferEXT :: bufferType הוא XR_SPATIAL_BUFFER_TYPE_UINT8_EXT באמצעות xrGetSpatialBufferUint8EXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialBufferTypeEXT עבור XrSpatialBufferGetInfoEXT :: bufferId הוא לא XR_SPATIAL_BUFFER_TYPE_UINT8_EXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT אם XrSpatialBufferGetInfoEXT :: bufferId לא שייך ל-snapshot .

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_entity לפני הקריאה ל-xrGetSpatialBufferUint8EXT
• ‫ snapshot must be a valid XrSpatialSnapshotEXT handle
• ‫ info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
• ‫ bufferCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם bufferCapacityInput לא שווה ל-0 , buffer חייב להיות מצביע למערך של bufferCapacityInput ערכי uint8_t

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
• XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferUint16EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint16_t*                                   buffer);

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

• ‫snapshot הוא נקודת אחיזה ל-XrSpatialSnapshotEXT .
• info מכיל את המידע על המאגר שאותו רוצים לשאול.
• ‫bufferCapacityInput הוא הקיבולת של המערך, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫bufferCountOutput הוא מספר הרכיבים במערך buffer, או הקיבולת הנדרשת במקרה ש-bufferCapacityInput לא מספיק.
• ‫buffer הוא מערך של uint16_t . הערך יכול להיות NULL אם bufferCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של buffer.

האפליקציה יכולה לקבל את הנתונים של XrSpatialBufferEXT שסופק על ידי רכיב, כאשר XrSpatialBufferEXT :: bufferType הוא XR_SPATIAL_BUFFER_TYPE_UINT16_EXT באמצעות xrGetSpatialBufferUint16EXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialBufferTypeEXT עבור XrSpatialBufferGetInfoEXT :: bufferId הוא לא XR_SPATIAL_BUFFER_TYPE_UINT16_EXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT אם XrSpatialBufferGetInfoEXT :: bufferId לא שייך ל-snapshot .

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני הקריאה ל-xrGetSpatialBufferUint16EXT
• ‫ snapshot חייב להיות נקודת אחיזה (handle) תקינה של XrSpatialSnapshotEXT
• ‫ info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
• ‫ bufferCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם bufferCapacityInput לא שווה ל-0 , buffer חייב להיות מצביע למערך של bufferCapacityInput ערכי uint16_t

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
• XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferUint32EXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    uint32_t*                                   buffer);

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

• ‫snapshot הוא נקודת אחיזה ל-XrSpatialSnapshotEXT .
• info מכיל את המידע על המאגר שאותו רוצים לשאול.
• ‫bufferCapacityInput הוא הקיבולת של המערך, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫bufferCountOutput הוא מספר הרכיבים במערך buffer, או הקיבולת הנדרשת במקרה ש-bufferCapacityInput לא מספיק.
• ‫buffer הוא מערך של uint32_t . הערך יכול להיות NULL אם bufferCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של buffer.

האפליקציה יכולה לקבל את הנתונים של XrSpatialBufferEXT שסופק על ידי רכיב, כאשר XrSpatialBufferEXT :: bufferType הוא XR_SPATIAL_BUFFER_TYPE_UINT32_EXT באמצעות xrGetSpatialBufferUint32EXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialBufferTypeEXT עבור XrSpatialBufferGetInfoEXT :: bufferId הוא לא XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

סביבת זמן הריצה חייבת להחזיר XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT אם XrSpatialBufferGetInfoEXT :: bufferId לא שייך ל-snapshot .

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני הקריאה ל-xrGetSpatialBufferUint32EXT
• ‫ snapshot חייב להיות נקודת אחיזה (handle) תקינה של XrSpatialSnapshotEXT
• ‫ info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
• ‫ bufferCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם bufferCapacityInput לא שווה ל-0 , buffer חייב להיות מצביע למערך של bufferCapacityInput ערכי uint32_t

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
• XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferFloatEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    float*                                      buffer);

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

• ‫snapshot הוא נקודת אחיזה ל-XrSpatialSnapshotEXT .
• info מכיל את המידע על המאגר שאותו רוצים לשאול.
• ‫bufferCapacityInput הוא הקיבולת של המערך, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫bufferCountOutput הוא מספר הרכיבים במערך buffer, או הקיבולת הנדרשת במקרה ש-bufferCapacityInput לא מספיק.
• ‫buffer הוא מערך של float . הערך יכול להיות NULL אם bufferCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של buffer.

האפליקציה יכולה לקבל את הנתונים של XrSpatialBufferEXT שסופק על ידי רכיב, כאשר XrSpatialBufferEXT :: bufferType הוא XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT באמצעות xrGetSpatialBufferFloatEXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialBufferTypeEXT עבור XrSpatialBufferGetInfoEXT :: bufferId הוא לא XR_SPATIAL_BUFFER_TYPE_FLOAT_EXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT אם XrSpatialBufferGetInfoEXT :: bufferId לא שייך ל-snapshot .

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני הקריאה ל-xrGetSpatialBufferFloatEXT
• ‫ snapshot חייב להיות נקודת אחיזה (handle) תקינה של XrSpatialSnapshotEXT
• ‫ info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
• ‫ bufferCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם bufferCapacityInput לא שווה ל-0 , buffer חייב להיות מצביע למערך של bufferCapacityInput ערכי float

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
• XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferVector2fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector2f*                                 buffer);

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

• ‫snapshot הוא נקודת אחיזה ל-XrSpatialSnapshotEXT .
• info מכיל את המידע על המאגר שאותו רוצים לשאול.
• ‫bufferCapacityInput הוא הקיבולת של המערך, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫bufferCountOutput הוא מספר הרכיבים במערך buffer, או הקיבולת הנדרשת במקרה ש-bufferCapacityInput לא מספיק.
• ‫buffer הוא מערך של XrVector2f . הערך יכול להיות NULL אם bufferCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של buffer.

האפליקציה יכולה לקבל את הנתונים של XrSpatialBufferEXT שסופק על ידי רכיב, כאשר XrSpatialBufferEXT :: bufferType הוא XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT באמצעות xrGetSpatialBufferVector2fEXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialBufferTypeEXT עבור XrSpatialBufferGetInfoEXT :: bufferId הוא לא XR_SPATIAL_BUFFER_TYPE_VECTOR2F_EXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT אם XrSpatialBufferGetInfoEXT :: bufferId לא שייך ל-snapshot .

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני הקריאה ל-xrGetSpatialBufferVector2fEXT
• ‫ snapshot חייב להיות נקודת אחיזה (handle) תקינה של XrSpatialSnapshotEXT
• ‫ info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
• ‫ bufferCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם bufferCapacityInput לא שווה ל-0 , buffer חייב להיות מצביע למערך של bufferCapacityInput מבני XrVector2f

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
• XR_ERROR_VALIDATION_FAILURE

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

XrResult xrGetSpatialBufferVector3fEXT(
    XrSpatialSnapshotEXT                        snapshot,
    const XrSpatialBufferGetInfoEXT*            info,
    uint32_t                                    bufferCapacityInput,
    uint32_t*                                   bufferCountOutput,
    XrVector3f*                                 buffer);

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

• ‫snapshot הוא נקודת אחיזה ל-XrSpatialSnapshotEXT .
• info מכיל את המידע על המאגר שאותו רוצים לשאול.
• ‫bufferCapacityInput הוא הקיבולת של המערך, או 0 כדי לציין בקשה לאחזור הקיבולת הנדרשת.
• ‫bufferCountOutput הוא מספר הרכיבים במערך buffer, או הקיבולת הנדרשת במקרה ש-bufferCapacityInput לא מספיק.
• ‫buffer הוא מערך של XrVector3f . הערך יכול להיות NULL אם bufferCapacityInput הוא 0.
• בקטע פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של buffer.

האפליקציה יכולה לקבל את הנתונים של XrSpatialBufferEXT שסופק על ידי רכיב, כאשר XrSpatialBufferEXT :: bufferType הוא XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT באמצעות xrGetSpatialBufferVector3fEXT .

סביבת זמן הריצה חייבת להחזיר את הערך XR_ERROR_VALIDATION_FAILURE אם XrSpatialBufferTypeEXT עבור XrSpatialBufferGetInfoEXT :: bufferId הוא לא XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT .

סביבת זמן הריצה חייבת להחזיר XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT אם XrSpatialBufferGetInfoEXT :: bufferId לא שייך ל-snapshot .

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני הקריאה ל-xrGetSpatialBufferVector3fEXT
• ‫ snapshot חייב להיות נקודת אחיזה (handle) תקינה של XrSpatialSnapshotEXT
• ‫ info must be a pointer to a valid XrSpatialBufferGetInfoEXT structure
• ‫ bufferCountOutput חייב להיות מצביע לערך uint32_t
• ‫ אם bufferCapacityInput לא שווה ל-0 , ‏ buffer חייב להיות מצביע למערך של bufferCapacityInput מבני XrVector3f

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SIZE_INSUFFICIENT
• XR_ERROR_SPATIAL_BUFFER_ID_INVALID_EXT
• XR_ERROR_VALIDATION_FAILURE

המבנה XrSpatialBufferGetInfoEXT מוגדר כך:

typedef struct XrSpatialBufferGetInfoEXT {
    XrStructureType         type;
    const void*             next;
    XrSpatialBufferIdEXT    bufferId;
} XrSpatialBufferGetInfoEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫bufferId XrSpatialBufferIdEXT למאגר שרוצים לאחזר ממנו נתונים.

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

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

#define XR_NULL_SPATIAL_BUFFER_ID_EXT 0

‫XR_NULL_SPATIAL_BUFFER_ID_EXT הוא ערך שמור שמייצג XrSpatialBufferIdEXT לא חוקי . יכול להיות שהערך יועבר לפונקציות API ויוחזר מהן רק אם הדבר מותר באופן ספציפי.

יצירת קובץ snapshot של עדכון

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

XrResult xrCreateSpatialUpdateSnapshotEXT(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialUpdateSnapshotCreateInfoEXT* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

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

• ‫spatialContext הוא XrSpatialContextEXT שנוצר קודם באמצעות xrCreateSpatialContextAsyncEXT .
• ‫createInfo הוא מצביע אל XrSpatialUpdateSnapshotCreateInfoEXT .
• ‫snapshot הוא מצביע לתוצאה XrSpatialSnapshotEXT .

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

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

הפונקציה בזמן הריצה חייבת להחזיר את הערך XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT אם אף אחת מהפונקציות XrSpatialComponentTypeEXT ב-XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes לא מופעלת עבור היכולות המרחביות שמועברות אל XrSpatialContextCreateInfoEXT :: capabilityConfigs כשיוצרים את spatialContext .

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

זמן הריצה לא יכול לכלול ישויות מרחביות שלא מופיעות ב-XrSpatialUpdateSnapshotCreateInfoEXT :: entities ב-snapshot .

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

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני הקריאה ל-xrCreateSpatialUpdateSnapshotEXT
• ‫ spatialContext must be a valid XrSpatialContextEXT handle
• ‫ createInfo must be a pointer to a valid XrSpatialUpdateSnapshotCreateInfoEXT structure
• ‫ snapshot must be a pointer to an XrSpatialSnapshotEXT handle

קודי החזרה

הצלחה

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_INSTANCE_LOST
• XR_ERROR_LIMIT_REACHED
• XR_ERROR_OUT_OF_MEMORY
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_SESSION_LOST
• XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
• XR_ERROR_TIME_INVALID
• XR_ERROR_VALIDATION_FAILURE

המבנה XrSpatialUpdateSnapshotCreateInfoEXT מוגדר כך:

typedef struct XrSpatialUpdateSnapshotCreateInfoEXT {
    XrStructureType                     type;
    const void*                         next;
    uint32_t                            entityCount;
    const XrSpatialEntityEXT*           entities;
    uint32_t                            componentTypeCount;
    const XrSpatialComponentTypeEXT*    componentTypes;
    XrSpace                             baseSpace;
    XrTime                              time;
} XrSpatialUpdateSnapshotCreateInfoEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. לא מוגדרים מבנים כאלה ב-OpenXR הבסיסי או בתוסף הזה.
• ‫entityCount הוא uint32_t שמתאר את מספר האלמנטים במערך entities.
• ‫entities הוא מערך של XrSpatialEntityEXT שזמן הריצה חייב לכלול את נתוני הרכיב בתמונת המצב.
• ‫componentTypeCount הוא uint32_t שמתאר את מספר האלמנטים במערך componentTypes.
• ‫componentTypes הוא מערך של XrSpatialComponentTypeEXT שזמן הריצה חייב לכלול את הנתונים שלו בתמונת המצב.
• ‫baseSpace הוא XrSpace שביחס אליו ימוקמו כל המיקומים של העדכון XrSpatialSnapshotEXT.
• ‫time הוא XrTime שבו ימוקמו כל המיקומים של העדכון XrSpatialSnapshotEXT.

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrSpatialUpdateSnapshotCreateInfoEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_UPDATE_SNAPSHOT_CREATE_INFO_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ entities must be a pointer to an array of entityCount valid XrSpatialEntityEXT handles
• ‫ אם componentTypeCount לא 0 , ‏ componentTypes חייב להיות מצביע למערך של componentTypeCount ערכים תקינים של XrSpatialComponentTypeEXT
• baseSpace חייב להיות כינוי תקין ב-XrSpace
• ‫ הפרמטר entityCount חייב להיות גדול מ-0
• גם baseSpace וגם הרכיבים של entities חייבים להיווצר, להיות מוקצים או מאוחזרים מאותו XrSession

השמדת תמונת מצב

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

XrResult xrDestroySpatialSnapshotEXT(
    XrSpatialSnapshotEXT                        snapshot);

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

• ‫snapshot הוא XrSpatialSnapshotEXT שסופק בעבר על ידי xrCreateSpatialDiscoverySnapshotCompleteEXT או xrCreateSpatialUpdateSnapshotEXT .

האפליקציה יכולה להתקשר אל xrDestroySpatialSnapshotEXT כדי להרוס את הטיפול ב-XrSpatialSnapshotEXT ואת המשאבים שמשויכים אליו.

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

• ‫ XR_EXT_spatial_entity התוסף חייב להיות מופעל לפני הקריאה ל-xrDestroySpatialSnapshotEXT
• ‫ snapshot חייב להיות נקודת אחיזה (handle) תקינה של XrSpatialSnapshotEXT

Thread Safety

• הגישה אל snapshot ואל כל הכינויים של הילדים חייבת להיות מסונכרנת חיצונית

קודי החזרה

הצלחה

• XR_SUCCESS

Failure

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_HANDLE_INVALID
• XR_ERROR_RUNTIME_FAILURE

רכיבים נפוצים

דו-ממד מוגדר

נתוני רכיבים

המבנה XrSpatialBounded2DDataEXT מוגדר כך:

typedef struct XrSpatialBounded2DDataEXT {
    XrPosef        center;
    XrExtent2Df    extents;
} XrSpatialBounded2DDataEXT;

תיאורים של חברי הקבוצה

• ‫center הוא XrPosef שמגדיר את המרכז הגיאומטרי של הרכיב הדו-ממדי המוגבל.
• ‫extents הוא גבולות הרכיב הדו-ממדי המוגבל לאורך ציר X (extents.width), ציר Y (extents.height), במרכז center .

הערכים extents ו-XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT מתייחסים לגודל הישות במישור x-y של מערכת הקואורדינטות של המישור. מישור עם מיקום של {0, 0, 0}, סיבוב של {0, 0, 0, 1} (ללא סיבוב) וגודל של {1, 1} מתייחס למישור בגודל מטר על מטר שממורכז בנקודה {0, 0, 0} עם וקטור נורמלי של הפנים הקדמיות שמצביע לכיוון +Z במרחב של הרכיב.

X X Y Y Z Z Height Height Y Y Z Z X X Vertical plane Vertical plane Horizontal Plane Horizontal Plane Width Width Width Width Height Height

איור 24. מערכת קואורדינטות של רכיב Bounded2D

הערה

‫OpenXR משתמש במישור X-Y עם +Z כנורמל של המישור, אבל ממשקי API אחרים עשויים להשתמש במישור X-Z עם +Y כנורמל של המישור. אפשר להמיר את מישור ה-X-Y למישור ה-X-Z על ידי סיבוב של ‎-π/2 רדיאנים סביב ציר ה-X החיובי.

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_entity לפני שמשתמשים ב-XrSpatialBounded2DDataEXT

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

המבנה XrSpatialComponentBounded2DListEXT מוגדר כך:

typedef struct XrSpatialComponentBounded2DListEXT {
    XrStructureType               type;
    void*                         next;
    uint32_t                      boundCount;
    XrSpatialBounded2DDataEXT*    bounds;
} XrSpatialComponentBounded2DListEXT;

תיאורים של חברי הקבוצה

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

סביבת הריצה חייבת להחזיר XR_ERROR_VALIDATION_FAILURE מ-xrQuerySpatialComponentDataEXT אם XrSpatialComponentBounded2DListEXT נמצא בשרשרת הבאה של XrSpatialComponentDataQueryResultEXT :: next אבל XrSpatialComponentDataQueryConditionEXT ::componentTypeCount הוא לא אפס ו-XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT לא נכלל ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

אם xrQuerySpatialComponentDataEXT :: snapshot נוצר מ-xrCreateSpatialDiscoverySnapshotCompleteEXT , סביבת זמן הריצה חייבת לספק את XrSpatialBounded2DDataEXT :: center ב-XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace וב-XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

אם xrQuerySpatialComponentDataEXT :: snapshot נוצר מ-xrCreateSpatialUpdateSnapshotEXT , סביבת זמן הריצה חייבת לספק XrSpatialBounded2DDataEXT :: center ב-XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace וב-XrSpatialUpdateSnapshotCreateInfoEXT :: time .

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני שמשתמשים ב-XrSpatialComponentBounded2DListEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_COMPONENT_BOUNDED_2D_LIST_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ bounds must be a pointer to an array of boundCount XrSpatialBounded2DDataEXT structures
• ‫ הפרמטר boundCount חייב להיות גדול מ-0

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

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

תלת-ממד מוגבל

נתוני רכיבים

‫XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT משתמש ב-XrBoxf לנתונים שלו.

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

המבנה XrSpatialComponentBounded3DListEXT מוגדר כך:

typedef struct XrSpatialComponentBounded3DListEXT {
    XrStructureType    type;
    void*              next;
    uint32_t           boundCount;
    XrBoxf*            bounds;
} XrSpatialComponentBounded3DListEXT;

תיאורים של חברי הקבוצה

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

סביבת הריצה חייבת להחזיר XR_ERROR_VALIDATION_FAILURE מ-xrQuerySpatialComponentDataEXT אם XrSpatialComponentBounded3DListEXT נמצא בשרשרת הבאה של XrSpatialComponentDataQueryResultEXT :: next אבל XrSpatialComponentDataQueryConditionEXT ::componentTypeCount הוא לא אפס ו-XR_SPATIAL_COMPONENT_TYPE_BOUNDED_3D_EXT לא נכלל ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

אם xrQuerySpatialComponentDataEXT :: snapshot נוצר מ-xrCreateSpatialDiscoverySnapshotCompleteEXT , זמן הריצה חייב לספק XrBoxf :: center ב-XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace ב-XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time .

אם נוצר xrQuerySpatialComponentDataEXT :: snapshot מ-xrCreateSpatialUpdateSnapshotEXT , אז זמן הריצה חייב לספק XrBoxf :: center ב-XrSpatialUpdateSnapshotCreateInfoEXT :: baseSpace ב-XrSpatialUpdateSnapshotCreateInfoEXT :: time .

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני השימוש ב-XrSpatialComponentBounded3DListEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_COMPONENT_BOUNDED_3D_LIST_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ bounds חייב להיות מצביע למערך של מבני boundCount XrBoxf
• ‫ הפרמטר boundCount חייב להיות גדול מ-0

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

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

הורה

נתוני רכיבים

‫XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT משתמש ב-XrSpatialEntityIdEXT לנתונים שלו.

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

המבנה XrSpatialComponentParentListEXT מוגדר כך:

typedef struct XrSpatialComponentParentListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 parentCount;
    XrSpatialEntityIdEXT*    parents;
} XrSpatialComponentParentListEXT;

תיאורים של חברי הקבוצה

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

ה-runtime חייב להחזיר XR_ERROR_VALIDATION_FAILURE מ-xrQuerySpatialComponentDataEXT אם XrSpatialComponentParentListEXT נמצא בשרשרת הבאה של XrSpatialComponentDataQueryResultEXT :: next אבל XrSpatialComponentDataQueryConditionEXT ::componentTypeCount הוא לא אפס ו-XR_SPATIAL_COMPONENT_TYPE_PARENT_EXT לא נכלל ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_entity לפני שמשתמשים ב-XrSpatialComponentParentListEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_COMPONENT_PARENT_LIST_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ parents חייב להיות מצביע למערך של parentCount ערכים של XrSpatialEntityIdEXT
• ‫ הפרמטר parentCount חייב להיות גדול מ-0

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

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

רשת תלת-ממדית

נתוני רכיבים

המבנה XrSpatialMeshDataEXT מוגדר כך:

typedef struct XrSpatialMeshDataEXT {
    XrPosef               origin;
    XrSpatialBufferEXT    vertexBuffer;
    XrSpatialBufferEXT    indexBuffer;
} XrSpatialMeshDataEXT;

תיאורים של חברי הקבוצה

• ‫origin הוא XrPosef שמגדיר את המקור של הרשת. כל הקודקודים של הרשת חייבים להיות יחסיים למקור הזה.
• ‫vertexBuffer הוא XrSpatialBufferEXT שמספק את המזהה של מאגר שמייצג את מאגר הקודקודים של הישות שהרכיב הזה נמצא בה. המיקום של קודקודי הצורה חייב להיות ביחס ל-origin .
• ‫indexBuffer הוא XrSpatialBufferEXT שמספק את המזהה של מאגר שמייצג מערך של אינדקסים של משולשים, ומציין את האינדקסים של קודקודי הרשת ב-vertexBuffer . האינדקסים של המשולשים חייבים להיות מוחזרים בסדר נגד כיוון השעון, ושלושה אינדקסים מציינים משולש אחד.

בסוג הרכיב באמצעות XrSpatialMeshDataEXT חובה לציין את XrSpatialBufferTypeEXT של vertexBuffer ושל indexBuffer .

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

• ‫ חובה להפעיל את התוסף XR_EXT_spatial_entity לפני שמשתמשים ב-XrSpatialMeshDataEXT
• ‫ vertexBuffer חייב להיות מבנה XrSpatialBufferEXT תקין
• ‫ indexBuffer חייב להיות מבנה XrSpatialBufferEXT תקין

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

המבנה XrSpatialComponentMesh3DListEXT מוגדר כך:

typedef struct XrSpatialComponentMesh3DListEXT {
    XrStructureType          type;
    void*                    next;
    uint32_t                 meshCount;
    XrSpatialMeshDataEXT*    meshes;
} XrSpatialComponentMesh3DListEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫meshCount הוא uint32_t שמתאר את מספר האלמנטים במערך meshes.
• ‫meshes הוא מערך של XrSpatialMeshDataEXT .

האפליקציה יכולה לשלוף נתונים לגבי רכיב התלת-ממד של רשת הישויות המרחביות ב-XrSpatialSnapshotEXT על ידי הוספת XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes והוספת XrSpatialComponentMesh3DListEXT לשרשרת המצביעים הבאה של XrSpatialComponentDataQueryResultEXT .

סביבת זמן הריצה חייבת להחזיר XR_ERROR_VALIDATION_FAILURE מ-xrQuerySpatialComponentDataEXT אם XrSpatialComponentMesh3DListEXT נמצא בשרשרת הבאה של XrSpatialComponentDataQueryResultEXT :: next אבל XrSpatialComponentDataQueryConditionEXT ::componentTypeCount הוא לא אפס ו-XR_SPATIAL_COMPONENT_TYPE_MESH_3D_EXT לא נכלל ב-XrSpatialComponentDataQueryConditionEXT :: componentTypes .

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

ב-XrSpatialMeshDataEXT שאוכלס על ידי זמן הריצה במערך meshes, הערך של XrSpatialBufferEXT :: bufferType עבור XrSpatialMeshDataEXT :: vertexBuffer חייב להיות XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT, והערך של XrSpatialBufferEXT :: bufferType עבור XrSpatialMeshDataEXT :: indexBuffer חייב להיות XR_SPATIAL_BUFFER_TYPE_UINT32_EXT .

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

• ‫ התוסף XR_EXT_spatial_entity חייב להיות מופעל לפני שמשתמשים ב-XrSpatialComponentMesh3DListEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_COMPONENT_MESH_3D_LIST_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ meshes must be a pointer to an array of meshCount XrSpatialMeshDataEXT structures
• ‫ הפרמטר meshCount חייב להיות גדול מ-0

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

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

הכללת הרכיב הזה בשרשרת הבאה של XrSpatialCapabilityConfigurationBaseHeaderEXT לא דורשת הגדרה מיוחדת .

מסננים של סטטוס המעקב

המבנה XrSpatialFilterTrackingStateEXT מוגדר כך:

typedef struct XrSpatialFilterTrackingStateEXT {
    XrStructureType                    type;
    const void*                        next;
    XrSpatialEntityTrackingStateEXT    trackingState;
} XrSpatialFilterTrackingStateEXT;

תיאורים של חברי הקבוצה

• ‫type הוא XrStructureType של המבנה הזה.
• ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים.
• ‫trackingState הוא XrSpatialEntityTrackingStateEXT שהאפליקציה רוצה להחיל עליו את המסנן.

האפליקציה יכולה להשתמש ב-XrSpatialFilterTrackingStateEXT בשרשרת הבאה של XrSpatialDiscoverySnapshotCreateInfoEXT כדי להגביל את היקף הגילוי רק לישויות שמצב המעקב שלהן הוא trackingState .

האפליקציה יכולה להשתמש ב-XrSpatialFilterTrackingStateEXT בשרשרת הבאה של XrSpatialComponentDataQueryConditionEXT כדי להגביל את היקף השאילתה של נתוני הרכיב מתמונה סטטית רק לישויות שמצב המעקב שלהן הוא trackingState .

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

• ‫ צריך להפעיל את התוסף XR_EXT_spatial_entity לפני שמשתמשים ב-XrSpatialFilterTrackingStateEXT
• ‫ type חייב להיות XR_TYPE_SPATIAL_FILTER_TRACKING_STATE_EXT
• ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
• ‫ trackingState חייב להיות ערך תקין של XrSpatialEntityTrackingStateEXT

קוד לדוגמה

שימוש באפליקציה

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

• אפליקציה קודם מפרטת את היכולות המרחביות של המערכת באמצעות xrEnumerateSpatialCapabilitiesEXT . לאחר מכן, הפונקציה בודקת את המערך המוחזר של XrSpatialCapabilityEXT ומפרטת את הרכיבים והתכונות שנתמכים לכל אחת מהיכולות האלה באמצעות xrEnumerateSpatialCapabilityComponentTypesEXT ו-xrEnumerateSpatialCapabilityFeaturesEXT בהתאמה. כך האפליקציה מקבלת תמונה מלאה של הרכיבים שהיא יכולה להפעיל ושל ההגדרות שהיכולת מקבלת.
• לאחר מכן האפליקציה יוצרת נקודות אחיזה מסוג XrSpatialContextEXT עם הגדרות ספציפיות של יכולות מרחביות. ההגדרות האלה מאפשרות להפעיל ולהגדיר יכולת ספציפית בהקשר המרחבי, וגם להפעיל ולהגדיר רכיבים של היכולות האלה.
• לכל XrSpatialContextEXT , האפליקציה מחכה לקבל אירועים מסוג XrEventDataSpatialDiscoveryRecommendedEXT עבור אותו XrSpatialContextEXT לפני השימוש ב-xrCreateSpatialDiscoverySnapshotAsyncEXT כדי לגלות ישויות מרחביות. אחרי שהפעולה האסינכרונית הזו תושלם, האפליקציה תקבל נקודת אחיזה של XrSpatialSnapshotEXT.
• האפליקציה שולחת שאילתות לגבי הישויות ונתוני הרכיבים שכלולים ב-XrSpatialSnapshotEXT באמצעות xrQuerySpatialComponentDataEXT . האפליקציה קוראת את נתוני הרכיבים העדכניים של הישויות שנכללות בשאילתה ממבנים שמצורפים לשרשרת הבאה של XrSpatialComponentDataQueryResultEXT אם מצב הישות הוא XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT .
• אם יש ישויות ספציפיות שהאפליקציה מזהה כמעניינות ורוצה לקבל עדכונים לגביהן לאורך זמן, היא יוצרת נקודות אחיזה של XrSpatialEntityEXT עבור הישויות האלה באמצעות xrCreateSpatialEntityFromIdEXT . האפליקציה מקבלת עדכונים לגבי ישויות מעניינות כאלה באמצעות xrCreateSpatialUpdateSnapshotEXT ומשתמשת באותה פונקציה xrQuerySpatialComponentDataEXT ב-XrSpatialSnapshotEXT שנוצר לאחרונה כדי לקבל את נתוני הרכיבים העדכניים של הישויות האלה.

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

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

/****************************/
/* Capability definition    */
/****************************/
// Foo capability has the following components -
// - XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT
#define XR_SPATIAL_CAPABILITY_FOO ((XrSpatialCapabilityEXT)1000740000U)

#define XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT ((XrStructureType)1000740000U)
// Derives from XrSpatialCapabilityConfigurationBaseHeaderEXT
typedef struct XrSpatialCapabilityConfigurationFooEXT {
  XrStructureType                     type;
  const void* XR_MAY_ALIAS            next;
  XrSpatialCapabilityEXT              capability;
  uint32_t                            enabledComponentCount;
  const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationFooEXT;

/******************************/
/* End capability definition  */
/******************************/

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);
};

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  };

  // Configure Foo capability for the spatial context
  XrSpatialCapabilityConfigurationFooEXT fooConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_FOO_EXT};
  fooConfig.capability = XR_SPATIAL_CAPABILITY_FOO;
  fooConfig.enabledComponentCount = enabledComponents.size();
  fooConfig.enabledComponents = enabledComponents.data();

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

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();
  XrFutureEXT createContextFuture;
  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) {
    return;
  }

  spatialContext = completion.spatialContext;
}

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

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

  waitUntilReady(future);

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

  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 componentToQuery = XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT;
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypes = &componentToQuery;

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    queryResult.entityIdCapacityInput = 0;
    queryResult.entityIds = nullptr;
    queryResult.entityStateCapacityInput = 0;
    queryResult.entityStates = nullptr;
    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;

    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) {
        // 2D extents for entity entityIds[i] is bounded2d[i].extents.
      }
    }

    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));

שאילתות לגבי נתונים במאגר

בדוגמת הקוד הבאה אפשר לראות איך מקבלים את הנתונים של רכיב שמספק XrSpatialBufferEXT .

/****************************/
/* Component definition     */
/****************************/
// Foo component that provides an XrVector3f buffer
#define XR_SPATIAL_COMPONENT_TYPE_FOO_EXT ((XrSpatialComponentTypeEXT)1000740000U)

#define XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT ((XrStructureType)1000740000U)

// XrSpatialComponentFooListEXT extends XrSpatialComponentDataQueryResultEXT
typedef struct XrSpatialComponentFooListEXT {
    XrStructureType                   type;
    void* XR_MAY_ALIAS                next;
    uint32_t                          fooCount;
    XrSpatialBufferEXT*               foo;
} XrSpatialComponentFooListEXT;

/******************************/
/* End Component definition  */
/******************************/

// Query for the foo component data
XrSpatialComponentTypeEXT componentToQuery = XR_SPATIAL_COMPONENT_TYPE_FOO_EXT;
XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
queryCond.componentTypeCount = 1;
queryCond.componentTypes = &componentToQuery;

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

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

std::vector<XrSpatialBufferEXT> fooBuffers(queryResult.entityIdCountOutput);
XrSpatialComponentFooListEXT fooList{XR_TYPE_SPATIAL_COMPONENT_FOO_LIST_EXT};
fooList.fooCount = fooBuffers.size();
fooList.foo = fooBuffers.data();
queryResult.next = &fooList;

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

for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
  // foo component data for entity entityIds[i]
  if (fooBuffers[i].bufferType == XR_SPATIAL_BUFFER_TYPE_VECTOR3F_EXT) {
    XrSpatialBufferGetInfoEXT getInfo{XR_TYPE_SPATIAL_BUFFER_GET_INFO_EXT};
    getInfo.bufferId = fooBuffers[i].bufferId;
    uint32_t bufferCountOutput;
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, 0, &bufferCountOutput, nullptr));
    std::vector<XrVector3f> vertexBuffer(bufferCountOutput);
    CHK_XR(xrGetSpatialBufferVector3fEXT(snapshot, &getInfo, bufferCountOutput, &bufferCountOutput, vertexBuffer.data()));

    // XrVertex3f buffer for entity entityIds[i] is now available in vertexBuffer vector.
  }
}

הנחיות לגבי תוספים

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

  • בנוסף, התוסף חייב להגדיר מבנה רשימה לרכיב הזה, שיאפשר לאפליקציה להעביר מערך לסביבת זמן הריצה כדי למלא אותו בנתונים של כל הישויות המרחביות שעומדות בדרישות של xrQuerySpatialComponentDataEXT :: queryCondition . דוגמאות למבני רשימות כאלה הן XrSpatialComponentParentListEXT ו-XrSpatialComponentBounded2DListEXT . אם גודל נתוני הרכיב משתנה ונדרש שימוש בשני קריאות כדי לשלוח שאילתה לגביו, נתוני הרכיב צריכים לספק XrSpatialBufferEXT לכל נתון בגודל משתנה במבנה הרשימה, וחובה לציין את XrSpatialBufferTypeEXT לכל מאגר. האפליקציה יכולה להריץ שאילתה על נתוני המאגר באמצעות פונקציות שמוגדרות בשני סוגי קריאות לנתוני רכיבים . דוגמה למבנה כזה היא XrSpatialMeshDataEXT שנכלל ב-XrSpatialComponentMesh3DListEXT .
  • התוסף יכול גם לספק מבנים שהאפליקציה יכולה לשרשר אל XrSpatialComponentDataQueryConditionEXT :: next כדי לספק מסננים נוספים לשאילתה שקשורים לנתונים של הרכיב הזה.

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

• אם תוסף מגדיר XrSpatialCapabilityEXT חדש ,

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

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

• תוסף שמגדיר XrSpatialCapabilityEXT חדש צריך לפעול לפי התבנית הזו של המפרט –

  • סקירה כללית
  • תמיכה בזמן ריצה
  • הגדרות אישיות
  • רכיבים מובטחים
  • קוד לדוגמה

• תוסף שמגדיר XrSpatialComponentTypeEXT חדש צריך לפעול לפי התבנית הזו של המפרט –

  • נתוני רכיבים
  • מבנה רשימת הרכיבים לשליחת שאילתות לנתונים
  • הגדרות אישיות

• כשכותבים API שמספק לאפליקציה XrSpatialBufferIdEXT , חובה לצרף אליו XrSpatialBufferTypeEXT כדי ליידע את האפליקציה מהו סוג הנתונים של המאגר. האפליקציה יכולה להשתמש בפונקציה מתאימה xrGetSpatialBuffer* כדי לאחזר את התוכן בפועל של המאגר.

הנחיות לעיצוב תוויות סמנטיות ולשימוש בתוספים

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

• אם תוסף מגדיר תוויות סמנטיות ל-XrSpatialCapabilityEXT , הוא צריך לעשות זאת על ידי הגדרה של XrSpatialComponentTypeEXT חדש וגם של ספירה חדשה עם קבוצה של תוויות ('קבוצת תוויות סמנטיות') שתשמש כנתונים של הרכיב הזה.
• לספירה שמייצגת קבוצה של תוויות סמנטיות חייב להיות ערך כדי לציין שהישות לא מסווגת באף אחת מהתוויות של הקבוצה הזו. השם של הערך המנומרי הזה חייב לכלול את הערך 'UNCATEGORIZED', לדוגמה: XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT . הערך הזה מציין לאפליקציות שסביבת זמן הריצה מזהה את הישות הזו, אבל יש עוד קבוצות של תוויות סמנטיות שבהן הישות הזו מסווגת.
• הספירה של XrSpatialComponentTypeEXT שהוגדר לאחרונה ב-xrEnumerateSpatialCapabilityComponentTypesEXT מרמזת שסביבת זמן הריצה תומכת בקבוצת התוויות הסמנטיות (ולכן בתוויות שמוגדרות בקבוצה) שמתאימה לסוג הרכיב הזה.
• אפליקציות שמבקשות לגלות ישויות עם תוויות ששייכות לקבוצת התוויות הסמנטיות הזו, כוללות את XrSpatialComponentTypeEXT המתאים במערך XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents של מבנה ההגדרה של היכולת שסוג הרכיב מפורט בה.
• יכול להיות שישות מרחבית אחת תכלול כמה רכיבים, וכל אחד מהם יספק לה תווית מתוך קבוצת התוויות הסמנטיות שלו. דוגמה: קבוצות של תוויות סמנטיות היפותטיות – XrSpatialObjectSemanticLabel, שיכולות לכלול ערכים כמו כיסא, ספה, שולחן וכו'. ‫XrSpatialSofaBrand, שיכולים להיות בו ערכים כמו IKEA,‏ Wayfair וכו', ו-XrSpatialIkeaSofa, שיכולים להיות בו שמות דגמים ספציפיים של ספות מאיקאה. בתרחיש הזה, לאותה ישות של ספה יש את כל 3 הרכיבים (תוויות מכל 3 קבוצות התוויות הסמנטיות), וכל אחד מהם מספק רמת פירוט שונה של מידע על הישות.
• אם תוסף מגדיר XrSpatialComponentTypeEXT חדש שמספק קבוצה חדשה של תוויות סמנטיות שמכילה כמה תוויות בנוסף לתווית UNCATEGORIZED, התוסף צריך להגדיר XrSpatialCapabilityFeatureEXT שמאפשר לאפליקציות להפעיל רק קבוצת משנה של התוויות שמוגדרות בקבוצת התוויות הסמנטיות שמתאימה לסוג הרכיב הזה. קבוצת המשנה הזו, שמסופקת בשרשרת הבאה של הגדרת היכולת, משמשת כרמז לסביבות זמן ריצה כדי לבצע אופטימיזציה של צינורות המעקב שלהן ולעקוב רק אחרי קבוצת המשנה שסופקה. דוגמה למבנה כזה של תכונה מופיעה בהמשך .
• אסור לתוספים להוסיף תוויות לספירה קיימת של קבוצת תוויות סמנטיות. במקום זאת, חובה להגדיר ספירה חדשה שמכילה ערכים מקבילים עם סמנטיקה זהה ועם ערכים ששווים לאלה מהקבוצה השנייה, בנוסף לערכים החדשים שנוספו. במפרט של קבוצת התוויות הסמנטיות החדשה חובה גם להגדיר את המיפוי בין קבוצת התוויות הישנה לבין קבוצת התוויות החדשה. דוגמה מופיעה בהמשך .

דוגמה להגדרה של תכונה מרחבית עבור קבוצת משנה של תוויות סמנטיות

// New example semantic label set.
typedef enum XrSpatialExampleSemanticLabelEXT {
  // ... label values
} XrSpatialExampleSemanticLabelEXT;

/*
typedef enum XrSpatialCapabilityFeatureEXT {
  // .. existing values

  // new spatial feature value
  XR_SPATIAL_CAPABILITY_FEATURE_EXAMPLE_SEMANTIC_LABEL_SUBSET_EXT

  // .. existing values
} XrSpatialCapabilityFeatureEXT;
*/

// New spatial feaure configuration structure
typedef struct XrSpatialFeatureExampleSemanticLabelSubsetEXT {
    XrStructureType                             type;
    const void* XR_MAY_ALIAS                    next;
    uint32_t                                    semanticLabelCount;
    const XrSpatialExampleSemanticLabelEXT*     semanticLabels;
} XrSpatialFeatureExampleSemanticLabelSubsetEXT;

דוגמה לתוסף של תוויות סמנטיות מרחביות

typedef enum XrSpatialExamplePlaneSemanticLabelExtensionEXT {
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_UNCATEGORIZED_EXT = 1,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT = 2,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT = 3,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT = 4,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT = 5,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT = 6,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT = 7,
    XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialExamplePlaneSemanticLabelExtensionEXT;

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

For all non-UNCATEGORIZED label enumerants in elink:XrSpatialPlaneSemanticLabelEXT,
the runtime must: return that enumerant if and only if it returns the corresponding
label enumerant from elink:XrSpatialExamplePlaneSemanticLabelExtensionEXT with the same value
i.e.
the ename:XR_SPATIAL_COMPONENT_TYPE_PLANE_SEMANTIC_LABEL_EXT value for that entity must:
correspond with the ename:XR_SPATIAL_COMPONENT_TYPE_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_EXT values
according to the following table -

[width="100%",options="header"]
|====
| XrSpatialExamplePlaneSemanticLabelExtensionEXT                | XrSpatialPlaneSemanticLabelEXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_FLOOR_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_FLOOR_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WALL_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_WALL_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_CEILING_EXT | XR_SPATIAL_PLANE_SEMANTIC_LABEL_CEILING_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_TABLE_EXT   | XR_SPATIAL_PLANE_SEMANTIC_LABEL_TABLE_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_DOOR_EXT    | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
| XR_SPATIAL_EXAMPLE_PLANE_SEMANTIC_LABEL_EXTENSION_WINDOW_EXT  | XR_SPATIAL_PLANE_SEMANTIC_LABEL_UNCATEGORIZED_EXT
|====