XR_ANDROID_scene_meshing

Name String

XR_ANDROID_scene_meshing

نوع الإضافة

إضافة مثيل

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

719

المراجعة

3

حالة التصديق

لم تتم المصادقة عليها

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

OpenXR 1.0

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

2025-05-15

حالة الملكية الفكرية

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

المساهمون

"سبنسر كوين"، Google
"جاريد فايندر"، Google
"أنطونيو فونتان"، Google
"كيرن أوفرتورف"، Google
"نيهاف جاين"، Google
"سالار خان"، Google
"سيباستيان كلوز"، Google
"يورغن شتورم"، Google
"فيني داسيلفا"، Google
"ريكاردو كامبل"، 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_DEFAULT2_ANDROID = 1000801000,
    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.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

تمثّل مجموعة التصنيفات الدلالية هذه XrSceneMeshSemanticLabel2ANDROID. (تمت الإضافة من خلال إضافة XR_ANDROID_scene_meshing_semantic_label2)

يتم تعريف الدالة 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

رموز الإرجاع

Success

  • 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.

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

رموز الإرجاع

Success

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

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

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

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

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

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

تُحرِّر الدالة xrDestroySceneMeshingTrackerANDROID المَعلمة tracker والموارد الأساسية عند الانتهاء من تجارب شبكة المشهد.

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

أمان Thread

  • يجب مزامنة الوصول إلى tracker وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

  • 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 على التوالي.

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

رموز الإرجاع

Success

  • 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

رموز الإرجاع

Success

  • 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

رموز الإرجاع

Success

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

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

أمان Thread

  • يجب مزامنة الوصول إلى snapshot وأي معرّفات فرعية خارجيًا

رموز الإرجاع

Success

  • 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 مايو 2025 (سالار خان)

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