تخصيص النماذج الثلاثية الأبعاد في تطبيقك

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

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

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

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

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

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

الكائنات الثلاثية الأبعاد في Android XR

تتوافق حزمة تطوير البرامج (SDK) الخاصة بـ Jetpack XR مع معيار glTF 2.0 المفتوح الذي وضعته مجموعة Khronos للتصاميم الثلاثية الأبعاد، كما تعرض هذه العناصر باستخدام تقنيات العرض المستند إلى الفيزياء (PBR) المحدّدة في معيار glTF 2.0 (بالإضافة إلى الإضافات المتوافقة). ‫glTF (تنسيق نقل مكتبة الرسومات) هو تنسيق ملفات عادي لنقل وتحميل المشاهد والتصاميم الثلاثية الأبعاد. يتألف نموذج glTF من بنية هرمية من المكوّنات الداخلية.

في ما يلي المكوّنات الرئيسية التي يجب فهمها:

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

في Jetpack Compose for XR، يمكنك عرض هذه الملفات باستخدام SpatialGltfModel وتتبُّع حالة تحميلها باستخدام SpatialGltfModelState. لمزيد من المعلومات، يُرجى الاطّلاع على إضافة تصاميم ثلاثية الأبعاد إلى تطبيقك.

التحكّم في العُقد: الأوضاع والتدوير

للتلاعب بأجزاء معيّنة من التصميم وتغيير خصائصه، مثل الدوران أو الوضع، عليك طلب بيانات nodes الداخلية لتصميم glTF باستخدام SpatialGltfModelState.

// Retrieve the list of nodes (individual components/meshes) defined within the glTF model.
val entityNodes = modelState.nodes

// Find a specific node by name to apply modifications, such as material overrides.
val node = entityNodes.find { it.name == "node_name" }
SpatialGltfModel.kt

بعد العثور على العقدة الصحيحة، يمكنك ضبط localPose لتغيير موضعها ثلاثي الأبعاد وتدويرها بالنسبة إلى العقدة الأب المباشرة GltfModelNode أو استخدام modelPose لضبط الموضع بالنسبة إلى العقدة الجذر GltfModelEntity. وبالمثل، يمكنك استخدام localScale/modelScale لتغيير حجم النموذج بالنسبة إلى العنصر الرئيسي أو الجذر.

LaunchedEffect(node, degrees) {
    val rotation = Quaternion.fromEulerAngles(degrees, 0f, degrees)
    node?.let {
        it.localPose = Pose(it.localPose.translation, rotation)
    }
}
SpatialGltfModel.kt

تخصيص خصائص المواد في التصميم الثلاثي الأبعاد

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

في Jetpack XR، يتم استخدام الفئتين KhronosPbrMaterial وKhronosUnlitMaterial لإنشاء هذه المواد ومعالجتها. وكما يوحي الاسم، فإنّ KhronosUnlitMaterials لا تضيء ولا تتأثر بإضاءة المشهد. تتيح لك KhronosPbrMaterial تخصيص مجموعة أكبر من الخصائص، مثل لون اللمعان ومدى معدنية أو خشونة العنصر وما إذا كان يصدر ضوءًا.

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

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

بعد ذلك، حدِّد الخصائص التي تريد تعديلها. يستخدم هذا المثال setBaseColorFactor لتغيير اللون الأساسي للشبكة إلى اللون الأرجواني. تتطلّب هذه الطريقة Vector4، حيث تتوافق المكوّنات x, y, z وw مع قيم RGBA (الأحمر والأخضر والأزرق والألفا) على التوالي:

// Maintain a reference to the custom material to avoid re-creating it on every recomposition.
var pbrMaterial by remember { mutableStateOf<KhronosPbrMaterial?>(null) }

