Membuat, mengontrol, dan mengelola entity

Jetpack XR SDK memungkinkan Anda menggunakan Jetpack SceneCore untuk membuat, mengontrol, dan mengelola instance Entity seperti model 3D, video stereoskopik, dan PanelEntity menggunakan Jetpack SceneCore.

Jetpack SceneCore mengadopsi dua pola arsitektur umum untuk mendukung pengembangan 3D: grafik tampilan dan sistem komponen entitas (ECS).

Menggunakan grafik tampilan untuk membuat dan mengontrol entity

Untuk membuat dan mengontrol objek dalam ruang 3D, Anda harus menggunakan Session API Jetpack SceneCore untuk mendapatkan akses ke grafik tampilan. Grafik tampilan selaras dengan dunia nyata pengguna dan memungkinkan Anda mengatur entitas 3D seperti panel dan model 3D ke dalam struktur hierarkis, serta menyimpan status entitas tersebut.

Setelah mendapatkan akses ke grafik tampilan, Anda dapat menggunakan API di Jetpack Compose untuk XR guna membuat UI spasial (misalnya, SpatialPanel dan Orbiter) dalam grafik tampilan. Untuk konten 3D seperti model 3D, Anda dapat mengakses Sesi secara langsung. Untuk mempelajari lebih lanjut, lihat Tentang ActivitySpace di halaman ini.

Sistem komponen entity

Sistem komponen entitas mengikuti prinsip komposisi atas pewarisan. Anda dapat memperluas perilaku entity dengan melampirkan komponen penentu perilaku, yang memungkinkan Anda menerapkan perilaku yang sama ke berbagai jenis entity. Untuk informasi selengkapnya, lihat Menambahkan perilaku umum ke entity di halaman ini.

Tentang ActivitySpace

Setiap Session memiliki ActivitySpace yang otomatis dibuat dengan Session. ActivitySpace adalah Entity level teratas dalam grafik tampilan.

ActivitySpace mewakili ruang 3 dimensi dengan sistem koordinat kanan (sumbu x mengarah ke kanan, sumbu y mengarah ke atas, dan sumbu z kembali relatif terhadap asal) dan dengan meter untuk unit yang cocok dengan dunia nyata. Asal untuk ActivitySpace agak arbitrer (karena pengguna dapat mereset posisi ActivitySpace dalam dunia nyata), oleh karena itu sebaiknya posisikan konten secara relatif terhadap satu sama lain, bukan relatif terhadap asal.

Menggunakan Entity

Entitas adalah inti dari SceneCore. Sebagian besar hal yang dilihat dan berinteraksi dengan pengguna adalah entitas yang mewakili panel, model 3D, dan lainnya.

Karena ActivitySpace adalah node level teratas dari grafik tampilan, secara default, semua entity baru ditempatkan langsung ke dalam ActivitySpace. Anda dapat memindahkan entitas di sepanjang grafik tampilan dengan memanggil setParent atau addChild.

Entitas memiliki beberapa perilaku default untuk hal-hal yang bersifat universal bagi semua entitas, seperti mengubah posisi, rotasi, atau visibilitas. Subclass Entity tertentu, seperti GltfEntity, memiliki perilaku tambahan yang mendukung subclass.

Memanipulasi Entity

Saat Anda membuat perubahan pada properti Entity yang termasuk dalam class Entity dasar, perubahan tersebut akan diterapkan secara berurutan ke semua turunannya. Misalnya, menyesuaikan Pose dari Entity induk akan menyebabkan semua turunannya memiliki penyesuaian yang sama. Membuat perubahan pada Entity turunan tidak memengaruhi induknya.

Pose mewakili lokasi dan rotasi Entitas dalam ruang 3D. Lokasi adalah Vector3 yang terdiri dari posisi numerik x, y, z. Rotasi direpresentasikan oleh Quaternion. Posisi Entity selalu relatif terhadap entity induknya. Dengan kata lain, Entity yang posisinya adalah (0, 0, 0) akan ditempatkan di asal entity induknya.

//place the entity forward 2 meters
val modelPosition = Vector3(0f, 0f, -2f)
//rotate the entity by 180 degrees on the up axis (upside-down)
val newOrientation = Quaternion.fromEulerAngles(0f, 0f, 180f)
//update the position and rotation on the entity
entity.setPose(Pose(newPosition, newOrientation))

Penting: Saat membahas lokasi Entity, ingat bahwa Entity dapat berada di titik tertentu dalam Scene Graph dan juga memiliki posisi di ruang 3D.

Untuk mengubah visibilitas Entity, gunakan setHidden.

//hide the entity
entity.setHidden(true)

Untuk mengubah ukuran Entity sekaligus mempertahankan bentuk keseluruhannya, gunakan setScale.

//double the size of the entity
entity.setScale(2f)

Perhatian: Skala Entity memengaruhi unit sistem koordinatnya. Misalnya, mengubah skala menjadi 2, membuat setiap unit dalam entitas ini tidak lagi mewakili 1 meter di dunia nyata, tetapi mewakili 2 meter di dunia nyata. Hal ini juga akan diterapkan ke turunan entity.

