תוסף OpenXR‏ XR_ANDROID_composition_layer_passthrough_mesh

מחרוזת שם

XR_ANDROID_composition_layer_passthrough_mesh

סוג התוסף

תוסף למכונה

מספר תוסף רשום

463

גרסה

1

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

OpenXR 1.0

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

2024-09-18

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

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

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

גרנט יושידה (Grant Yoshida), Google

Kevin Moule, ‏ Google

Vasiliy Baranov, ‏ Google

פיטר צ'ן (Peter Chen), Google

לבנה צ'ן, Google

סקירה כללית

במכשירים שתומכים במספר מצבי שילוב סביבה, המערכת עשויה לספק הגדרות העברה (passthrough) כדי להציג למשתמש את הסביבה הפיזית שלו מתצוגה immersive.

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

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

  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;

כדי להעביר מסך מלא, האפליקציות יכולות להשתמש במצב ערבוב סביבה.

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

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

typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. אין מבנים כאלה מוגדרים ב-OpenXR או בהרחבה הזו.
  • supportsPassthroughLayer הוא XrBool32, שמציין אם המערכת הנוכחית תומכת במעבר רשת (passthrough) של שכבת קומפוזיציה.
  • maxMeshIndexCount הוא uint32_t שמחזיר את המספר המקסימלי של אינדקסים שייקבלו למערך רשתות של העברה ישירה.
  • maxMeshVertexCount הוא uint32_t שמחזיר את המספר המקסימלי של קודקודים שייכללו ברשת העברה.

אם הפונקציה supportsPassthroughLayer מחזירה את הערך XR_FALSE, המערכת לא תומכת ברשת של העברה ישירה של שכבת קומפוזיציה, ולכן תקבל את הערך XR_ERROR_FEATURE_UNSUPPORTED מהפונקציה xrCreatePassthroughLayerANDROID. צריך להימנע משימוש ב-mesh של העברה ישירה בשכבת הקומפוזיציה כש-supportsPassthroughLayer הוא XR_FALSE.

אם הפונקציה supportsPassthroughLayer מחזירה את הערך XR_TRUE, המערכת תומכת במעבר של רשתות (mesh) דרך שכבת קומפוזיציה. במקרה כזה, הפונקציות maxMeshIndexCount ו-maxMeshVertexCount יחזירו מספר שאינו אפס. באפליקציה צריך להשתמש ב-maxMeshIndexCount וב-maxMeshVertexCount כערכים המקסימליים להגדרת רשתות של העברה דרך כשקוראים ל-xrCreatePassthroughLayerANDROID ול-xrSetPassthroughLayerMeshANDROID. אחרת, יכול להיות שהערך XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID יוחזר כדי לציין שנתוני הרשת חורגים מהמגבלה הנתמכת.

שימוש תקין (מרומז)

הרכב השכבה השקופה

השכבה XrCompositionLayerPassthroughANDROID מכילה את המידע הדרוש לעיבוד (רנדר) של טקסטורה של העברה (passthrough) על רשת משולשים בזמן הקריאה ל-xrEndFrame. XrCompositionLayerPassthroughANDROID הוא סוג כינוי למבנה הבסיס XrCompositionLayerBaseHeader שמשמש ב-XrFrameEndInfo.

typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • next הוא NULL או הפניה למבנה הבא בשרשרת המבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בהרחבה הזו.
  • layerFlags הוא מסכת ביט של XrCompositionLayerFlags שמתארת את הדגלים שיוחלו על השכבה.
  • space הוא מרחב Xr שבו pose של רשת השכבות נמדד לאורך זמן.
  • pose הוא XrPosef שמגדיר את המיקום והכיוון של רשת השכבה במסגרת העזר של space.
  • scale הוא XrVector3f שמגדיר את קנה המידה של רשת השכבה.
  • opacity הוא float שמגדיר את האטימות של טקסטורת העברה בטווח [0, 1].
  • layer הוא XrPassthroughLayerANDROID שנוצר קודם לכן על ידי xrCreatePassthroughLayerANDROID.

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

אפשר לשלוח הפניה ל-XrCompositionLayerPassthroughANDROID ב-xrEndFrame כהפניה למבנה הבסיס XrCompositionLayerBaseHeader, בסדר השכבות שנבחר, כדי לבקש מסביבת זמן הריצה ליצור שכבת העברה (passthrough) בתוצר המסגרת הסופי.

שימוש תקין (מרומז)

יצירת שם למעטפת של שכבת העברה

הידית XrPassthroughLayerANDROID מייצגת שכבת העברה שמגדירה את ההתנהגות של XrCompositionLayerPassthroughANDROID.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

