إضافة بيئات مكانية إلى تطبيقك

أجهزة XR المعنيّة
تساعدك هذه الإرشادات في إنشاء تجارب لهذه الأنواع من أجهزة الواقع الممتد.
مزيد من المعلومات حول أنواع أجهزة XR →
سماعات رأس بنظام الواقع الممتد
نظارات الواقع الممتد السلكية
مزيد من المعلومات حول أنواع أجهزة XR →

في حزمة تطوير البرامج (SDK) الخاصة بتجربة الواقع الممتد (XR) من Jetpack، البيئات المكانية هي محيط غامر يمكنك إضافته إلى تطبيقك لتخصيص خلفية المشهد الافتراضي. لا تظهر البيئات المكانية إلا عندما يكون التطبيق في وضع "المساحة الكاملة".

نظرة عامة على البيئات المكانية

يُستخدم SpatialEnvironment لإدارة إعدادات البيئة المكانية للتطبيق. وهي تتألف من صورة skybox مستقلة وشكل هندسي محدّد بتنسيق glTF. يمكن ضبط صورة واحدة فقط لخلفية السماء وملف هندسي واحد بتنسيق glTF في المرة الواحدة.

تمثّل Skybox الصورة التي يراها المستخدم من حوله في المشهد الافتراضي، ما يخلق وهمًا بوجود بيئة خلفية بعيدة، مثل السماء أو الجبال أو منظر المدينة. لا يمكن للمستخدم التفاعل مع صندوق السماء أو الاقتراب منه. تتوافق حزمة تطوير البرامج (SDK) الخاصة بـ Jetpack XR مع صناديق السماء الكروية وفقًا لمعيار OpenEXR. بالإضافة إلى توفير خلفية غامرة لتطبيقك، يوفّر صندوق السماء بتنسيق EXR أيضًا إضاءة مستندة إلى الصور (IBL) للتصاميم الثلاثية الأبعاد التي يحمّلها تطبيقك. لمزيد من المعلومات، يُرجى الرجوع إلى دليل العمل مع التصاميم الثلاثية الأبعاد.

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

في إرشادات التصميم الخاصة بالبيئات المكانية، يمكنك التعرّف على أنواع مواد العرض المختلفة التي يمكنك استخدامها لإنشاء بيئات مكانية وكيفية إنشاء بيئات مكانية آمنة وممتعة.

يمكنك ضبط البيئة المكانية لتطبيقك على أحد الإعدادات الثلاثة التالية:

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

إمكانات المساحات للبيئات المكانية

  • SpatialCapabilities: تمثّل هذه السمة إمكانات المساحة في الجلسة الحالية. تتوفّر بعض الإمكانات المكانية ذات الصلة بالبيئات المكانية.

  • SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL: يشير إلى ما إذا كان بإمكان النشاط تفعيل ميزة "نقل البيانات" أو إيقافها في الوقت الحالي.

  • SPATIAL_CAPABILITY_APP_ENVIRONMENT: تشير إلى ما إذا كان بإمكان النشاط ضبط بيئته المكانية الخاصة في الوقت الحالي.

استيراد وتحميل موارد البيئة المكانية

يتم تحميل موارد glTF وEXR للبيئات المكانية بشكل غير متزامن باستخدام الفئة Session.

إنشاء مرجع glTF

يمكن إنشاء مصدر glTF كـ GltfModel، حيث يتم تحميل glTF من ملف محلي. يمكن استخدام GltfModel كجزء من بيئة تطبيق مكاني.

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))
Environments.kt

إنشاء مورد صورة EXR

يمكن إنشاء مورد صورة EXR كـ ExrImage، حيث يتم تحميل EXR من ملف محلي. يمكن استخدام ExrImage مع cmgen لإنشاء ملف ZIP يحتوي على إضاءة مستندة إلى الصورة (IBL) لمشاهدك ثلاثية الأبعاد. يمكنك الاطّلاع على دليلنا حول تحسين أصول البيئة لمزيد من التفاصيل.

val lightingForSkybox = ExrImage.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))
Environments.kt

ضبط SpatialEnvironmentPreference لتطبيقك

تتحكّم السمة preferredSpatialEnvironment في بيئة العرض المكاني المفضّلة للتطبيق. وعند استخدام هذه السمة لضبط الإعدادات المفضّلة، لن تؤدي إلى تغيير فوري إلا إذا كانت السمة isPreferredSpatialEnvironmentActive مضبوطة على true. بعد أن يصبح الجهاز في حالة يمكن فيها تغيير خلفية الواقع الممتد وتتوفّر إمكانية SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENT، سيتم تلقائيًا عرض البيئة المكانية المفضّلة للتطبيق.

سيؤدي ضبط الإعداد على null إلى إيقاف البيئة المكانية المفضّلة للتطبيق، ما يعني أنّه سيتم عرض بيئة النظام التلقائية بدلاً من ذلك.

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

لتلقّي إشعارات بشأن التغييرات في حالة SpatialEnvironment، استخدِم addOnSpatialEnvironmentChangedListener.

الاستخدام الأساسي

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

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, any listeners specified using addOnSpatialEnvironmentChangedListener
    // will be notified.
}
Environments.kt

الاستخدام المتقدّم

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

ضبط PassthroughOpacityPreference للبيئة المكانية لتطبيقك

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

يتم استخدام setPassthroughOpacityPreference لضبط مستوى الشفافية المفضّل لوضع "نقل الفيديو" في أحد التطبيقات. لا تضبط هذه الطريقة سوى الإعدادات المفضّلة ولا تؤدي إلى تغيير فوري إلا إذا كانت إمكانية SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL متاحة. بعد أن يصبح الجهاز في حالة يمكن فيها تغيير مستوى عتامة ميزة "الرؤية المجسّمة" وتصبح إمكانية SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL متاحة، سيتم تلقائيًا تطبيق مستوى العتامة المفضّل لميزة "الرؤية المجسّمة" في التطبيق.

تتراوح قيم إعدادات "معدل شفافية عرض المحيط" من 0.0f (معدل شفافية صفر، حيث لا يظهر سطح عرض المحيط) إلى 1.0f (معدل شفافية كامل، حيث يخفي سطح عرض المحيط البيئة المكانية). المَعلمة setPassthroughOpacityPreference هي قيمة عائمة تقبل القيم الخالية. يشير ضبط القيمة على null إلى أنّ التطبيق ليس لديه إعداد مفضّل لشفافية وضع "الرؤية من خلال الجهاز"، وسيعيد عنصر التحكّم في وضع "الرؤية من خلال الجهاز" إلى النظام.

الاستخدام الأساسي

يضبط مقتطف الرمز هذا الإعداد المفضّل لشفافية النقل المباشر. سيتم تذكُّر هذا الإعداد المفضّل، وسيتم تطبيقه عندما يكون التطبيق قادرًا على ضبط مستوى شفافية العرض المباشر.

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the
    // SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
    // Then, any listeners specified using addOnPassthroughOpacityChangedListener
    // will be notified.
}
Environments.kt

الاستخدام المتقدّم

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

تحسين مواد العرض

عند إنشاء مواد عرض لضبط SpatialEnvironment لدى المستخدمين، احرص على أن تحقّق مواد العرض دقة عالية مع الحفاظ على حجم ملف معقول. لمزيد من المعلومات، يُرجى الاطّلاع على إرشاداتنا بشأن تحسين مواد عرض "البيئة".

تحديد مستوى التعتيم الحالي لوضع "نقل البيانات المرئية"

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity
Environments.kt

انظر أيضًا