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

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

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

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

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

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

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

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

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

ملاحظة: عند ضبط الإعدادات المفضّلة لـ SpatialEnvironment، لا تسري الطرق بالضرورة على الفور. وبدلاً من ذلك، تضبط هذه الطرق إعدادًا مفضّلاً سيتم تطبيقه عندما يدخل الجهاز في حالة يمكن فيها تغيير بيئة التطبيق. في مقتطفات الرموز البرمجية، سترى مستمعين للتعامل مع تغييرات الحالة هذه.

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

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

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

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

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

يتم تحميل موارد glTF وEXR للبيئات المكانية بشكل غير متزامن في فئة Session. يجب تخزين هذه الملفات في مجلد مواد العرض.

إنشاء مورد glTF

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

// assume that session is a Session that has been previously created
val environmentGeometryFuture = session.createGltfResourceAsync("DayGeometry.glb")

val environmentGeometry = environmentGeometryFuture.await()

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

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

// assume that session is a Session that has been previously created
val skyboxExrFuture = session.createExrImageResourceAsync("BlueSkybox.exr")

val skyboxExr = skyboxExrFuture.await()

ضبط SpatialEnvironmentPreference لتطبيقك

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

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

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

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

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

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

// Assume that session is a Session that has been previously created

// Create a GLTFResource
val environmentGeometry = session.createGltfResourceAsync("DayGeometry.glb").await()

// Create an ExrImage for the skybox
val skyboxExr = session.createExrImageResourceAsync("BlueSkybox.exr").await()

val spatialEnvironmentPreference = SpatialEnvironmentPreference(skyboxExr, 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.
}

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

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

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

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

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

تتراوح قيم الإعداد المفضّل لشفافية العبور من 0.0f (شفافية صفرية، حيث لا تكون المساحة الشفافة مرئية) إلى 1.0f (شفافية كاملة، حيث تحجب المساحة الشفافة البيئة المكانية). المَعلمة setPassthroughOpacityPreference هي عدد عائم قابل للحذف. يشير ضبط قيمة على "قيمة فارغة" إلى أنّ التطبيق ليس لديه إعدادات مفضّلة لمعدّل الشفافية للعرض المباشر، و سيعيد التحكّم في العرض المباشر إلى النظام.

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

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

// Assume that session is a Session that has been previously created

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
}

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

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

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

عند إنشاء مواد عرض لإعداد SpatialEnvironment للمستخدمين، عليك التأكّد من أنّ مواد العرض تحقّق درجة دقة عالية مع الحفاظ على حجم ملف معقول. يجب التأكّد من أنّ ملف glb يستخدم mipmaps وملف ‎ktx2 textures. عليك أيضًا الانتباه إلى عدد المضلّعات في ملفات glb، لأنّ عددًا كبيرًا من المضلّعات يمكن أن يؤدي إلى استهلاك طاقة غير ضروري. تأتي معظم حجم الملف لمعظم نُسخ SpatialEnvironment من الصورة المستخدَمة في صندوق السماء. لضمان تحسين صورك، عليك تشغيل مواد العرض من خلال أحد أداة التحسين (مثل ktx).

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

val currentPassthroughOpacity =  session.spatialEnvironment.getCurrentPassthroughOpacity()

انظر أيضًا

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