إضافة OpenXR‏ XR_ANDROID_composition_layer_passthrough_mesh

سلسلة الاسم

XR_ANDROID_composition_layer_passthrough_mesh

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

463

المراجعة

1

التبعيات المتعلّقة بالإصدارات والإضافات

OpenXR 1.0

تاريخ آخر تعديل

2024-09-18

حالة عنوان IP

ما مِن مطالبات معروفة بعناوين IP.

المساهمون

"غرانت يوشيدا"، Google

كيفن مول، Google

فاسيليي باراسنوي، Google

بيتر تشين، Google

ليفانا تشين، من Google

نظرة عامة

بالنسبة إلى الأجهزة التي تتيح أوضاع دمج بيئات متعددة، قد يقدّم النظام إعدادات للعرض المباشر من أجل عرض البيئة المادية للمستخدم من خلال عرض غامر.

تتيح هذه الإضافة للتطبيقات عرض مواد تمرير على سطح أشكال هندسية عشوائية من خلال طبقة تركيب إضافية 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، ويشير إلى ما إذا كان النظام الحالي يتيح شبكة تمرير طبقة التركيب.
• دالة maxMeshIndexCount هي دالة uint32_t تعرض الحد الأقصى لعدد الفهارس التي سيتم قبولها لشبكة تمرير.
• maxMeshVertexCount هي دالة uint32_t تعرض الحد الأقصى لعدد الرؤوس التي سيتم قبولها لشبكة تمرير.

إذا كانت القيمة التي يعرضها supportsPassthroughLayer هي XR_FALSE، يعني ذلك أنّ النظام لا يتيح استخدام شبكة تمرير طبقة التركيبة، وبالتالي سيتلقّى XR_ERROR_FEATURE_UNSUPPORTED من xrCreatePassthroughLayerANDROID. يجب أن يتجنب التطبيق استخدام شبكة تمرير طبقة التركيبة عندما يكون supportsPassthroughLayer هو XR_FALSE.

إذا كانت القيمة التي يعرضها supportsPassthroughLayer هي XR_TRUE، يعني ذلك أنّ النظام يتوافق مع شبكة تمرير طبقة التركيبة. في هذه الحالة، ستعرِض الدالتان maxMeshIndexCount وmaxMeshVertexCount رقمًا غير صفري. يجب أن يستخدم التطبيق maxMeshIndexCount وmaxMeshVertexCount كأقصى قيم لضبط شبكات العبور عند استدعاء xrCreatePassthroughLayerANDROID وxrSetPassthroughLayerMeshANDROID، وإلا قد يتم عرض XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID للإشارة إلى أنّ بيانات الشبكة تتجاوز الحد الأقصى المسموح به.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_ANDROID_composition_layer_passthrough_mesh قبل استخدام XrSystemPassthroughLayerPropertiesANDROID.
• type يجب أن يكون XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID
• next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية.

تركيبة طبقة "رؤية العالم المحيط"

يحتوي العنصر XrCompositionLayerPassthroughANDROID على المعلومات اللازمة لمعالجة ملفّ نسيج من خلال شبكة مثلّثة عند استدعاء 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 هو XrSpace الذي يتم فيه تقييم pose لشبكة الطبقة بمرور الوقت.
• pose هو XrPosef يحدِّد موضع شبكة الطبقة واتجاهها في الإطار المرجعي للspace.
• scale هو XrVector3f يحدِّد مقياس شبكة الطبقة.
• opacity هو float يحدِّد مستوى شفافية نسيج السماح بالمرور في النطاق [0، 1].
• layer هو XrPassthroughLayerANDROID الذي تم إنشاؤه سابقًا باستخدامxrCreatePassthroughLayerANDROID.

يمكن للتطبيق إنشاء XrCompositionLayerPassthroughANDROID هيكل باستخدام layer الذي تم إنشاؤه والشبكات المقابلة التي يوفّرها XrPassthroughLayerMeshANDROID.

يمكن إرسال مؤشر إلى XrCompositionLayerPassthroughANDROID في xrEndFrame كمؤشر إلى البنية الأساسية XrCompositionLayerBaseHeader، بترتيب الطبقات المحدّد، لطلب وقت التشغيل لتجميع طبقة تمرير في إخراج الإطار النهائي.

الاستخدام الصالح (ضمني)

• يجب تفعيل إضافة XR_ANDROID_composition_layer_passthrough_mesh قبل استخدام XrCompositionLayerPassthroughANDROID.
• type يجب أن يكون XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
• next يجب أن يكون NULL أو مؤشرًا صالحًا إلى البنية التالية في سلسلة البنية.
• layerFlags يجب أن تكون 0 أو مجموعة صالحة من قيم XrCompositionLayerFlagBits
• space يجب أن يكون معرّف XrSpace صالحًا
• layer يجب أن يكون معرّف XrPassthroughLayerANDROID صالحًا
• يجب أن يكون كلّ من layer وspace قد تم إنشاؤهما أو تخصيصهما أو retrievingهما من XrSession نفسها.

إنشاء اسم معرِّف لطبقة تمرير

يمثّل المعرّف XrPassthroughLayerANDROID طبقة تمرير تحدد سلوك XrCompositionLayerPassthroughANDROID.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

يمكن للتطبيق إنشاء معرّف XrPassthroughLayerANDROID من خلال استدعاء xrCreatePassthroughLayerANDROID. يمكن استخدام معرّف XrPassthroughLayerANDROID الذي تم إرجاعه لاحقًا في طلبات البيانات من واجهة برمجة التطبيقات.

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

أوصاف المَعلمات

• session هو XrSession سيتم إنشاء طبقة العبور لها.
• createInfo هو مؤشر إلى بنية XrPassthroughLayerCreateInfoANDROID التي تحدّد مَعلمات الطبقة الأولى للعرض. يمكن أيضًا ربط هذا الحقل ببنية XrPassthroughLayerMeshANDROID لضبط الشبكة في الوقت نفسه.
• layer هو مؤشر إلى معرّف يتم من خلاله عرض العنصر الذي تم إنشاؤه XrPassthroughLayerANDROID.

يجب أن يحدِّد التطبيق عدد فهارس الشبكة التي يتم تمريرها في XrPassthroughLayerCreateInfoANDROID::vertexCapacity وXrPassthroughLayerCreateInfoANDROID::indexCapacity بحيث يكون أقل من أو يساوي XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount وXrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount عند استدعاء xrGetSystemProperties. سيعرض xrCreatePassthroughLayerANDROID خطأ XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID إذا كان عدد فهارس الشبكةالذي يحدِّدهcreateInfo أكبر من الحد الأقصى للقيم.

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

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

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

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

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

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