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

أجهزة XR المشمولة

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

مزيد من المعلومات حول أنواع أجهزة XR →

مزيد من المعلومات حول أنواع أجهزة XR →

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

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

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

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

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

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

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

• مزيج من صورة skybox وشكل 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

إنشاء مصدر إضاءة مستند إلى صورة

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

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

ضبط SpatialEnvironmentPreference لتطبيقك

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

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

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

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

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

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

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

انظر أيضًا

• إرشادات تصميم البيئات المكانية