Menambahkan perilaku umum ke entitas

Anda dapat menggunakan komponen berikut untuk menambahkan perilaku umum ke entity:

• MovableComponent: Memungkinkan pengguna memindahkan entity
• ResizableComponent: Memungkinkan pengguna mengubah ukuran entitas dengan pola UI yang konsisten
• InteractableComponent: Memungkinkan Anda merekam peristiwa input untuk interaksi kustom

Pembuatan instance komponen harus dilakukan melalui metode pembuatan yang sesuai di class Session. Misalnya, untuk membuat ResizableComponent, panggil session.createResizableComponent().

Pratinjau: Saat ini, dengan pengecualian InteractableComponent, yang dapat digunakan di GltfEntity, komponen hanya dapat dilampirkan ke PanelEntity atau subclass-nya.

Untuk menambahkan perilaku komponen tertentu ke Entity, gunakan metode addComponent().

Menggunakan MovableComponent untuk membuat Entity dapat dipindahkan oleh pengguna

MovableComponent memungkinkan Entity dipindahkan oleh pengguna. Anda juga dapat menentukan apakah entity dapat ditautkan ke jenis permukaan seperti permukaan horizontal atau vertikal, atau permukaan semantik tertentu seperti meja, dinding, atau langit-langit. Untuk menentukan opsi anchor, tentukan kumpulan AnchorPlacement saat membuat MovableComponent.

Berikut adalah contoh entitas yang dapat dipindahkan dan ditambatkan ke permukaan vertikal apa pun dan hanya permukaan horizontal lantai dan langit-langit.

val anchorPlacement = AnchorPlacement.createForPlanes(
    planeTypeFilter = setOf(PlaneSemantic.FLOOR, PlaneSemantic.TABLE),
    planeSemanticFilter = setOf(PlaneType.VERTICAL))

val movableComponent = xrSession.createMovableComponent(
    systemMovable = false,
    scaleInZ = false,
    anchorPlacement = setOf(anchorPlacement)
)
entity.addComponent(movableComponent)

Catatan: Jika membuat UI dengan compose, Anda dapat memilih untuk menggunakan pengubah subspace yang dapat dipindahkan untuk mengaktifkan gerakan panel.

Menggunakan ResizableComponent untuk membuat Entity yang dapat diubah ukurannya oleh pengguna

ResizableComponent memungkinkan pengguna mengubah ukuran Entity. ResizableComponent menyertakan isyarat interaksi visual yang mengundang pengguna untuk mengubah ukuran Entity. Saat membuat ResizeableComponent, Anda dapat menentukan ukuran minimum atau maksimum (dalam meter). Anda juga memiliki opsi untuk menentukan rasio aspek tetap saat mengubah ukuran sehingga lebar dan tinggi mengubah ukuran secara proporsional satu sama lain.

Berikut adalah contoh penggunaan ResizableComponent dengan rasio aspek tetap:

val resizableComponent = xrSession.createResizableComponent()
resizableComponent.minimumSize = Dimensions(177f, 100f, 1f )
resizableComponent.fixedAspectRatio = 16f / 9f //Specify a 16:9 aspect ratio
entity.addComponent(resizableComponent)

Catatan: Jika membuat UI dengan compose, Anda dapat memilih untuk menggunakan pengubah subspace yang dapat diubah ukurannya untuk mengaktifkan pengubahan ukuran panel.

Menggunakan InteractableComponent untuk menangkap peristiwa input pengguna

InteractableComponent memungkinkan Anda merekam peristiwa input dari pengguna, seperti saat pengguna berinteraksi atau mengarahkan kursor ke Entity. Saat membuat InteractableComponent, Anda harus menentukan InputEventListener untuk menerima peristiwa input. Saat pengguna melakukan tindakan input, metode onInputEvent akan dipanggil dengan informasi input tertentu yang diberikan dalam parameter InputEvent.

• InputEvent.action menentukan jenis input seperti mengarahkan kursor atau mengetuk entity
• InputEvent.source menentukan asal input seperti input tangan atau pengontrol
• InputEvent.pointerType menentukan apakah input berasal dari tangan kanan atau kiri

Untuk mengetahui daftar lengkap semua konstanta InputEvent, lihat dokumentasi referensi.

Cuplikan kode berikut menunjukkan contoh penggunaan InteractableComponent untuk meningkatkan ukuran entity dengan tangan kanan dan mengurangi dengan tangan kiri.

private val executor by lazy { Executors.newSingleThreadExecutor() }
val interactableComponent = xrSession.createInteractableComponent(executor) {
    //when the user disengages with the entity with their hands
    if (it.source == InputEvent.SOURCE_HANDS && it.action == InputEvent.ACTION_UP) {
        // increase size with right hand and decrease with left
        if (it.pointerType == InputEvent.POINTER_TYPE_RIGHT){
            entity.setScale(1.5f)
        } else if (it.pointerType == InputEvent.POINTER_TYPE_LEFT){
            entity.setScale(0.5f)
        }
    }
}
entity.addComponent(interactableComponent)