XR_ANDROID_scene_meshing

מחרוזת שם

XR_ANDROID_scene_meshing

סוג התוסף

תוסף למכונה

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

719

גרסה

3

סטטוס האישור

לא אושר

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

OpenXR 1.0

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

2025-05-15

סטטוס 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 , המערכת תומכת ב-scene meshing.

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

הספירה 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_DEFAULT2_ANDROID = 1000801000,
    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.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

קבוצת התוויות הסמנטיות הזו מייצגת את XrSceneMeshSemanticLabel2ANDROID. (נוסף על ידי התוסף XR_ANDROID_scene_meshing_semantic_label2)

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

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

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

  • ‫instance הוא XrInstance שנוצר על ידי האפליקציה.
  • ‫systemId הוא XrSystemId שניסה שוב מ-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 הזה מייצג מצב שבו לא הוגדרה תווית סמנטית, ואפשר להשתמש בו אם האפליקציה לא צריכה סמנטיקה של קודקודים.

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS

נכשל

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

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

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

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

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

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

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

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

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

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

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

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

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • 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 , זמן הריצה יתעלם מהשדה של מאגר הנתונים הזמני XrSceneSubmeshDataANDROID :: vertexSemantics.
  • ‫enableNormals הוא XrBool32 שמשמש כדי לציין אם לכלול וקטורים נורמליים של קודקודים עבור קודקודי הרשת במאגר הזמני של רשת הסצנה כשמקבלים את נתוני רשת הסצנה.

המבנה XrSceneMeshingTrackerCreateInfoANDROID מתאר את המידע ליצירת נקודת אחיזה (handle) מסוג XrSceneMeshingTrackerANDROID.

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

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

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

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

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

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

Thread Safety

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

קודי החזרה

הצלחה

  • XR_SUCCESS

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

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

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

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

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

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

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

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

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

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

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_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 מתאר את המידע ליצירת נקודת אחיזה (handle) של XrSceneMeshSnapshotANDROID

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

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

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

תיאורי חברים

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

המבנה XrSceneMeshSnapshotCreationResultANDROID מאחסן את התוצאה של יצירת תמונת מצב של רשת סצנה שהוחזרה מ-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

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

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

נכשל

  • 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 שמייצג את התנוחה של רשת המשנה במרחב הבסיס ששימש ליצירת תמונת המצב של רשת הסצנה. התנוחה היא גם מרכז התיבה התוחמת (bounding box) של רשת המשנה.
  • ‫bounds הוא XrExtent3Df שמתאר את המימדים של התיבה התוחמת (bounding box) שמקיפה את רשת המשנה. הגבולות האלה מוגדרים במרחב הבסיס ששימש ליצירת נקודת האחיזה של רשת הסצנה.

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

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

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

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

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

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

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

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

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

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

  • ‫ חובה להפעיל את התוסף XR_ANDROID_scene_meshing לפני שקוראים לפונקציה xrGetSubmeshDataANDROID
  • snapshot חייב להיות כינוי תקין של XrSceneMeshSnapshotANDROID
  • ‫ inoutSubmeshData חייב להיות מצביע למערך של מבני submeshDataCount XrSceneSubmeshDataANDROID
  • ‫ הפרמטר submeshDataCount חייב להיות גדול מ-0

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

נכשל

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_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 חייב להיות מצביע למערך של ערכי uint8_t מסוג vertexCapacityInput
  • אם indexCapacityInput הוא לא 0, אז indices חייב להיות מצביע למערך של ערכי uint32_t מסוג indexCapacityInput

הספירה XrSceneMeshSemanticLabelANDROID היא קבוצת ברירת המחדל של תוויות סמנטיות שאפשר להשתמש בהן כדי לתייג קודקודים של רשת, כדי לתאר באיזה משטח של סביבה פיזית נמצא קודקוד הרשת. קבוצת הטיפוסים המוגדרים מראש מיוצגת על ידי הערך 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

נכשל

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

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

פקודות חדשות

מבנים חדשים

ערכי Enums חדשים

קבועי Enum חדשים

  • 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 (סאלאר חאן)

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