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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

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

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

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

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

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

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

• ‫SpatialCapabilities: يمثّل الإمكانات المكانية للجلسة الحالية. ترتبط بعض الإمكانات المكانية بالبيئات المكانية.

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

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

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

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

إنشاء مورد glTF

يمكن إنشاء مورد glTF كعنصر GltfModel يتم تحميل glTF فيه من ملف على الجهاز. يمكن استخدام GltfModel كجزء من بيئة التطبيقات المساحية.

val environmentGeometryFuture = GltfModel.create(session, "DayGeometry.glb")
val environmentGeometry = environmentGeometryFuture.await()
Environments.kt

إنشاء مورد صورة بتنسيق EXR

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

val lightingForSkybox = ExrImage.create(session, "BlueSkyboxLighting.zip")
Environments.kt

ضبط SpatialEnvironmentPreference لتطبيقك

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

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

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

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

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

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

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
val preferenceResult =
    session.scene.spatialEnvironment.setSpatialEnvironmentPreference(spatialEnvironmentPreference)
if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangeApplied()) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else if (preferenceResult == SpatialEnvironment.SetSpatialEnvironmentPreferenceChangePending()) {
    // The environment is in the process of being updated. Once visible, 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 إلى أنّ التطبيق ليس لديه إعدادات مفضّلة لمعدّل الشفافية للعرض المباشر، و سيعيد التحكّم في العرض المباشر إلى النظام.

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

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

val preferenceResult = session.scene.spatialEnvironment.setPassthroughOpacityPreference(1.0f)
if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangeApplied()) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified
} else if (preferenceResult == SpatialEnvironment.SetPassthroughOpacityPreferenceChangePending()) {
    // 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.getCurrentPassthroughOpacity()
Environments.kt

انظر أيضًا

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