אפליקציה יכולה ליצור מנוף XrPassthroughLayerANDROID באמצעות קריאה ל-xrCreatePassthroughLayerANDROID. אפשר להשתמש במנהל XrPassthroughLayerANDROID שהוחזרה בקריאות API. 

XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);

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

האפליקציה צריכה לציין את מספר אינדקסי הרשת של העברה דרך XrPassthroughLayerCreateInfoANDROID::vertexCapacity ו-XrPassthroughLayerCreateInfoANDROID::indexCapacity, כך שהם יהיו קטנים או שווים לערכי המקסימום שמוחזרים על ידי XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount ו-XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount בקריאה ל-xrGetSystemProperties. xrCreatePassthroughLayerANDROID תחזיר שגיאת XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID אם מספר אינדקסי הרשת שמוגדר על ידי createInfo גדול מהערכים המקסימליים.

בסופו של דבר צריך לפנות את ה-handle של XrPassthroughLayerANDROID באמצעות הפונקציה xrDestroyPassthroughLayerANDROID.

שימוש תקין (מרומז)

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

כישלון

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

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

typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • next הוא ערך NULL או הפניה למבנה הבא בשרשרת המבנים. אפשר לספק את XrPassthroughLayerMeshANDROID בשרשרת הבאה כדי לציין רשת ראשונית לשכבת העברה כשקוראים ל-xrCreatePassthroughLayerANDROID.
  • vertexCapacity הוא uint32_t שמייצג את הקיבולת המקסימלית של מאגר הנקודות (vertex buffer) של המארג של השכבה הזו, או 0 אם לא צוין אחרת. אם יצוין, הערך של XrPassthroughLayerMeshANDROID::vertexCount של כל רשת שמוגדר לה שכבה הזו חייב להיות קטן מ-vertexCapacity או שווה לו.
  • indexCapacity הוא uint32_t שמייצג את הקיבולת המקסימלית של מאגר האינדקס של הרשת של השכבה הזו, או 0 אם לא צוין אחרת. אם יצוין, הערך של XrPassthroughLayerMeshANDROID::indexCount של כל רשת שמוגדר לה שכבה הזו חייב להיות קטן מ-indexCapacity או שווה לו.

שימוש תקין (מרומז)

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

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

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

שימוש תקין (מרומז)

בטיחות בשרשור

  • חובה לסנכרן באופן חיצוני את הגישה ל-layer ואת כל כינויי הילדים

קודי החזרה

הצלחה

  • XR_SUCCESS

כישלון

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

הגדרת רשת של שכבת העברה

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

XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);

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

האפליקציה צריכה לציין את מספר אינדקסי הרשת של העברה דרך XrPassthroughLayerMeshANDROID::vertexCount ו-XrPassthroughLayerMeshANDROID::indexCount, כך שהם יהיו קטנים או שווים לערכי המקסימום שמוחזרים על ידי XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount ו-XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount בקריאה ל-xrGetSystemProperties. אם מספר האינדקסים של הרשת שמוצגים ב-mesh מ-xrSetPassthroughLayerMeshANDROID גדול מהערכים המקסימליים, יוחזר הערך XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID.

אם קיבולת מאגר המשנה של המבנה רשומה ב-XrPassthroughLayerCreateInfoANDROID::vertexCapacity וב-XrPassthroughLayerCreateInfoANDROID::indexCapacity כשיוצרים את layer באמצעות xrCreatePassthroughLayerANDROID, השגיאה XR_ERROR_SIZE_INSUFFICIENT תוחזר ב-xrSetPassthroughLayerMeshANDROID אם מספר האינדקסים של המבנה שמוגדר על ידי mesh גדול מהקיבולת.

שימוש תקין (מרומז)

קודי החזרה

הצלחה

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

כישלון

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

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

typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;

תיאורי חברים

  • type הוא XrStructureType של המבנה הזה.
  • next הוא NULL או הפניה למבנה הבא בשרשרת המבנים.
  • windingOrder הוא XrWindingOrderANDROID של משולשי המארג, שישמש לצורך סינון צד עורפי (backface culling) במהלך העיבוד הגרפי של המארג.
  • vertexCount הוא uint32_t שמייצג את מספר הקודקודים ברשת. כשמציינים את XrPassthroughLayerCreateInfoANDROID::vertexCapacity, הערך של vertexCount חייב להיות קטן מ-vertexCapacity או שווה לו.
    • vertices הוא הפניה למערך של XrVector3f שמכיל את מיקומי הנקודות של רשת המשולשים.
  • indexCount הוא uint32_t שמייצג את מספר האינדקסים ברשת המשולשים. האינדקסים האחרונים של indexCount % 3, אם יש כאלה, לא יתוארו. כשמציינים את XrPassthroughLayerCreateInfoANDROID::indexCapacity, הערך של indexCount חייב להיות קטן מ-indexCapacity או שווה לו.
  • indices הוא הפניה למערך של uint16_t שמכיל את האינדקסים של רשת המשולשים.

