XR_ANDROID_composition_layer_passthrough_mesh OpenXR एक्सटेंशन

पास-थ्रू लेयर का कंपोज़िशन

XrCompositionLayerPassthroughANDROID में, xrEndFrame को कॉल करते समय, ट्राएंगल मेश पर पास-थ्रू टेक्सचर को रेंडर करने के लिए ज़रूरी जानकारी होती है. XrCompositionLayerPassthroughANDROID, XrFrameEndInfo में इस्तेमाल किए गए बेस स्ट्रक्चर XrCompositionLayerBaseHeader का दूसरा नाम है.

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 वह XrSpace है जिसमें लेयर मेश के pose का आकलन, समय के साथ किया जाता है.
• pose एक XrPosef है, जो space के रेफ़रंस फ़्रेम में लेयर मेश की पोज़िशन और ओरिएंटेशन तय करता है.
• scale एक XrVector3f है, जो लेयर मेश के स्केल की जानकारी देता है.
• opacity एक float है, जो पास-थ्रू टेक्सचर की ओपैसिटी तय करता है. इसकी वैल्यू [0, 1] के बीच होनी चाहिए.
• layer, XrPassthroughLayerANDROID है, जिसे पहले xrCreatePassthroughLayerANDROID ने बनाया था.

ऐप्लिकेशन, बनाए गए layer और XrPassthroughLayerMeshANDROID से मिले मेश के साथ XrCompositionLayerPassthroughANDROID स्ट्रक्चर बन सकता है.

XrCompositionLayerPassthroughANDROID का पॉइंटर, xrEndFrame में सबमिट किया जा सकता है. यह पॉइंटर, चुने गए लेयर के क्रम में, बेस स्ट्रक्चर XrCompositionLayerBaseHeader का पॉइंटर होता है. इससे रनटाइम को फ़ाइनल फ़्रेम आउटपुट में पासथ्रू लेयर को कंपोज करने का अनुरोध किया जाता है.

मान्य इस्तेमाल (इंप्लिसिट)

• XrCompositionLayerPassthroughANDROID का इस्तेमाल करने से पहले, XR_ANDROID_composition_layer_passthrough_mesh एक्सटेंशन चालू होना ज़रूरी है
• type होनी चाहिए XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
• next NULL या स्ट्रक्चर चेन में अगले स्ट्रक्चर का मान्य पॉइंटर होना चाहिए
• layerFlags की वैल्यू 0 या XrCompositionLayerFlagBits की वैल्यू के मान्य कॉम्बिनेशन में से कोई एक होनी चाहिए
• space यह XrSpace का मान्य हैंडल होना चाहिए
• layer XrPassthroughLayerANDROID हैंडल मान्य होना ज़रूरी है
• layer और space, दोनों को एक ही XrSession से बनाया, असाइन या फिर वापस पाया गया हो

पासथ्रू लेयर हैंडल बनाना

XrPassthroughLayerANDROID हैंडल, पासथ्रू लेयर को दिखाता है. यह XrCompositionLayerPassthroughANDROID के व्यवहार को तय करता है.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

कोई ऐप्लिकेशन, xrCreatePassthroughLayerANDROID को कॉल करके, XrPassthroughLayerANDROID हैंडल बना सकता है. दिखाए गए XrPassthroughLayerANDROID हैंडल का इस्तेमाल, एपीआई कॉल में बाद में किया जा सकता है.

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

पैरामीटर की जानकारी

• session एक XrSession है, जिसमें पासथ्रू लेयर बनाई जाएगी.
• createInfo, XrPassthroughLayerCreateInfoANDROID स्ट्रक्चर का पॉइंटर है. इसमें, पासथ्रू लेयर के शुरुआती पैरामीटर की जानकारी होती है. इस फ़ील्ड को XrPassthroughLayerMeshANDROID स्ट्रक्चर से भी जोड़ा जा सकता है, ताकि एक ही समय पर मेश सेट किया जा सके.
• layer, उस हैंडल का पॉइंटर है जिसमें बनाया गया XrPassthroughLayerANDROID दिखाया जाता है.

ऐप्लिकेशन को XrPassthroughLayerCreateInfoANDROID::vertexCapacity और XrPassthroughLayerCreateInfoANDROID::indexCapacity में, पास-थ्रू मेश इंडेक्स की संख्या तय करनी चाहिए. यह संख्या, xrGetSystemProperties को कॉल करते समय, XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount और XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount से मिली ज़्यादा से ज़्यादा वैल्यू से कम या उसके बराबर होनी चाहिए. अगर createInfo से तय किए गए मेश इंडेक्स की संख्या, ज़्यादा से ज़्यादा वैल्यू से ज़्यादा है, तो xrCreatePassthroughLayerANDROID, XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID गड़बड़ी दिखाएगा.

