XR_ANDROID_scene_meshing

מחרוזת שם

XR_ANDROID_scene_meshing

סוג התוסף

הרחבת המכונה

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

719

Revision

3

סטטוס האישור

לא אושר

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

OpenXR 1.0

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

2025-05-15

סטטוס כתובת ה-IP

לא ידוע על תלונות בנושא זכויות יוצרים שקשורות לכתובות IP.

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

ספנסר קווין, Google
ג'ארד פינדר, Google
אנטוניו פונטן, Google
קיירן אוברטרף, Google
ניחב ג'יין, Google
סלאר חאן, Google
סבסטיאן קלוז, Google
יורגן שטורם, Google
ויני דה סילבה, Google
ריקרדו קמפבל, Google

סקירה כללית

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

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

נתוני רשת הסצנה נוצרים בזמן הריצה ומשותפים עם האפליקציה באמצעות XrSceneMeshingTrackerANDROID ו-XrSceneMeshSnapshotANDROID . אפליקציות יכולות לגשת לערכים במידע על רשת המשנה של הסצנה באמצעות XrSceneSubmeshStateANDROID שמוחזר מ-xrGetAllSubmeshStatesANDROID . אפליקציות יכולות לגשת לערכים בנתוני רשת המשנה של הסצנה באמצעות XrSceneSubmeshDataANDROID שמוחזר מ-xrGetSubmeshDataANDROID .

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

הרשאות

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

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

(רמת ההגנה: מסוכן)

בדיקת יכולת המערכת

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

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

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

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

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

אם סביבת זמן ריצה מחזירה XR_FALSE עבור supportsSceneMeshing , המערכת לא תומכת במיפוי סצנות, ולכן חייבת להחזיר XR_ERROR_FEATURE_UNSUPPORTED מ- xrCreateSceneMeshingTrackerANDROID . מומלץ להימנע משימוש בפונקציית מיזוג הסצנות באפליקציה כשערך המאפיין supportsSceneMeshing הוא XR_FALSE .

אם סביבת זמן ריצה מחזירה XR_TRUE עבור supportsSceneMeshing , המערכת תומכת במיזוג סצנות.

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

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

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

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

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

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

קבוצת התוויות הסמנטיות הזו מייצגת היעדר תוויות סמנטיות.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

התווית הסמנטית הזו מייצגת את XrSceneMeshSemanticLabelANDROID.

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

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

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

  • ‫instance הוא XrInstance שנוצר על ידי האפליקציה.
  • ‫systemId is an XrSystemId retried from xrGetSystem .
  • ‫supportedSemanticLabelSetsInputCapacity היא הקיבולת של supportedSemanticLabelSets , או 0 כדי לאחזר את הקיבולת הנדרשת.
  • ‫supportedSemanticLabelSetsOutputCount הוא מצביע למספר supportedSemanticLabelSets שנכתב, או מצביע לקיבולת הנדרשת במקרה ש-supportedSemanticLabelSetsInputCapacity לא מספיק.
  • ‫supportedSemanticLabelSets הוא מצביע למערך של XrSceneMeshSemanticLabelSetANDROID . הערך יכול להיות NULL אם supportedSemanticLabelSetsInputCapacity הוא 0.
  • בפרק Buffer Size Parameters מופיע תיאור מפורט של אחזור הגודל הנדרש של supportedSemanticLabelSets.

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

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

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

  • ‫ התוסף XR_ANDROID_scene_meshing חייב להיות מופעל לפני הקריאה ל-xrEnumerateSupportedSemanticLabelSetsANDROID
  • ‫ instance חייב להיות ידית XrInstance תקינה
  • ‫ supportedSemanticLabelSetsOutputCount חייב להיות מצביע לערך uint32_t
  • אם supportedSemanticLabelSetsInputCapacity לא שווה ל-0 , ‏ supportedSemanticLabelSets חייב להיות מצביע למערך של supportedSemanticLabelSetsInputCapacity ערכים מסוג XrSceneMeshSemanticLabelSetANDROID

קודי החזרה

הצלחה

  • 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

צור כינוי למעקב אחרי מיזוג סצנות

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

ה-handle‏ XrSceneMeshingTrackerANDROID מייצג כלי למעקב אחר מיפוי סצנות לצורך מיפוי סצנות וניהול המשאבים שקשורים לכך.

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

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

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

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

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

