XR_ANDROID_scene_meshing

سلسلة الاسم

XR_ANDROID_scene_meshing

نوع الإضافة

إضافة مثيل

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

719

المراجعة

3

حالة التصديق

لم تتم المصادقة

الاعتماديات على الإضافات والإصدارات

OpenXR 1.0

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

2025-05-15

حالة عنوان IP

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

المساهمون

Spencer Quin، Google
Jared Finder، Google
Antonio Fontan، Google
Cairn Overturf، Google
Nihav Jain، Google
Salar Khan، Google
Sebastian Klose، Google
Jürgen Sturm، Google
Vinny DaSilva، Google
Ricardo Campbell، 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، يعني ذلك أنّ النظام يتيح ميزة "دمج المشاهد".

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

يصف التعداد XrSceneMeshSemanticLabelSetANDROID مجموعات التصنيفات الدلالية لإنشاء شبكة المشهد. تمثّل كل قيمة في هذا النوع تعدادًا آخر يحتوي على التصنيفات الدلالية. على سبيل المثال، تمثّل القيمة 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_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

تحمل قيم التعداد المعاني التالية:

وصف التعداد

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

تمثّل مجموعة التصنيفات الدلالية هذه عدم توفّر تصنيفات دلالية.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

تمثّل مجموعة التصنيفات الدلالية هذه XrSceneMeshSemanticLabelANDROID.

يتم تعريف الدالة 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.
  • راجِع فصل مَعلمات حجم المخزن المؤقت للحصول على وصف تفصيلي حول كيفية استرداد حجم supportedSemanticLabelSets المطلوب.

يمكن للتطبيق تعداد مجموعات التصنيفات الدلالية التي يتيحها النظام باستخدام الدالة xrEnumerateSupportedSemanticLabelSetsANDROID.

يجب أن يتيح كل نظام على الأقل استخدام XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID لأنّ قيمة التعداد هذه لا تمثّل أي مجموعة تصنيفات دلالية، ويمكن استخدامها في حال لم يكن التطبيق بحاجة إلى دلالات الرؤوس.

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

  • يجب تفعيل الإضافة 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);

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

يمكن للتطبيق إنشاء معرّف XrSceneMeshingTrackerANDROID باستخدام الدالة xrCreateSceneMeshingTrackerANDROID.

إذا كان النظام لا يتيح ربط المشاهد، يجب أن تعرض وقت التشغيل XR_ERROR_FEATURE_UNSUPPORTED من xrCreateSceneMeshingTrackerANDROID . في هذه الحالة، يجب أن تعرض بيئة التشغيل القيمة XR_FALSE للسمة XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing عند استدعاء الدالة xrGetSystemProperties، حتى يتمكّن التطبيق من تجنُّب إنشاء أداة تتبُّع لربط المشهد.

يجب أن يستخدم التطبيق فقط مجموعات التصنيفات الدلالية التي يتيحها النظام في XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet عند إنشاء أداة تتبُّع لربط المشاهد. إذا كان التطبيق يستخدم مجموعة تصنيفات دلالية غير متوافقة لرؤوس شبكة المشهد، يجب أن يعرض وقت التشغيل الخطأ XR_ERROR_FEATURE_UNSUPPORTED من xrCreateSceneMeshingTrackerANDROID .

يمكن للتطبيق تعداد قائمة مجموعات التصنيفات الدلالية المتوافقة باستخدام الدالة xrEnumerateSupportedSemanticLabelSetsANDROID.

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

يصف البنية XrSceneMeshingTrackerCreateInfoANDROID المعلومات اللازمة لإنشاء معرّف XrSceneMeshingTrackerANDROID.

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

يتم تعريف الدالة xrDestroySceneMeshingTrackerANDROID على النحو التالي:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

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

تُصدر الدالة xrDestroySceneMeshingTrackerANDROID tracker والموارد الأساسية عند الانتهاء من تجارب ربط المشهد.

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

