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 saat spasialisasi diaktifkan. Di Ruang Utama 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 Subruang 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 Subspace composable subruang.

Tentang hierarki subruang

Subspace tingkat atas adalah subruang terluar yang dipanggil oleh aplikasi Anda. Setiap panggilan ke Subspace akan membuat hierarki UI Spasial baru yang independen. Hierarki ini tidak mewarisi posisi spasial, orientasi, atau skala Subspace induk tempat hierarki tersebut berada.

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

PlanarEmbeddedSubspace memiliki dua perbedaan utama dari Subspace:

  • Keduanya berpartisipasi dalam tata letak 2D tempat keduanya dipanggil. Artinya, tinggi dan lebar subruang akan dibatasi oleh tinggi dan lebar tata letak induk 2D-nya.
  • Keduanya berperilaku sebagai turunan dari entity tempat keduanya dipanggil. Artinya, jika Anda memanggil composable subruang yang berada di dalam SpatialPanel, subruang tersebut adalah turunan dari SpatialPanel tempat subruang tersebut 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 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 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. 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.