// Create and apply the custom material once the session is ready and the target node is available.
LaunchedEffect(node) {
    val material = KhronosPbrMaterial.create(
        session = xrSession,
        alphaMode = AlphaMode.OPAQUE
    ).also {
        pbrMaterial = it
        // Apply a base color factor (RGBA) to change the color of the model.
        it.setBaseColorFactor(
            Vector4(
                x = 0.5f,
                y = 0.0f,
                z = 0.5f,
                w = 1.0f
            )
        )
    }
SpatialGltfModel.kt

تحميل مواد مخصّصة للتصميم الثلاثي الأبعاد

Texture هي مادة عرض مصوّرة يمكنك تطبيقها على سطح تصميم ثلاثي الأبعاد لتوفير اللون أو التفاصيل أو معلومات أخرى عن السطح. تتيح واجهة برمجة التطبيقات Jetpack XR Texture API تحميل بيانات الصور، مثل ملفات PNG، من مجلد /assets/ في تطبيقك بشكل غير متزامن.

عند تحميل مادة، يمكنك تحديد TextureSampler، ما يتحكّم في طريقة عرض المادة. يحدّد أداة أخذ العيّنات خصائص الفلترة (عندما يظهر النسيج أصغر أو أكبر من حجمه الأصلي) وأوضاع الالتفاف (للتعامل مع الإحداثيات خارج النطاق [0, 1] العادي). يجب تعيين Texture إلى KhronosPbrMaterial ليكون له تأثير مرئي على تصميم ثلاثي الأبعاد.

لتحميل مادة مخصّصة، عليك أولاً حفظ ملف الصورة في مجلد /assets/. كأفضل ممارسة، ننصحك بإنشاء texturesمجلد فرعي في ذلك المجلد أيضًا.

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

يطبّق هذا المثال نسيجًا مسدودًا ويضبط قوة الانسداد:

LaunchedEffect(node) {
    val material = KhronosPbrMaterial.create(
        session = xrSession,
        alphaMode = AlphaMode.OPAQUE
    ).also {
        pbrMaterial = it

        // Load a texture
        val texture = Texture.create(
            session = xrSession,
            path = Path("textures/texture_name.png")
        )

        // Set the texture and configure occlusion to define how the material surface handles ambient lighting.
        it.setOcclusionTexture(
            texture = texture,
            strength = 1.0f
        )
    }
    node?.setMaterialOverride(
        material = material
    )
}
SpatialGltfModel.kt

تطبيق المواد والأنماط على المجسّمات الثلاثية الأبعاد

لتطبيق المادة أو السطح الجديدَين، عليك تجاهل المادة الحالية لعنصر node معيّن في ملف glTF. يمكنك إجراء ذلك من خلال استدعاء setMaterialOverride:

node?.setMaterialOverride(
    material = material
)
SpatialGltfModel.kt

لإزالة المواد التي تم إنشاؤها حديثًا، استدعِ الدالة clearMaterialOverride على العقدة التي تم استبدالها سابقًا. سيؤدي ذلك إلى إعادة تصميمك الثلاثي الأبعاد إلى حالته التلقائية:

if (removeMaterial) {
    node?.clearMaterialOverride()
}
SpatialGltfModel.kt

تحريك التصاميم الثلاثية الأبعاد

يمكن أن تحتوي التصاميم الثلاثية الأبعاد على صور متحركة مضمّنة. تستخدم الصور المتحركة داخليًا أخذ العيّنات لتحديد توقيت الحركات وقيمها، والقنوات لربط هذه الحركات بالعُقد والشبكات الفردية. تتوافق الصور المتحركة الهيكلية والصور المتحركة الخاصة بالمواد التي تم إنشاؤها باستخدام KHR_animation_pointer إضافة glTF مع حزمة تطوير البرامج (SDK) لمنصة Jetpack XR.

لا يمكن التحكّم في الصور المتحركة إلا باستخدام GltfAnimation في SceneCore مع GltfModelEntity. لإضافة هذا العنصر إلى تصميم Compose for XR، عليك استخدام SceneCoreEntity بدلاً من SpatialGltfModel.

حدِّد اسم المسار المحدّد من قائمة animations في GltfModelEntity. استخدِم GltfAnimationStartOptions للتحكّم في تشغيل الصورة المتحركة. يمكنك اختياريًا تحديد السرعة ووقت البحث وما إذا كان يجب تكرار الصورة المتحركة:

val animation = gltfEntity.getAnimations().find { it.name == "Walk" }
animation?.start(GltfAnimationStartOptions(shouldLoop = true))
GltfEntity.kt

‫glTF وشعار glTF هما علامتان تجاريتان مسجّلتان تملكهما شركة Khronos Group Inc.