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

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

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

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

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

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

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

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

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

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

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

  • ‫SpatialCapability: تمثّل الإمكانات المكانية للجلسة الحالية. بعض الإمكانات المكانية ذات صلة بالبيئات المكانية.

  • SpatialCapability.PASSTHROUGH_CONTROL: يشير هذا الحقل إلى ما إذا كان النشاط يمكنه تفعيل ميزة "الرؤية من خلال النظارة" أو إيقافها في الوقت الحالي.

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

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

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

إنشاء ملف glTF

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

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

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

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

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

ضبط SpatialEnvironmentPreference لتطبيقك

تتحكّم السمة preferredSpatialEnvironment في البيئة المكانية المفضّلة للتطبيق. وعند استخدام هذه السمة لضبط إعداد مفضّل، لا يؤدي ذلك إلى تغيير فوري ما لم تكن السمة isPreferredSpatialEnvironmentActive مضبوطة على true. عندما يدخل الجهاز في حالة يمكن فيها تغيير خلفية الواقع الممتد وتتوفّر إمكانية SpatialCapability.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.
}

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

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

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

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

يتم استخدام setPassthroughOpacityPreference لضبط مستوى التعتيم المفضّل في وضع العرض الشفاف في أحد التطبيقات. يضبط هذا الإجراء الإعداد المفضّل فقط ولا يؤدي إلى تغيير فوري إلا إذا كانت ميزة SpatialCapability.PASSTHROUGH_CONTROL متاحة. عندما يدخل الجهاز في حالة يمكن فيها تغيير مستوى تعتيم وضع "الرؤية من خلال النظارة"، وتكون إمكانية SpatialCapability.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.
}

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

For more advanced use cases where you need finer control over the passthrough opacity, you can incorporate SpatialCapability checks and add a listener using addOnPassthroughOpacityChangedListener to determine when you want to set the passthrough opacity preference.

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

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

تحديد مستوى تعتيم ميزة "الرؤية من خلال النظارة" الحالي

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

انظر أيضًا