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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يتم تحميل موارد 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 كجزء من بيئة التطبيقات المجسمة لرسم صناديق السماء.

val skybox = ExrImage.create(session, "BlueSkybox.exr")
Environments.kt

ضبط SpatialEnvironmentPreference لتطبيقك

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

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

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

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

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

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

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(skybox, environmentGeometry)
val preferenceResult =
    session.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.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 للمستخدمين، عليك التأكّد من أنّ مواد العرض تحقّق درجة دقة عالية مع الحفاظ على حجم ملف معقول. يجب التأكّد من أنّ ملف glb يستخدم ملفات mipmaps وملفّات ‎ktx2 texture. عليك أيضًا الانتباه إلى عدد الأشكال الهندسية في ملفات glb، لأنّ ارتفاع عددها يمكن أن يؤدي إلى استهلاك طاقة غير ضروري. تأتي معظم حجم الملف لمعظم نُسخ SpatialEnvironment من الصورة المستخدَمة في صندوق السماء. لضمان تحسين صورك، عليك تشغيل مواد العرض من خلال أداة تحسين (مثل ktx).

تحديد مستوى الشفافية الحالي للعرض

val currentPassthroughOpacity = session.spatialEnvironment.getCurrentPassthroughOpacity()
Environments.kt

انظر أيضًا

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