أمان سلاسل المحادثات

  • يجب مزامنة حساب 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 المعلومات اللازمة لإنشاء معرّف XrSceneMeshSnapshotANDROID.

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

يتم تعريف بنية XrSceneMeshSnapshotCreationResultANDROID على النحو التالي:

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

أوصاف الأعضاء

  • type هو XrStructureType لهذه البنية.
  • next هي NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • ‫snapshot هو معرّف XrSceneMeshSnapshotANDROID تم إنشاؤه بواسطة وقت التشغيل.
  • ‫trackingState هو XrSceneMeshTrackingStateANDROID يصف حالة أداة تتبُّع ربط المشهد في وقت إنشاء اللقطة.

يخزّن البنية XrSceneMeshSnapshotCreationResultANDROID نتيجة إنشاء لقطة لشبكة المشهد تم إرجاعها من xrCreateSceneMeshSnapshotANDROID .

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

يصف التعداد XrSceneMeshTrackingStateANDROID حالة التتبُّع لأداة تتبُّع ربط المشاهد. تمثّل كل قيمة في هذا التعداد حالة أداة تتبُّع ربط المشهد.

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;

تحمل قيم التعداد المعاني التالية:

وصف التعداد

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

يبذل وقت التشغيل قصارى جهده لربط submeshId بمنطقة المساحة المادية التي يشغلها الشبكة الفرعية. قد تفقد بيئات التشغيل هذا الربط في أي وقت وتعيّن معرّف UUID جديدًا لأي مجموعة فرعية من الشبكات الفرعية التي تم رصدها. على وجه الخصوص، لا يلزم استخدام معرّفات UUID نفسها للشبكات نفسها في مثيلات التطبيق اللاحقة.

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

يتم تعريف الدالة xrGetSubmeshDataANDROID على النحو التالي:

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

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

يمكن للتطبيق استخدام الدالة xrGetSubmeshDataANDROID للحصول على مجموعات من الشبكات الفرعية أو جميع الشبكات الفرعية في آنٍ واحد، وذلك عن طريق تمرير قائمة XrSceneSubmeshDataANDROID مع ضبط كل XrSceneSubmeshDataANDROID :: submeshId على المعرّف الخاص بالشبكة الفرعية المطلوب استرجاعها.

يجب أن يكون XrSceneSubmeshDataANDROID :: submeshId فريدًا لكل عنصر في inoutSubmeshData ويمكن استرجاعه من خلال xrGetAllSubmeshStatesANDROID لنفس snapshot . إذا كان معرّف الشبكة الفرعية غير صالح أو كان أكثر من عنصر واحد في inoutSubmeshData يحمل معرّف الشبكة الفرعية نفسه، يجب أن يعرض وقت التشغيل XR_ERROR_VALIDATION_FAILURE .

يجب أن تكون قيمة submeshDataCount أقل من أو مساوية للقيمة التي تعرضها الدالة xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput، وإلا يجب أن تعرض وقت التشغيل القيمة XR_ERROR_VALIDATION_FAILURE .

يمكن استخدام هذا في تعبير من خطوتين للاستعلام عن عدد الرؤوس والفهارس لجميع الشبكات الفرعية المحدّدة.

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

  • يجب تفعيل الإضافة 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 يجب أن يكون مؤشرًا إلى مصفوفة من قيم vertexCapacityInput uint8_t
  • إذا لم يكن indexCapacityInput هو 0 ، indices يجب أن يكون مؤشرًا إلى مصفوفة من قيم indexCapacityInput uint32_t

تتضمّن قائمة تعداد 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;

تحمل القيم المُعدّدة المعاني التالية:

وصف التعداد

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

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

أمان سلاسل المحادثات

  • يجب مزامنة حساب 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));

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

الأوامر الجديدة

بنى جديدة

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

ثوابت التعداد الجديدة

  • 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-05-2025 (سار خان)

    • الوصف الأوّلي للإضافة