إضافة 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 للإشارة إلى أنّ بيانات الشبكة تتجاوز الحد الأقصى المسموح به.

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

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

يحتوي العنصر 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، بترتيب الطبقات المحدّد، لطلب وقت التشغيل لتجميع طبقة تمرير في إخراج الإطار النهائي.

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

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

يمثّل المعرّف 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 أكبر من القيم القصوى.

يجب في النهاية تحرير معرّف 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 يمثّل الحد الأقصى لسعة مخازن رؤوس العناصر لشبكة هذه الطبقة، أو 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 لمثلثات الشبكة، والتي ستُستخدَم لإزالة السطح الخلفي عند عرض الشبكة.
  • 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));

أنواع العناصر الجديدة

ثوابت قائمة التعداد الجديدة

تم توسيع قائمة 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

عمليات التعداد الجديدة

التصاميم الجديدة

الدوالّ الجديدة

المشاكل

سجلّ الإصدارات

  • المراجعة 1، ‎11-09-2024 (ليلى زين)
    • الوصف الأولي للإضافة