שימוש תקין (מרומז)

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

typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;

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

  • XR_WINDING_ORDER_UNKNOWN_ANDROID  — סדר ההתחברות של המשולשים של הרשת לא ידוע.
  • XR_WINDING_ORDER_CW_ANDROID  — סדר ההתחברות של המשולשים של הרשת הוא בכיוון השעון.
  • XR_WINDING_ORDER_CCW_ANDROID  — סדר ההתחברות של המשולשים של הרשת הוא נגד כיוון השעון.

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

קוד הדוגמה הבא מראה איך יוצרים שכבת העברה ומשתמשים בה ביצירת קומפוזיציה.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace space; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreatePassthroughLayerANDROID xrCreatePassthroughLayerANDROID; // previously initialized
PFN_xrDestroyPassthroughLayerANDROID xrDestroyPassthroughLayerANDROID; // previously initialized
PFN_xrSetPassthroughLayerMeshANDROID xrSetPassthroughLayerMeshANDROID; // previously initialized

// Inspect passthrough mesh system properties
XrSystemPassthroughLayerPropertiesANDROID passthroughLayerSystemProperties{
  XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{
  XR_TYPE_SYSTEM_PROPERTIES, &passthroughLayerSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!passthroughLayerSystemProperties.supportsPassthroughLayer) {
    // the system does not support composite layer passthrough mesh.
    return;
}

// The initial mesh for the layer.
XrPassthroughLayerMeshANDROID mesh = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID,
  .windingOrder = XR_WINDING_ORDER_CW_ANDROID,
  .vertexCount = 4,
  .vertices = {
    { 0, 0, 0 }, { 0, 1, 0 }, { 1, 1, 0 }, { 1, 0, 0 }
  },
  .indexCount = 6,
  .indices = {
    0, 1, 2,
    0, 2, 3
  },
};

// Create the layer. Layers are expected to persist across frames.
XrPassthroughLayerCreateInfoANDROID create_info = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID,
  .next = &mesh,
  .vertexCapacity = 0,
  .indexCapacity = 0,
};
XrPassthroughLayerANDROID layer;
CHK_XR(xrCreatePassthroughLayerANDROID(session, &create_info, &layer));

// Create a composition layer. Composition layers are submitted per frame.
XrCompositionLayerPassthroughANDROID passthrough_layer = {
  .type = XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID,
  .next = nullptr,
  .layerFlags = 0,
  .space = space,
  .pose = {
    .orientation = { 0.0f, 0.0f, 0.0f, 1.0f }
    .position = { 0.0f, 0.0f, 0.0f }
  },
  .scale = { 1.0f, 1.0f, 1.0f },
  .opacity = 1.0f,
  .layer = layer
};

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

    // Submit composition layer in xrEndFrame.
    std::vector<XrCompositionLayerBaseHeader*> layers = {
        ...,
        &passthrough_layer,
        ...,
    };
    XrFrameEndInfo end_frame_info = { XR_TYPE_FRAME_END_INFO, nullptr };
    end_frame_info.layerCount = (uint32_t)layers.size();
    end_frame_info.layers = layers.data();
    CHK_XR(xrEndFrame(session, &end_frame_info));

    // Update the layer. Results can be seen the next time a passthrough composition
    // layer is submitted.
    mesh.indexCount = 9;
    const uint16_t new_index_buffer[] = {
        0, 1, 2,
        0, 2, 3,
        0, 1, 2
    };
    mesh.indexBuffer = &new_index_buffer[0];
    CHK_XR(xrSetPassthroughLayerMeshANDROID(&layer, &mesh));

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

// Clean up.
CHK_XR(xrDestroyPassthroughLayerANDROID(layer));

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

קבועים חדשים של Enum

המניין XrObjectType הורחב עם:

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

המניין XrStructureType הורחב עם:

  • XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
  • XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
  • XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
  • XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID

המניין XrResult הורחב עם:

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

משתני Enum חדשים

מבנים חדשים

פונקציות חדשות

בעיות

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

  • גרסה 1, 11 בספטמבר 2024 (Levana Chen)
    • תיאור ראשוני של התוסף