إضافة نماذج ثلاثية الأبعاد إلى تطبيقك

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

عند العمل مع التصاميم الثلاثية الأبعاد، تتوافق حزمة تطوير البرامج (SDK) لـ Jetpack XR مع معيار glTF 2.0 المفتوح. عندما يعرض Android XR التطبيقات التي تم إنشاؤها باستخدام حزمة تطوير البرامج (SDK) لـ Jetpack XR، سيتم عرض النماذج الثلاثية الأبعاد باستخدام تقنيات العرض المستند إلى الخصائص الفيزيائية (PBR) المحدّدة في معيار glTF 2.0 (بالإضافة إلى الإضافات المتوافقة). تتيح معظم أدوات إنشاء المحتوى الرقمي (dcc)، مثل Autodesk Maya وMaxon ZBrush وBlender وSpline، تصدير التصاميم الثلاثية الأبعاد بتنسيق glTF (ملفات .gltf أو .glb).

إذا حدّد المستخدم أو تطبيقك SpatialEnvironment skybox، ستتم إضاءة النماذج الثلاثية الأبعاد باستخدام معلومات الإضاءة التي يوفّرها skybox البيئة. ستعكس المواد العاكسة واللمعان المرآوي أيضًا مربّع السماء المحيط. إذا تم تفعيل ميزة "الرؤية من خلال النظارة"، ستعتمد الإضاءة والانعكاسات واللمعان على غرفة ساطعة مع ضوء اتجاهي واحد.

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

إضافة ملف glTF إلى مجلد مواد العرض

بعد الحصول على ملف glTF، تتمثّل الخطوة التالية في إضافته إلى مجلّد الموارد في "استوديو Android". ننصحك بإنشاء دليل models لتنظيم أنواع مواد العرض بشكل أفضل.

مثال على إضافة مواد عرض إلى دليل ‎/models

إضافة عنصر ثلاثي الأبعاد باستخدام SpatialGltfModel

يتيح Android XR استخدام تنسيق glTF للتصاميم الثلاثية الأبعاد، والتي يتم حفظها عادةً كملفات .glb. لإضافة هذه العناصر إلى التنسيق، استخدِم SpatialGltfModel. ‫SpatialGltfModel هي دالة مركّبة للمساحة الفرعية تتيح لك إضافة تصاميم ثلاثية الأبعاد بتنسيق glTF إلى التنسيق المكاني. تسهّل واجهة برمجة التطبيقات هذه عملية تحميل مواد العرض وإدارة حالتها.

لعرض نموذج، عليك أولاً تحديد مصدره وحالته باستخدام rememberSpatialGltfModelState. يمكنك تحميل النماذج من مجلد assets في تطبيقك أو من URI أو raw data.

val modelState = rememberSpatialGltfModelState(
    source = SpatialGltfModelSource.fromPath(
        Paths.get("models/model_name.glb")
    )
)

بعد تحديد الحالة، استخدِم الدالة المركّبة SpatialGltfModel لعرضها ضمن مساحة فرعية:

SpatialGltfModel(state = modelState, modifier = SubspaceModifier)

نقاط رئيسية حول الرمز

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

وضع نموذج ثلاثي الأبعاد باستخدام Compose SceneCoreEntity

لوضع نموذج ثلاثي الأبعاد باستخدام SceneCoreEntity، عليك أولاً تحميل glTF في الذاكرة باستخدام GltfModel.create(). يمكنك بعد ذلك وضع نموذج ثلاثي الأبعاد في SceneCoreEntity لربط مكوّنات SceneCore بتنسيقات Compose for XR. يُرجى الرجوع إلى مقالة استخدام SceneCoreEntity لوضع عنصر ثلاثي الأبعاد في التصميم.

وضع نموذج ثلاثي الأبعاد باستخدام Jetpack Scenecore

لتحميل نموذج glTF، استخدِم GltfModel.create().

val gltfModel = GltfModel.create(session, Paths.get("models", "saturn_rings.glb"))

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

أضِف ملف glTF إلى السمة ActivitySpace. يمكنك استدعاء GltfModelEntity.create لإنشاء كيان ووضعه في ActivitySpace. كأفضل ممارسة، يجب التأكّد من أنّ التطبيق في حالة تسمح باستخدام الإمكانات المكانية.

if (session.scene.spatialCapabilities.contains(SpatialCapability.SPATIAL_3D_CONTENT)) {
    val gltfEntity = GltfModelEntity.create(session, gltfModel)
}

من المفترض أن يظهر لك الآن النموذج الثلاثي الأبعاد الذي تم تحميله عند تشغيل تطبيقك.

مثال على التصميم الثلاثي الأبعاد الذي تم تحميله

تحميل تصميم ثلاثي الأبعاد باستخدام Scene Viewer

إذا كنت تبحث عن أبسط طريقة لتحميل نموذج ثلاثي الأبعاد يتضمّن إمكانات تفاعلية أساسية، يمكنك اختيار استخدام Scene Viewer كما تفعل على الأجهزة الجوّالة. يتمثّل الاختلاف الرئيسي بين Scene Viewer على Android XR وعلى الأجهزة الجوّالة في أنّ Scene Viewer لا يتيح سوى مَعلمة معرّف الموارد المنتظم (URI) للملف التي تشير إلى ملف glTF ويتم تجاهل جميع المَعلمات الأخرى.

‫Scene Viewer هو تطبيق منفصل يتم استدعاؤه باستخدام نية ويتم تشغيله في وضع "المساحة الكاملة". نتيجةً لذلك، لن يظهر تطبيقك عند استدعائه، وسيتم التركيز على Scene Viewer. ستتم إعادة ضبط أي بيئات قد تكون غيّرتها على الإعدادات المفضّلة للنظام لدى المستخدم.

في ما يلي مثال على استخدام Intent لعرض ملف glTF في Scene Viewer على Android XR:

val url =
    "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Avocado/glTF/Avocado.gltf"
val sceneViewerIntent = Intent(Intent.ACTION_VIEW)
val intentUri =
    Uri.parse("https://arvr.google.com/scene-viewer/1.2")
        .buildUpon()
        .appendQueryParameter("file", url)
        .build()
sceneViewerIntent.setData(intentUri)
try {
    startActivity(sceneViewerIntent)
} catch (e: ActivityNotFoundException) {
    // There is no activity that could handle the intent.
}

لمزيد من المعلومات حول خيارات التفاعل في Scene Viewer، يُرجى الرجوع إلى مستندات تصميم النماذج الثلاثية الأبعاد.

إضافات glTF

تتيح حزمة تطوير البرامج Jetpack XR SDK العديد من إضافات glTF التي توسّع إمكانات النماذج الثلاثية الأبعاد. تتوفّر هذه الإمكانات من خلال كلّ من GltfModelEntity وScene Viewer.