אם המערכת לא תומכת במיזוג סצנות, סביבת זמן הריצה חייבת להחזיר XR_ERROR_FEATURE_UNSUPPORTED מ-xrCreateSceneMeshingTrackerANDROID . במקרה כזה, סביבת זמן הריצה חייבת להחזיר XR_FALSE עבור XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing כשקוראים לפונקציה xrGetSystemProperties, כדי שהאפליקציה תוכל להימנע מיצירת כלי למעקב אחר מיפוי סצנות.

האפליקציה חייבת להשתמש רק בקבוצות של תוויות סמנטיות שנתמכות על ידי המערכת ב-XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet כשיוצרים כלי למעקב אחר מיפוי סצנות. אם האפליקציה משתמשת בקבוצת תוויות סמנטיות של קודקודים ברשת תלת-ממדית של סצנה שלא נתמכת, סביבת הריצה חייבת להחזיר XR_ERROR_FEATURE_UNSUPPORTED מ-xrCreateSceneMeshingTrackerANDROID .

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

ה-handle‏ xrCreateSceneMeshingTrackerANDROID הוא הבעלים של כל המשאבים של מיפוי הרשת של הסצנה. בסיום השימוש בחוויית מיפוי הסצנה, האפליקציה חייבת להרוס את ה-handle באמצעות הפונקציה xrDestroySceneMeshingTrackerANDROID.

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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_VALIDATION_FAILURE

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

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

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

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. לא מוגדרים מבנים כאלה ב-OpenXR הבסיסי או בתוסף הזה.
  • ‫semanticLabelSet הוא XrSceneMeshSemanticLabelSetANDROID שמשמש לציון קבוצת התוויות הסמנטיות שתשמש למיפוי הרשת של הסצנה. אם הערך הוא XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID , סביבת זמן הריצה תתעלם משדה המאגר vertexSemantics של XrSceneSubmeshDataANDROID ::.
  • ‫enableNormals הוא XrBool32 שמשמש כדי לציין אם לכלול את הנורמלים של הקודקודים של הרשת במאגר הרשת של הסצנה כשמקבלים את נתוני הרשת של הסצנה.

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

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

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

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

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

הפונקציה xrDestroySceneMeshingTrackerANDROID משחררת את tracker ואת המשאבים הבסיסיים כשהשימוש בחוויות של מיפוי סצנות מסתיים.

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

Thread Safety

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

קודי החזרה

הצלחה

  • XR_SUCCESS

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

יצירת כינוי של קובץ snapshot של רשת סצנה

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

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

אפשר להשתמש בנקודת האחיזה הזו כדי לאחזר נתוני רשת משנה באמצעות xrGetAllSubmeshStatesANDROID ו-xrGetSubmeshDataANDROID .

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

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

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

האפליקציה יכולה להשתמש בפונקציה xrCreateSceneMeshSnapshotANDROID כדי ליצור תמונה של רשת הסצנה מהכלי למעקב אחר רשת הסצנה. הפונקציה הזו מחזירה נקודת אחיזה של XrSceneMeshSnapshotANDROID יחד עם XrSceneMeshTrackingStateANDROID שעטופה במבנה XrSceneMeshSnapshotCreationResultANDROID. ההנדל הוא למעשה תמונת מצב של נתוני רשת הסצנה בזמן היצירה. אפשר להשתמש ב-handle הזה כדי לבצע שאילתות לגבי המידע והנתונים של רשת הסצנה באמצעות הפונקציות xrGetAllSubmeshStatesANDROID ו-xrGetSubmeshDataANDROID בהתאמה.

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

קודי החזרה

הצלחה

  • 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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID

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

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

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

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. לא מוגדרים מבנים כאלה ב-OpenXR הבסיסי או בתוסף הזה.
  • ‫baseSpace הוא XrSpace שבו מיוצגים פרטי התנוחה של רשת המשנה של הסצנה.
  • ‫time הוא XrTime שמתאר את הזמן שבו רשת הסצנה תעובד או תוצג, בדרך כלל XrFrameState :: predictedDisplayTime .
  • ‫boundingBox הוא XrBoxf שמתאר את התיבה התוחמת שבה יתבצע איסוף של רשת הסצנה.

