Menambahkan lingkungan spasial 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 →

Di Jetpack XR SDK, lingkungan spasial adalah lingkungan imersif yang dapat Anda tambahkan ke aplikasi untuk menyesuaikan latar belakang tampilan virtual. Lingkungan spasial hanya terlihat saat aplikasi berada dalam Ruang Penuh.

Ringkasan lingkungan spasial

SpatialEnvironment mengelola preferensi lingkungan spasial aplikasi. Ini adalah gabungan dari gambar skybox mandiri dan geometri yang ditentukan glTF. Hanya satu gambar skybox dan satu file geometri glTF yang dapat ditetapkan sekaligus.

Skybox merepresentasikan gambar yang dilihat pengguna di sekitarnya dalam adegan virtual, sehingga menciptakan ilusi lingkungan latar belakang yang jauh, seperti langit, pegunungan, atau pemandangan kota. Pengguna tidak dapat berinteraksi dengan atau mendekati skybox. Jetpack XR SDK mendukung skybox sferis dalam standar OpenEXR. Selain memberikan latar belakang yang imersif untuk aplikasi Anda, skybox EXR juga menyediakan pencahayaan berbasis gambar (IBL) ke model 3D yang dimuat oleh aplikasi Anda. Untuk informasi selengkapnya, lihat panduan untuk bekerja dengan model 3D.

Lingkungan spasial juga dapat menyertakan konten geometri 3D dalam standar glTF. Geometri lingkungan yang dimuat dengan cara ini akan otomatis diselaraskan dengan lantai dunia nyata. Geometri lingkungan adalah cara yang bagus untuk menambahkan realisme ke lingkungan Anda melalui elemen latar depan dan latar tengah yang menyatu ke dalam skybox dengan efek paralaks.

Dalam panduan desain untuk lingkungan spasial, Anda dapat mempelajari berbagai jenis aset yang dapat digunakan untuk membuat lingkungan spasial dan cara membuat lingkungan spasial yang aman dan menyenangkan.

Anda dapat menyetel lingkungan spasial aplikasi ke salah satu dari tiga konfigurasi berikut:

  • Kombinasi gambar skybox dan geometri glTF.
  • Permukaan passthrough, tempat lingkungan yang ditampilkan adalah feed langsung dari kamera perangkat yang menghadap ke luar. Pada opasitas penuh, permukaan passthrough ini sepenuhnya menutupi skybox dan geometri.
  • Konfigurasi campuran, dengan permukaan passthrough tidak dalam opasitas penuh, dan juga tidak dalam opasitas nol. Dalam hal ini, permukaan passthrough menjadi semi-transparan dan berbaur alfa dengan skybox dan geometri di belakangnya.

Kemampuan spasial untuk lingkungan spasial

Mengimpor dan memuat resource lingkungan spasial

Resource glTF dan EXR untuk lingkungan spasial dimuat secara asinkron menggunakan class Session.

Membuat aset glTF

Resource glTF dapat dibuat sebagai GltfModel, dengan glTF dimuat dari file lokal. GltfModel dapat digunakan sebagai bagian dari lingkungan aplikasi spasial.

val environmentGeometry = GltfModel.create(session, Paths.get("DayGeometry.glb"))

Membuat resource pencahayaan berbasis gambar

Resource pencahayaan berbasis gambar dapat dibuat sebagai ImageBasedLightingAsset, dengan pencahayaan yang dimuat dari file lokal. ImageBasedLightingAsset dapat digunakan dengan cmgen untuk membuat file ZIP IBL untuk skybox Anda. Lihat panduan kami tentang mengoptimalkan aset lingkungan untuk mengetahui detail selengkapnya.

val lightingForSkybox = ImageBasedLightingAsset.createFromZip(session, Paths.get("BlueSkyboxLighting.zip"))

Menetapkan SpatialEnvironmentPreference untuk aplikasi Anda

Properti preferredSpatialEnvironment mengontrol lingkungan spasial pilihan untuk aplikasi. Jika properti ini digunakan untuk menetapkan preferensi, properti ini tidak akan menyebabkan perubahan langsung, kecuali jika isPreferredSpatialEnvironmentActive sudah true. Setelah perangkat memasuki status tempat latar belakang XR dapat diubah dan kemampuan SpatialCapability.APP_ENVIRONMENT tersedia, lingkungan spasial pilihan untuk aplikasi akan otomatis ditampilkan.

Menetapkan preferensi ke null akan menonaktifkan lingkungan spasial pilihan untuk aplikasi, yang berarti lingkungan sistem default akan ditampilkan.

