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

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

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

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

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

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

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

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

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

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

  • 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

انظر أيضًا