המבנה XrSceneMeshSnapshotCreateInfoANDROID מתאר את המידע ליצירת נקודת אחיזה XrSceneMeshSnapshotANDROID

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

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

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

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

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

המבנה XrSceneMeshSnapshotCreationResultANDROID מאחסן את התוצאה של יצירת קובץ snapshot של רשת סצנה שמוחזרת מ-xrCreateSceneMeshSnapshotANDROID .

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

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

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

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

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

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

הגשש עדיין לא מוכן לספק נתונים של רשת Mesh.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

המעקב פעיל.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

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

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

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

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

איך מקבלים נתוני רשת תלת-ממדית מתמונה של רשת תלת-ממדית

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

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

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

  • ‫snapshot הוא טיפול ב-XrSceneMeshSnapshotANDROID שנוצר בעבר באמצעות xrCreateSceneMeshSnapshotANDROID .
  • ‫submeshStateCapacityInput היא הקיבולת של submeshStates , או 0 כדי לאחזר את הקיבולת הנדרשת.
  • ‫submeshStateCountOutput הוא מצביע למספר submeshStates שנכתב, או מצביע לקיבולת הנדרשת במקרה ש-submeshStateCapacityInput לא מספיק.
  • ‫submeshStates הוא מצביע למערך של מבני XrSceneSubmeshStateANDROID שהסביבה בזמן הריצה תוציא אליהם את המצב של כל רשתות המשנה ברשת הסצנה. הערך יכול להיות NULL אם submeshStateCapacityInput הוא 0.
  • בפרק Buffer Size Parameters מופיע תיאור מפורט של אחזור הגודל הנדרש של submeshStates.

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

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

  • ‫ צריך להפעיל את התוסף XR_ANDROID_scene_meshing לפני שקוראים לפונקציה xrGetAllSubmeshStatesANDROID
  • ‫ snapshot חייב להיות נקודת אחיזה תקינה של XrSceneMeshSnapshotANDROID
  • ‫ submeshStateCountOutput חייב להיות מצביע לערך uint32_t
  • ‫ אם submeshStateCapacityInput לא שווה ל-0 , ‏ submeshStates חייב להיות מצביע למערך של submeshStateCapacityInput מבני XrSceneSubmeshStateANDROID

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

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

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

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

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

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. לא מוגדרים מבנים כאלה ב-OpenXR הבסיסי או בתוסף הזה.
  • ‫submeshId הוא XrUuid שמזהה את רשת המשנה.
  • ‫lastUpdatedTime הוא XrTime שמייצג את הזמן שבו רשת המשנה עודכנה לאחרונה.
  • ‫submeshPoseInBaseSpace הוא XrPosef שמייצג את התנוחה של רשת המשנה במרחב הבסיסי שמשמש ליצירת ה-snapshot של רשת הסצנה. הפוזה היא גם המרכז של התיבה התוחמת של רשת המשנה.
  • ‫bounds הוא XrExtent3Df שמתאר את הממדים של התיבה התוחמת שמקיפה את רשת המשנה. הגבולות האלה מוגדרים במרחב הבסיסי ששימש ליצירת נקודת האחיזה של רשת הסצנה.

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

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

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

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

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

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

הערך של XrSceneSubmeshDataANDROID :: submeshId חייב להיות ייחודי לכל רכיב ב-inoutSubmeshData, ואפשר לאחזר אותו באמצעות xrGetAllSubmeshStatesANDROID עבור אותו snapshot . אם מזהה רשת המשנה לא תקין או אם יותר מרכיב אחד ב-inoutSubmeshData כולל את אותו מזהה רשת משנה, זמן הריצה חייב להחזיר XR_ERROR_VALIDATION_FAILURE .

