Menyesuaikan model 3D di aplikasi Anda

Perangkat XR yang kompatibel
Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.
Mempelajari jenis perangkat XR →
Headset XR
Kacamata XR Berkabel
Mempelajari jenis perangkat XR →

Sebelum menyesuaikan model 3D, Anda harus menambahkannya ke aplikasi terlebih dahulu. Setelah menambahkan model 3D ke aplikasi, Anda dapat meningkatkan pengalaman visual dan interaktif dengan menyesuaikan tampilan dan pergerakan model 3D.

Misalnya, Anda dapat memutar dan mengontrol animasi glTF tersemat, mengakses dan memindahkan node yang membentuk model, atau bahkan memuat tekstur kustom dan menentukan properti materi untuk menggantikan mesh internal. Kemampuan ini memungkinkan Anda mengubah tampilan dan perilaku objek secara dinamis saat runtime.

Objek 3D di Android XR

Jetpack XR SDK mendukung standar terbuka glTF 2.0 dari Khronos Group untuk model 3D dan merender objek ini dengan teknik physically based rendering (PBR) yang ditentukan dalam standar glTF 2.0 (bersama dengan ekstensi yang didukung). glTF (Graphics Library Transmission Format) adalah format file standar untuk mengirim dan memuat adegan dan model 3D. Model glTF terdiri dari struktur hierarkis komponen internal.

Berikut komponen utama yang perlu dipahami:

  • Node: Node ini menentukan struktur dan hierarki model. Setiap node dapat memiliki posisi, rotasi, dan skala sendiri.
  • Mesh: Geometri 3D struktural yang membentuk bentuk objek 3D.
  • Material: Menentukan tampilan visual mesh, seperti warna, kekasaran, atau reaksinya terhadap pencahayaan.
  • Tekstur: Aset gambar, seperti file PNG, yang dapat Anda terapkan ke permukaan model 3D untuk membuat pola, warna, detail, atau efek visual lainnya yang disesuaikan.

Di Jetpack Compose untuk XR, Anda merender file ini menggunakan SpatialGltfModel dan melacak status pemuatannya menggunakan SpatialGltfModelState. Untuk mengetahui informasi selengkapnya, lihat Menambahkan model 3D ke aplikasi Anda.

Memanipulasi Node: Pose dan Rotasi

Untuk memanipulasi bagian tertentu dari model dan mengubah propertinya seperti rotasi atau pose, Anda harus membuat kueri nodes internal model glTF menggunakan 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" }

Setelah menemukan node yang benar, Anda dapat menyetel localPose untuk mengubah posisi dan rotasi 3D-nya relatif terhadap induk langsung GltfModelNode atau menggunakan modelPose untuk menyetel posisi relatif terhadap root GltfModelEntity. Demikian pula, Anda dapat menggunakan localScale/modelScale untuk mengubah skala model relatif terhadap induk atau root-nya.

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

Menyesuaikan properti materi model 3D

Anda dapat menyesuaikan atribut materi selama runtime untuk mengubah tampilan objek secara dinamis berdasarkan input pengguna atau status aplikasi saat ini.

Di Jetpack XR, class KhronosPbrMaterial dan KhronosUnlitMaterial digunakan untuk membuat dan memanipulasi materi ini. Seperti namanya, KhronosUnlitMaterials tidak diterangi dan tidak terpengaruh oleh pencahayaan adegan. KhronosPbrMaterial memungkinkan Anda menyesuaikan berbagai properti, seperti warna kilau, seberapa metalik atau kasar suatu objek, dan apakah objek tersebut memancarkan cahaya.

Untuk mengetahui informasi selengkapnya tentang setiap properti yang didukung dan parameter yang dapat disesuaikan di Android XR, lihat dokumentasi referensi kami. Untuk lebih memahami properti ini, lihat glosarium Khronos.

Gambar 1. Contoh mengubah warna dasar pada model 3D.

Untuk menyesuaikan properti materi model 3D, pertama-tama Anda akan membuat materi baru menggunakan KhronosPbrMaterial. Anda harus menyetel AlphaMode yang sesuai untuk tampilan visual yang ingin Anda capai:

Selanjutnya, tentukan properti yang ingin Anda ubah. Contoh ini menggunakan setBaseColorFactor untuk mengubah warna dasar mesh menjadi ungu. Metode ini memerlukan Vector4, dengan komponen x, y, z, dan w masing-masing sesuai dengan nilai RGBA (Merah, Hijau, Biru, dan Alfa):

// 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
            )
        )
    }

Memuat tekstur kustom untuk model 3D Anda

Texture adalah aset gambar yang dapat Anda terapkan ke permukaan model 3D untuk memberikan warna, detail, atau informasi permukaan lainnya. Jetpack XR Texture API memungkinkan Anda memuat data gambar, seperti file PNG, dari folder /assets/ aplikasi Anda secara asinkron.

Saat memuat tekstur, Anda dapat menentukan TextureSampler, yang mengontrol cara tekstur dirender. Sampler menentukan properti pemfilteran (saat tekstur tampak lebih kecil atau lebih besar dari ukuran aslinya) dan mode pembungkusan (untuk menangani koordinat di luar rentang [0, 1] standar). Texture harus ditetapkan ke KhronosPbrMaterial agar memiliki efek visual pada model 3D.

Gambar 2. Contoh mengubah tekstur pada model 3D.

Untuk memuat tekstur kustom, pertama-tama Anda harus menyimpan file gambar ke folder /assets/. Sebagai praktik terbaik, sebaiknya Anda membuat subdirektori textures di folder tersebut juga.

Setelah Anda menyimpan file di direktori yang sesuai, buat tekstur dengan API Texture. Di sini juga Anda dapat menerapkan TextureSampler opsional jika diperlukan.

Contoh ini menerapkan tekstur oklusi dan menetapkan kekuatan oklusi:

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
    )
}

Menerapkan material dan tekstur ke objek 3D

Untuk menerapkan materi atau tekstur baru, ganti materi yang ada untuk node tertentu di node glTF Anda. Lakukan hal ini dengan memanggil setMaterialOverride:

node?.setMaterialOverride(
    material = material
)

Untuk menghapus materi yang baru dibuat, panggil clearMaterialOverride di node yang sebelumnya diganti. Tindakan ini akan mengembalikan Model 3D Anda ke status default-nya:

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

Menganimasikan model 3D

Model 3D dapat memiliki animasi tersemat. Secara internal, animasi menggunakan sampler untuk menentukan waktu dan nilai gerakan, serta channel untuk menghubungkan gerakan tersebut ke masing-masing node dan mesh. Animasi kerangka dan animasi material yang dibuat dengan KHR_animation_pointer ekstensi glTF didukung di Jetpack XR SDK.

Animasi hanya dapat dikontrol menggunakan GltfAnimation SceneCore dengan GltfModelEntity. Untuk menambahkan entity ini ke tata letak Compose untuk XR, Anda harus menggunakan SceneCoreEntity, bukan SpatialGltfModel.

Tentukan nama jalur tertentu dari daftar animations di GltfModelEntity Anda. Gunakan GltfAnimationStartOptions untuk mengontrol pemutaran animasi. Secara opsional, Anda dapat menentukan kecepatan, waktu pencarian, dan apakah animasi harus diulang:

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

glTF dan logo glTF adalah merek dagang Khronos Group Inc.