إضافة XR_ANDROID_scene_meshing OpenXR

سلسلة الاسم XR_ANDROID_scene_meshing

نوع الإضافة إضافة مثيل

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

المراجعة 3

متطلبات الإضافات والإصدارات OpenXR 1.0

تاريخ آخر تعديل 2025-05-15

حالة الملكية الفكرية لا توجد مطالبات معروفة بشأن الملكية الفكرية.

المساهمون سبنسر كوين، Google جاريد فايندر، Google أنطونيو فونتان، Google كيرن أوفرتورف، Google نيهاف جاين، Google سالار خان، Google سيباستيان كلوز، Google يورغن ستورم، Google فيني داسيلفا، Google ريكاردو كامبل، Google

نظرة عامة

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

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

الأذونات

يجب أن تتضمّن تطبيقات Android الإذن android.permission.SCENE_UNDERSTANDING_FINE في ملف البيان الخاص بها. يُعدّ الإذن android.permission.SCENE_UNDERSTANDING_FINE من الأذونات الحساسة لأنّه يسمح لوقت التشغيل بدراسة بيئة المستخدم.

يجب أن يطلب التطبيق الإذن في وقت التشغيل لاستخدام الوظائف التالية:

(مستوى الحماية: خطير)

فحص إمكانات النظام

يمكن لأحد التطبيقات التحقّق مما إذا كان النظام قادرًا على إنشاء شبكة من المشهد من خلال ربط بنية XrSystemSceneMeshingPropertiesANDROID ببنية XrSystemProperties عند استدعاء xrGetSystemProperties.

XrSystemSceneMeshingPropertiesANDROID

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

أوصاف العضوية

  • ‫type هو XrStructureType لهذا الهيكل.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة بنيات. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • ‫supportsSceneMeshing هو XrBool32، يشير إلى ما إذا كان النظام يتيح ربط المشاهد.

إذا كانت قيمة supportsSceneMeshing هي XR_FALSE، لا يتيح النظام ميزة "دمج المشاهد". يجب أن يتجنّب التطبيق استخدام وظيفة ربط المشاهد عندما تكون قيمة supportsSceneMeshing هي XR_FALSE، لأنّ طلبات xrCreateSceneMeshingTrackerANDROID ستفشل.

إذا كانت قيمة supportsSceneMeshing هي XR_TRUE، يعني ذلك أنّ النظام يتيح ميزة "ربط المشاهد".

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

XrSceneMeshSemanticLabelSetANDROID

يصف التعداد 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;

xrEnumerateSupportedSemanticLabelSetsANDROID

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

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

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

  • ‫instance هو XrInstance تم إنشاؤه بواسطة التطبيق.
  • ‫systemId هو XrSystemId تمت إعادة محاولة الحصول عليه من xrGetSystem.
  • ‫supportedSemanticLabelSetsInputCapacity هي مدة supportedSemanticLabelSets.
  • supportedSemanticLabelSetsOutputCount هو عدد العناصر في supportedSemanticLabelSets التي تم تعديلها بواسطة وقت التشغيل بدءًا من بداية المصفوفة.
  • ‫supportedSemanticLabelSets هي مصفوفة من XrSceneMeshSemanticLabelSetANDROID التي يكتب إليها وقت التشغيل مجموعات التصنيفات الدلالية المتوافقة.

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

إنشاء معرّف لتتبُّع دمج المشاهد

XrSceneMeshingTrackerANDROID

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

يمثّل معرّف XrSceneMeshingTrackerANDROID أداة تتبُّع لربط المشاهد وإدارة الموارد ذات الصلة.

يمكن استخدام هذا المعرّف لإنشاء لقطة لشبكة مشهد باستخدام xrCreateSceneMeshSnapshotANDROID في هذه الإضافة.

xrCreateSceneMeshingTrackerANDROID

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

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

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

إذا كان النظام لا يتيح ربط المشاهد، ستعرض الدالة xrCreateSceneMeshingTrackerANDROID القيمة XR_ERROR_FEATURE_UNSUPPORTED. يمكن للتطبيق التحقّق من توافق النظام من خلال استدعاء xrGetSystemProperties باستخدام بنية XrSystemSceneMeshingPropertiesANDROID.

يمكن استخدام مجموعات التصنيفات الدلالية التي يتيحها النظام فقط في XrSceneMeshingTrackerCreateInfoANDROID::semanticLabelSet عند إنشاء أداة تتبُّع لربط المشهد. يمكن استخدام الدالة xrEnumerateSupportedSemanticLabelSetsANDROID للحصول على قائمة بمجموعات التصنيفات الدلالية المتوافقة.

إذا طلب التطبيق semanticLabelSet غير متوافق، ستعرض الدالة xrCreateSceneMeshingTrackerANDROID القيمة XR_ERROR_FEATURE_UNSUPPORTED.