הערך submeshDataCount חייב להיות שווה לערך שמוחזר על ידי xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput או קטן ממנו , אחרת זמן הריצה חייב להחזיר XR_ERROR_VALIDATION_FAILURE .

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

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

  • ‫ חובה להפעיל את התוסף XR_ANDROID_scene_meshing לפני שמפעילים את xrGetSubmeshDataANDROID
  • ‫ snapshot חייב להיות נקודת אחיזה תקינה של XrSceneMeshSnapshotANDROID
  • ‫ inoutSubmeshData must be a pointer to an array of submeshDataCount XrSceneSubmeshDataANDROID structures
  • ‫ הפרמטר submeshDataCount חייב להיות גדול מ-0

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Failure

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

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

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

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

  • ‫type הוא XrStructureType של המבנה הזה.
  • ‫next הוא NULL או מצביע למבנה הבא בשרשרת מבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בתוסף הזה.
  • ‫submeshId הוא XrUuid שמזהה את רשת המשנה.
  • ‫vertexCapacityInput היא הקיבולת של vertexPositions , ‏ vertexNormals ו-vertexSemantics , או 0 כדי לאחזר את הקיבולת הנדרשת.
  • ‫vertexCountOutput הוא מצביע למספר הערכים של vertexPositions, vertexNormals ו-vertexSemantics שנכתבו, או מצביע לקיבולת הנדרשת במקרה ש-vertexCapacityInput לא מספיק.
  • ‫vertexPositions הוא מערך של XrVector3f שאליו זמן הריצה יוציא את מיקומי הקודקודים של רשת המשנה.
  • ‫vertexNormals הוא מערך של XrVector3f שאליו זמן הריצה יוציא את הנורמלים של הקודקודים של רשת המשנה. אפשר להשאיר את השדה הזה ריק NULL אם האפליקציה יצרה כלי למעקב עם השבתה של הגדרות רגילות.
  • ‫vertexSemantics הוא מערך של uint8_t שאליו זמן הריצה יוציא את הסמנטיקה של קודקודים של רשת המשנה. אפשר להשאיר את השדה הזה ריק NULL אם האפליקציה יצרה כלי מעקב עם קבוצת תוויות סמנטיות XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID.
  • ‫indexCapacityInput היא הקיבולת של indices , או 0 כדי לאחזר את הקיבולת הנדרשת.
  • ‫indexCountOutput הוא מצביע למספר indices שנכתב, או מצביע לקיבולת הנדרשת במקרה ש-vertexCapacityInput לא מספיק.
  • ‫indices הוא מערך של uint32_t שאליו זמן הריצה יוציא את האינדקסים של רשת המשנה.
  • בפרק פרמטרים של גודל המאגר מופיע תיאור מפורט של אחזור הגודל הנדרש של vertexPositions , vertexNormals , vertexSemantics ו-indices.

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

  • ‫ התוסף XR_ANDROID_scene_meshing חייב להיות מופעל לפני שמשתמשים ב-XrSceneSubmeshDataANDROID
  • ‫ type חייב להיות XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
  • ‫ next חייב להיות NULL או מצביע תקין אל המבנה הבא בשרשרת המבנים
  • ‫ אם vertexCapacityInput לא שווה ל-0 , ‏ vertexPositions חייב להיות מצביע למערך של vertexCapacityInput מבני XrVector3f
  • ‫ אם vertexCapacityInput לא שווה ל-0 , ‏ vertexNormals חייב להיות מצביע למערך של vertexCapacityInput מבני XrVector3f
  • ‫ אם vertexCapacityInput לא שווה ל-0 , vertexSemantics חייב להיות מצביע למערך של vertexCapacityInput ערכי uint8_t
  • ‫ אם indexCapacityInput לא שווה ל-0 , indices חייב להיות מצביע למערך של indexCapacityInput ערכי uint32_t

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

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

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

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

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

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

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

התווית הסמנטית הזו מציינת שאלמנט הרשת התואם מייצג רצפה.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

התווית הסמנטית הזו מציינת שאלמנט הרשת התואם מייצג תקרה.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

התווית הסמנטית הזו מציינת שרכיב הרשת התואם מייצג קיר.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

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

מחיקת תמונת מצב של רשת סצנה

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

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

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

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

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

Thread Safety

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

קודי החזרה

הצלחה

  • XR_SUCCESS

Failure

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

קוד לדוגמה ליצירת רשת של סצנה

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

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup
XrSpace appPlaySpace; // Created at app startup

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

  // ...
  // Finish frame loop
  // ...
}

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

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

פקודות חדשות

מבנים חדשים

New Enums

New Enum Constants

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • הרחבה של XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • הרחבה של XrStructureType :

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

בעיות

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

  • גרסה 3, ‏ 15 במאי 2025 (סלאר חאן)

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