xrDestroyPassthroughLayerANDROID फ़ंक्शन का इस्तेमाल करके, XrPassthroughLayerANDROID हैंडल को आखिर में खाली करना ज़रूरी है.

मान्य इस्तेमाल (इंप्लिसिट)

• xrCreatePassthroughLayerANDROID को कॉल करने से पहले, XR_ANDROID_composition_layer_passthrough_mesh एक्सटेंशन चालू होना ज़रूरी है
• session यह एक मान्य XrSession हैंडल होना चाहिए
• createInfo यह, XrPassthroughLayerCreateInfoANDROID स्ट्रक्चर के लिए मान्य पॉइंटर होना चाहिए
• layer XrPassthroughLayerANDROID हैंडल का पॉइंटर होना चाहिए

रिटर्न कोड

सफलता

• 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 है, जो इस लेयर के मेश के लिए वर्टिक्स बफ़र की ज़्यादा से ज़्यादा क्षमता को दिखाता है. अगर कोई वैल्यू नहीं दी गई है, तो 0 दिखेगा. अगर यह वैल्यू दी गई है, तो इस लेयर के लिए सेट किए गए किसी भी मेश की XrPassthroughLayerMeshANDROID::vertexCount वैल्यू, vertexCapacity से कम या उसके बराबर होनी चाहिए.
• indexCapacity एक uint32_t है, जो इस लेयर के मेश के लिए इंडेक्स बफ़र की ज़्यादा से ज़्यादा क्षमता को दिखाता है. अगर कोई वैल्यू नहीं दी गई है, तो यह 0 होता है. अगर यह वैल्यू दी गई है, तो इस लेयर के लिए सेट किए गए किसी भी मेश का XrPassthroughLayerMeshANDROID::indexCount, indexCapacity से कम या उसके बराबर होना चाहिए.

मान्य इस्तेमाल (इंप्लिसिट)

• XrPassthroughLayerCreateInfoANDROID का इस्तेमाल करने से पहले, XR_ANDROID_composition_layer_passthrough_mesh एक्सटेंशन चाहिए कि चालू हो
• type होनी चाहिए XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
• next NULL या स्ट्रक्चर चेन में अगले स्ट्रक्चर का मान्य पॉइंटर होना चाहिए. यह भी देखें: XrPassthroughLayerMeshANDROID

ऐप्लिकेशन, पासथ्रू लेयर और उसमें मौजूद संसाधनों को रिलीज़ करने के लिए, xrDestroyPassthroughLayerANDROID फ़ंक्शन का इस्तेमाल कर सकता है.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

पैरामीटर की जानकारी

• layer वह XrPassthroughLayerANDROID है जिसे मिटाना है.

मान्य इस्तेमाल (इंप्लिसिट)

• xrDestroyPassthroughLayerANDROID को कॉल करने से पहले, XR_ANDROID_composition_layer_passthrough_mesh एक्सटेंशन चालू होना चाहिए
• layer यह एक मान्य XrPassthroughLayerANDROID हैंडल होना चाहिए

थ्रेड की सुरक्षा

• layer और किसी भी चाइल्ड हैंडल का ऐक्सेस, बाहरी तौर पर सिंक किया जाना चाहिए

रिटर्न कोड

सफलता

• XR_SUCCESS

प्रोसेस पूरी नहीं हो सकी

• XR_ERROR_FUNCTION_UNSUPPORTED
• XR_ERROR_RUNTIME_FAILURE
• XR_ERROR_HANDLE_INVALID

पास-थ्रू लेयर मेश सेट करना

ऐप्लिकेशन, पासथ्रू लेयर के लिए मेश सेट करने के लिए, xrSetPassthroughLayerMeshANDROID फ़ंक्शन का इस्तेमाल कर सकता है.

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

पैरामीटर की जानकारी

• layer एक XrPassthroughLayerANDROID हैंडल है, जिसमें दिए गए mesh के साथ अपडेट करना है.
  • mesh, XrPassthroughLayerMeshANDROID स्ट्रक्चर का एक पॉइंटर है, जिसमें मेश की जानकारी दी गई है.