Jika SpatialEnvironmentPreference yang diberikan tidak null, tetapi semua propertinya null, lingkungan spasial akan terdiri dari skybox hitam dan tanpa geometri.

Untuk mendapatkan notifikasi perubahan status SpatialEnvironment, gunakan addOnSpatialEnvironmentChangedListener.

Penggunaan dasar

Cuplikan kode ini membuat resource geometri lingkungan dan skybox, lalu menetapkan preferensi lingkungan spasial. Preferensi ini akan diingat, dan akan diterapkan saat aplikasi memiliki kemampuan untuk menyetel lingkungannya sendiri.

val spatialEnvironmentPreference =
    SpatialEnvironment.SpatialEnvironmentPreference(lightingForSkybox, environmentGeometry)
session.scene.spatialEnvironment.preferredSpatialEnvironment = spatialEnvironmentPreference
if (session.scene.spatialEnvironment.isPreferredSpatialEnvironmentActive) {
    // The environment was successfully updated and is now visible, and any listeners
    // specified using addOnSpatialEnvironmentChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the SPATIAL_CAPABILITY_APP_ENVIRONMENT capability.
    // Then, any listeners specified using addOnSpatialEnvironmentChangedListener
    // will be notified.
}

Penggunaan lanjutan

Untuk kasus penggunaan yang lebih lanjut, saat Anda memerlukan kontrol yang lebih mendetail atas lingkungan, Anda dapat menggabungkan pemeriksaan SpatialCapability dan menerapkan addOnSpatialEnvironmentChangedListener untuk menentukan kapan Anda ingin menetapkan preferensi lingkungan spasial.

Menetapkan PassthroughOpacityPreference untuk lingkungan spasial aplikasi Anda

Salah satu komponen latar belakang virtual imersif aplikasi adalah platform passthrough. Dalam hal ini, latar belakang yang ditampilkan adalah feed live dari kamera perangkat yang menghadap ke luar.

setPassthroughOpacityPreference digunakan untuk menetapkan opasitas passthrough pilihan untuk aplikasi. Metode ini hanya menetapkan preferensi dan tidak menyebabkan perubahan langsung kecuali jika kemampuan SpatialCapability.PASSTHROUGH_CONTROL tersedia. Setelah perangkat memasuki status yang memungkinkan perubahan opasitas passthrough, dan kemampuan SpatialCapability.PASSTHROUGH_CONTROL tersedia, opasitas passthrough yang diinginkan untuk aplikasi akan otomatis diterapkan.

Nilai untuk preferensi opasitas passthrough berkisar dari 0.0f (opasitas nol, dengan permukaan passthrough tidak terlihat) hingga 1.0f (opasitas penuh, dengan permukaan passthrough menyembunyikan lingkungan spasial). Parameter setPassthroughOpacityPreference adalah float nullable. Menetapkan nilai ke null menunjukkan bahwa aplikasi tidak memiliki preferensi opasitas passthrough, dan akan mengembalikan kontrol passthrough ke sistem.

Penggunaan dasar

Cuplikan kode ini menetapkan preferensi opasitas passthrough. Preferensi ini akan diingat, dan akan diterapkan saat aplikasi memiliki kemampuan untuk menyetel opasitas passthrough.

session.scene.spatialEnvironment.preferredPassthroughOpacity = 1.0f
if (session.scene.spatialEnvironment.currentPassthroughOpacity == 1.0f) {
    // The passthrough opacity request succeeded and should be visible now, and any listeners
    // specified using addOnPassthroughOpacityChangedListener will be notified.
} else {
    // The passthrough opacity preference was successfully set, but not
    // immediately visible. The passthrough opacity change will be applied
    // when the activity has the
    // SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL capability.
    // Then, any listeners specified using addOnPassthroughOpacityChangedListener
    // will be notified.
}

Penggunaan lanjutan

Untuk kasus penggunaan lanjutan yang memerlukan kontrol lebih baik atas opasitas passthrough, Anda dapat menggabungkan pemeriksaan SpatialCapability dan menambahkan pemroses menggunakan addOnPassthroughOpacityChangedListener untuk menentukan kapan Anda ingin menetapkan preferensi opasitas passthrough.

Pengoptimalan aset

Saat membuat aset untuk menetapkan SpatialEnvironment pengguna, pastikan aset Anda mencapai resolusi berkualitas tinggi sekaligus mempertahankan ukuran file yang wajar. Untuk mempelajari lebih lanjut, lihat panduan kami tentang cara mengoptimalkan aset Lingkungan.

Menentukan opasitas passthrough saat ini

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

Lihat juga