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

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

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

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

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

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

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

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

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

تحريك النماذج الثلاثية الأبعاد

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

لاستخدام Compose for XR وتشغيل حركة، حدِّد اسم المسار المحدّد من قائمة animations. استخدِم animation.start() لبدء التشغيل. يمكنك اختياريًا تحديد السرعة ووقت البحث وما إذا كان يجب تكرار الحركة باستخدام SpatialGltfModelAnimation:

val animation = modelState.animations.find { it.name == "Walk" }

animation?.animationState?.let { state ->
    LaunchedEffect(state) {
        Log.i("SpatialGltfModelAnimationSample", "Animation State: $state")
    }
}

DisposableEffect(animation) {
    animation?.loop()
    onDispose {
        animation?.stop()
    }
}

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

للتحكّم في أجزاء معيّنة من نموذج وتغيير خصائصه، مثل الدوران أو الوضع، عليك طلب 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" }

بعد العثور على العُقدة الصحيحة، يمكنك ضبط 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)
    }
}

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

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

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

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

الشكل 1. مثال على تغيير الألوان الأساسية في نموذج ثلاثي الأبعاد

لتخصيص خصائص المواد في النموذج الثلاثي الأبعاد، عليك أولاً إنشاء الـ مادة الجديدة باستخدام 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
            )
        )
    }

تحميل الزخارف المخصّصة للنموذج الثلاثي الأبعاد

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

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

الشكل 2. مثال على تغيير الزخرفة في نموذج ثلاثي الأبعاد

لتحميل زخرفة مخصّصة، عليك أولاً حفظ ملف الصورة في مجلد /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
    )
}

تطبيق المواد والزخارف على الكائنات الثلاثية الأبعاد

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

node?.setMaterialOverride(
    material = material
)

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

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

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