ऐप्लिकेशन को XrPassthroughLayerMeshANDROID::vertexCount और XrPassthroughLayerMeshANDROID::indexCount में, पासथ्रू मेश इंडेक्स की संख्या तय करनी चाहिए. यह संख्या, xrGetSystemProperties को कॉल करते समय, XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount और XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount से मिली ज़्यादा से ज़्यादा वैल्यू से कम या उसके बराबर होनी चाहिए. अगर xrSetPassthroughLayerMeshANDROID से mesh के ज़रिए दिए गए मेश इंडेक्स की संख्या, ज़्यादा से ज़्यादा वैल्यू से ज़्यादा है, तो XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID दिखाया जाएगा.

अगर xrCreatePassthroughLayerANDROID का इस्तेमाल करके layer बनाते समय, XrPassthroughLayerCreateInfoANDROID::vertexCapacity और XrPassthroughLayerCreateInfoANDROID::indexCapacity से मेश बफ़र की क्षमता तय की जाती है, तो mesh से तय किए गए मेश इंडेक्स की संख्या, क्षमता से ज़्यादा होने पर, xrSetPassthroughLayerMeshANDROID पर XR_ERROR_SIZE_INSUFFICIENT गड़बड़ी दिखेगी.

मान्य इस्तेमाल (इंप्लिसिट)

• xrSetPassthroughLayerMeshANDROID को कॉल करने से पहले, XR_ANDROID_composition_layer_passthrough_mesh एक्सटेंशन चालू होना ज़रूरी है
• layer यह एक मान्य XrPassthroughLayerANDROID हैंडल होना चाहिए
• mesh XrPassthroughLayerMeshANDROID के मान्य स्ट्रक्चर का पॉइंटर होना चाहिए

रिटर्न कोड

सफलता

• 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 है. इसका इस्तेमाल, मेश को रेंडर करते समय बैकफ़ेस कलिंग के लिए किया जाएगा.
• vertexCount एक uint32_t है, जो मेश में वर्टिसेस की संख्या दिखाता है. XrPassthroughLayerCreateInfoANDROID::vertexCapacity के लिए वैल्यू तय करने पर, vertexCount को vertexCapacity से कम या उसके बराबर होना चाहिए.
  • vertices, XrVector3f के कलेक्शन का पॉइंटर है. इसमें ट्राएंगल मेश के वर्टिक्स की पोज़िशन होती हैं.
• indexCount एक uint32_t है, जो त्रिभुज मेश में इंडेक्स की संख्या दिखाता है. अगर पिछले indexCount % 3 इंडेक्स हैं, तो उन्हें नहीं दिखाया जाएगा. XrPassthroughLayerCreateInfoANDROID::indexCapacity तय करने पर, indexCount को indexCapacity से कम या उसके बराबर होना चाहिए.
• indices, uint16_t के कलेक्शन का पॉइंटर है. इसमें त्रिभुज मेश के इंडेक्स होते हैं.

मान्य इस्तेमाल (इंप्लिसिट)

• XrPassthroughLayerMeshANDROID का इस्तेमाल करने से पहले, XR_ANDROID_composition_layer_passthrough_mesh एक्सटेंशन चालू होना ज़रूरी है
• type होनी चाहिए XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
• next NULL या स्ट्रक्चर चेन में अगले स्ट्रक्चर का मान्य पॉइंटर होना चाहिए
• windingOrder XrWindingOrderANDROID की मान्य वैल्यू होनी चाहिए
• अगर vertexCount, 0, vertices नहीं है, तो यह vertexCount XrVector3f स्ट्रक्चर के ऐरे के पॉइंटर के तौर पर होना चाहिए
• अगर indexCount, 0, indices नहीं है, तो indexCount 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));

नए ऑब्जेक्ट टाइप

• XrPassthroughLayerANDROID

नई Enum Constant

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

नए Enums

• XrWindingOrderANDROID

नए स्ट्रक्चर

• XrPassthroughLayerCreateInfoANDROID
• XrPassthroughLayerMeshANDROID
• XrCompositionLayerPassthroughANDROID
• XrSystemPassthroughLayerPropertiesANDROID

नए फ़ंक्शन

• xrCreatePassthroughLayerANDROID
• xrDestroyPassthroughLayerANDROID
• xrSetPassthroughLayerMeshANDROID

समस्याएं

वर्शन का इतिहास

• पहला बदलाव, 11-09-2024 (लेवन चेन)
  • एक्सटेंशन के बारे में शुरुआती जानकारी