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

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

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

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

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

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

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

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

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

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

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

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

• مزيج من صورة skybox وهندسة glTF
• سطح العرض المباشر، حيث تكون البيئة المعروضة عبارة عن خلاصة مباشرة من الكاميرات الخارجية للجهاز عند مستوى الشفافية الكامل، يحجب سطح العرض المباشر هذا skybox والهندسة تمامًا.
• إعداد مختلط، حيث لا يكون سطح العرض المباشر شفافًا تمامًا أو معتمًا تمامًا في هذه الحالة، يصبح سطح العرض المباشر شبه شفاف ويمتزج مع 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

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

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

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

ضبط SpatialEnvironmentPreference لتطبيقك

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

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

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

لتلقّي إشعارات بشأن التغييرات في حالة 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 هي قيمة float تقبل القيم الخالية. يشير ضبط القيمة على 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

انظر أيضًا

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