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 hanya dirender jika spasialisasi diaktifkan. Di Ruang Beranda atau di perangkat non-XR, kode apa pun dalam subruang tersebut akan diabaikan.

Untuk mengetahui informasi selengkapnya tentang tata letak spasial dan komponen yang dapat Anda gunakan dalam subruang, lihat komponen spasial.

Tentang hierarki subruang

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

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

PlanarEmbeddedSubspace memiliki dua perbedaan utama dari Subspace:

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

Perilaku PlanarEmbeddedSubspace ini memungkinkan kemampuan seperti:

  • Memindahkan turunan dengan parent entity
  • Mengimbangi lokasi turunan menggunakan offset SubspaceModifier
  • Menampilkan objek 3D yang melayang di atas UI 2D dan sesuai 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 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 ruang pandang pengguna.

Konten utama aplikasi Anda harus sesuai dengan 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 spesifik ini sesuai kebutuhan. Lihat contoh berikut:

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

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

@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 {}
    }
}

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