Menambahkan subruang ke aplikasi

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 →

Subruang adalah partisi ruang 3D dalam aplikasi Anda tempat Anda dapat menempatkan model 3D, membangun tata letak 3D, dan menambahkan kedalaman pada konten 2D. Subruang dirender hanya jika spasialisasi diaktifkan. Di Ruang Rumah atau di perangkat non-XR, kode apa pun dalam subruang tersebut akan diabaikan.

Anda dapat menggunakan composable subruang seperti SpatialPanel, SpatialRow, dan SpatialColumn untuk membuat tata letak dan menempatkan konten 2D di ruang 3D. Untuk menempatkan konten 3D, gunakan Composable Subspace yang sesuai seperti SceneCoreEntity untuk model 3D dan SpatialExternalSurface untuk gambar stereo. Beberapa komponen XR seperti Orbiter atau SpatialDialog adalah composable 2D standar yang dapat digunakan di mana saja dalam hierarki UI 2D Anda, tetapi SubspaceComposable harus dipanggil di subruang aplikasi Anda. Untuk melakukannya, gunakan composable subruang Subspace.

Tentang hierarki subruang

Subspace tingkat teratas adalah subruang terluar yang dipanggil oleh aplikasi Anda. Setiap panggilan ke Subspace membuat hierarki UI Spasial baru yang independen. Objek ini tidak mewarisi posisi, orientasi, atau skala spasial dari Subspace induk tempat objek ini bertingkat.

Untuk membuat Subspace tersemat atau bertingkat dalam SpatialPanel, Orbiter, SpatialPopup, atau komponen lain, gunakan PlanarEmbeddedSubspace.

PlanarEmbeddedSubspace memiliki dua perbedaan utama dari Subspace:

  • Mereka berpartisipasi dalam tata letak 2D tempat mereka dipanggil. Artinya, tinggi dan lebar subruang akan dibatasi oleh tinggi dan lebar tata letak induk 2D-nya.
  • Mereka berperilaku sebagai turunan dari entity tempat mereka dipanggil. Artinya, jika Anda memanggil composable subruang yang bertingkat di dalam SpatialPanel, subruang tersebut adalah turunan dari SpatialPanel tempat ia dipanggil.

Perilaku PlanarEmbeddedSubspace ini memungkinkan kemampuan seperti:

  • Memindahkan turunan dengan entity induk
  • Mengimbangi lokasi turunan menggunakan offset SubspaceModifier
  • Menampilkan objek 3D yang melayang di atas UI 2D Anda dan cocok dengan tinggi dan lebar ruang yang sesuai dalam tata letak 2D

Menyesuaikan tata letak untuk subruang

Di Android XR, tata letak aplikasi Anda terikat ke VolumeConstraints dari Subspace dalam Mode Ruang Penuh secara default. Oleh karena itu, Anda harus mempertimbangkan jumlah ruang yang terlihat yang tersedia bagi pengguna dan menyesuaikan tata letak Anda. recommendedContentBoxInFullSpace memberikan dimensi spesifik untuk kotak pembatas di dalam ActivitySpace sehingga konten dapat ditempatkan dalam bidang pandang pengguna.

Konten utama aplikasi Anda harus berada di dalam kotak ini. Jika Anda memiliki konten yang harus melebihi batas yang direkomendasikan, pertimbangkan tata letak yang mendorong pengguna untuk menjelajahi ruang dengan menggerakkan kepala mereka. Batasan default recommendedContentBoxInFullSpace dapat diganti dengan menerapkan pengubah berbasis ukuran kustom seperti SubspaceModifier.requiredSizeIn. Untuk perilaku tanpa batas, tetapkan allowUnboundedSubspace = true.

Panggil recommendedContentBoxInFullSpace menggunakan Sesi saat ini untuk mendapatkan dimensi tertentu ini sesuai kebutuhan. Lihat contoh berikut:

val session = LocalSession.current
session?.scene?.activitySpace?.recommendedContentBoxInFullSpace
Subspace.kt

Menambahkan subruang ke aplikasi Anda

Contoh kode berikut menunjukkan cara menambahkan Subspace dan PlanarEmbeddedSubspace ke aplikasi Anda:

setContent {
    // This is a top-level subspace
    Subspace {
        SpatialPanel {
            MyComposable()
        }
    }
}
Subspace.kt

@Composable
private fun MyComposable() {
    Row {
        PrimaryPane()
        SecondaryPane()
    }
}

@Composable
private fun PrimaryPane() {
    // This is an embedded subspace, because PrimaryPane is in a SpatialPanel
    // and that SpatialPanel is in the top-level Subspace
    PlanarEmbeddedSubspace {
        SpatialPanel {}
    }
}
Subspace.kt

Lihat dokumentasi referensi lengkap tentang Subspace dan PlanarEmbeddedSubspace untuk mengetahui detail selengkapnya.