يتضمّن معرّف xrCreateSceneMeshingTrackerANDROID جميع الموارد اللازمة لإنشاء شبكة المشهد. بعد الانتهاء من تجربة ربط المشاهد، يجب أن يوقف التطبيق المعالج باستخدام الدالة xrDestroySceneMeshingTrackerANDROID.

XrSceneMeshingTrackerCreateInfoANDROID

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

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

xrDestroySceneMeshingTrackerANDROID

تؤدي الدالة xrDestroySceneMeshingTrackerANDROID إلى تحرير tracker والموارد الأساسية عند الانتهاء من تجارب ربط المشهد.

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID          tracker);

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

إنشاء مقبض للقطة شبكة مشهد

XrSceneMeshSnapshotANDROID

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

يمثّل معرّف XrSceneMeshSnapshotANDROID لقطة لشبكة مشهد. يتم إنشاء ذلك باستخدام xrCreateSceneMeshSnapshotANDROID التي تأخذ بشكل أساسي لقطة لبيانات شبكة المشهد في وقت استدعاء الدالة.

يمكن استخدام هذا المعرّف لاسترداد معلومات وبيانات الشبكة الفرعية باستخدام xrGetAllSubmeshStatesANDROID وxrGetSubmeshDataANDROID.

XrSceneMeshSnapshotCreateInfoANDROID

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

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

أوصاف العضوية

  • ‫type هو XrStructureType لهذا الهيكل.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة بنيات. لم يتم تحديد أي بنى من هذا النوع في OpenXR الأساسية أو هذه الإضافة.
  • ‫baseSpace هي XrSpace تُستخدَم لوصف مساحة المرجع التي يجب تمثيل معلومات وضع الشبكات الفرعية للمشهد فيها.
  • ‫time هو XrTime الذي يصف الوقت الذي ستتم فيه معالجة شبكة المشهد أو عرضها.
  • ‫boundingBox هو XrBoxf يصف مربّع الإحاطة الذي سيتم ضمنه الحصول على شبكة المشهد.

XrSceneMeshTrackingStateANDROID

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

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;

XrSceneMeshSnapshotCreationResultANDROID

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

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

أوصاف العضوية

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

xrCreateSceneMeshSnapshotANDROID

يمكن للتطبيق استخدام الدالة xrCreateSceneMeshSnapshotANDROID لإنشاء لقطة لشبكة المشهد من أداة تتبُّع ربط المشهد. تعرض هذه الدالة معرّف XrSceneMeshSnapshotANDROID بالإضافة إلى XrSceneMeshTrackingStateANDROID مضمّن في بنية XrSceneMeshSnapshotCreationResultANDROID. المقبض هو من الناحية الفنية لقطة من بيانات شبكة المشهد في وقت الإنشاء. يمكن استخدام هذا المعرّف لطلب معلومات وبيانات شبكة المشهد باستخدام الدالتَين xrGetAllSubmeshStatesANDROID وxrGetSubmeshDataANDROID على التوالي.

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

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

الحصول على بيانات شبكة المشهد من لقطة شبكة المشهد

XrSceneSubmeshStateANDROID

يصف 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 يصف أبعاد المربّع المحيط الذي يضم الشبكة الفرعية. هذه الحدود هي في المساحة الأساسية التي تم استخدامها لإنشاء معرّف شبكة المشهد.

xrGetAllSubmeshStatesANDROID

يمكن للتطبيق استخدام الدالة xrGetAllSubmeshStatesANDROID للحصول على حالة جميع الشبكات الفرعية في شبكة المشهد. يحتوي هذا الحقل على معلومات أساسية تتيح للتطبيق اختيار الشبكات الفرعية التي يريد الحصول على بياناتها. يمكن استخدام هذه الدالة في تعبير من خطوتين.

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID            snapshot,
    uint32_t                              submeshStateCapacityInput,
    uint32_t*                             submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*           submeshStates);

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

  • ‫snapshot هو معرّف XrSceneMeshSnapshotANDROID تم إنشاؤه سابقًا باستخدام xrCreateSceneMeshSnapshotANDROID.
  • ‫submeshStateCapacityInput هو طول submeshStates.
  • submeshStateCountOutput هو عدد العناصر في submeshStates التي تم تعديلها بواسطة وقت التشغيل بدءًا من بداية الصفيفة.
  • ‫submeshStates هو مصفوفة من بنى XrSceneSubmeshStateANDROID التي ستعرض عليها وقت التشغيل حالة جميع الشبكات الفرعية في شبكة المشهد.

XrSceneSubmeshDataANDROID

يحتوي XrSceneSubmeshDataANDROID على بيانات المثلثات الخاصة بشبكة فرعية بالإضافة إلى معرّف الشبكة الفرعية. يتم استخدام هذا الهيكل في xrGetSubmeshDataANDROID للحصول على بيانات الشبكة الفرعية. يجب أن يضبط التطبيق رقم تعريف الشبكة الفرعية لهذا البنية ومؤشرات المخزن المؤقت إلى المخازن المؤقتة المخصّصة، حتى يمكن ملء البيانات التي تم إرجاعها للشبكة الفرعية في المخازن المؤقتة المخصّصة. يمكن للتطبيق استخدام xrGetSubmeshDataANDROID كعبارة ذات استدعاءَين حيث يتطلّب الاستدعاء الأول من التطبيق ضبط معرّف الشبكة الفرعية والحصول على أحجام المخازن المؤقتة المطلوبة لبيانات الشبكة الفرعية، ثم يمكن للتطبيق تخصيص المخازن المؤقتة والحصول على البيانات في الاستدعاء الثاني.

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.
  • vertexCountOutput هو عدد العناصر في vertexPositions وvertexNormals وvertexSemantics التي تم تعديلها بواسطة وقت التشغيل بدءًا من بداية المصفوفة.
  • vertexPositions هي مصفوفة من XrVector3f التي ستعرض عليها وقت التشغيل مواضع رؤوس الشبكة الفرعية.
  • ‫vertexNormals هو مصفوفة من XrVector3f التي ستعرض عليها وقت التشغيل المتجهات العمودية للرؤوس في الشبكة الفرعية. يمكن ترك هذا الحقل فارغًا إذا أنشأ التطبيق أداة تتبُّع مع إيقاف الإعدادات العادية.NULL
  • vertexSemantics هي مصفوفة من uint8_t التي ستعرض وقت التشغيل دلالات الرأس للشبكة الفرعية. يمكن ترك هذا الحقل فارغًا NULL إذا أنشأ التطبيق أداة تتبُّع مع ضبط XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID التصنيف الدلالي.
  • ‫indexCapacityInput هو طول indices.
  • indexCountOutput هو عدد العناصر في indices التي تم تعديلها بواسطة وقت التشغيل بدءًا من بداية المصفوفة.
  • indices هي مصفوفة من uint32_t التي سيخرج منها وقت التشغيل فهارس الشبكة الفرعية.

xrGetSubmeshDataANDROID

يمكن للتطبيق استخدام الدالة xrGetSubmeshDataANDROID للحصول على بيانات لقائمة محدّدة من الشبكات الفرعية. يمكن استخدام هذه الدالة في تعبير من خطوتين. في الطلب الأول، يجب أن يضبط التطبيق معرّفًا صالحًا للشبكة الفرعية (أي يمكن استرداده من xrGetAllSubmeshStatesANDROID باستخدام لقطة شبكة المشهد نفسها) وسعة صفرية لكل عنصر في القائمة المحدّدة من الشبكات الفرعية للحصول على أحجام المخازن المؤقتة المطلوبة لبيانات الشبكة الفرعية. في طلب البيانات الثاني، يجب أن يضبط التطبيق مؤشرات المخزن المؤقت على مخزن مؤقت مخصّص لكل عنصر في قائمة الشبكات الفرعية المحدّدة، بالإضافة إلى سعة المخازن المؤقتة للحصول على بيانات الشبكات الفرعية.

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

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

XrSceneMeshSemanticLabelANDROID

التعداد 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;

تدمير لقطة شبكة مشهد

xrDestroySceneMeshSnapshotANDROID

يمكن للتطبيق استخدام الدالة xrDestroySceneMeshSnapshotANDROID لتدمير لقطة لشبكة مشهد. بعد إتلاف المعرّف، لا يمكن للتطبيق استخدامه للحصول على معلومات أو بيانات الشبكة الفرعية. يتم إيقاف المعرّف تلقائيًا عند إيقاف أداة التتبُّع لأنّ معرّف أداة التتبُّع هو العنصر الرئيسي لمعرّف لقطة شبكة المشهد.

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID            snapshot);

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

مثال على الرمز البرمجي لإنشاء شبكة المشهد

يوضّح مثال الرمز البرمجي التالي كيفية الوصول إلى بيانات شبكة المشهد لعرضها.

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
  std::vector<XrSceneSubmeshStateANDROID> states;
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  states.resize(submeshCount);
  for (XrSceneSubmeshStateANDROID& state : states) {
    state = {.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.vertexCountOutput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCountOutput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCountOutput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCountOutput];
  }
  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 =
      reinterpret_cast<XrSceneMeshSemanticLabelANDROID*>(data.vertexSemantics);
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

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

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

تمت إضافة ما يلي إلى تعداد XrObjectType:

  • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
  • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

تمت إضافة ما يلي إلى تعداد XrStructureType:

  • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID
  • 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_STATE_ANDROID
  • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID

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

التركيبات الجديدة

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

المشاكل

سجلّ التعديلات

  • النسخة 3، 15-05-2025 (سَلار خان) ** وصف الإضافة الأوّلي

‫OpenXR™ وشعار OpenXR هما علامتان تجاريتان مملوكتان لشركة The Khronos Group Inc. ومسجّلتان كعلامة تجارية في الصين والاتحاد الأوروبي واليابان والمملكة المتحدة.