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 adegan virtual. Lingkungan spasial hanya terlihat saat aplikasi berada di Ruang Penuh.

Ringkasan lingkungan spasial

A SpatialEnvironment digunakan untuk 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 pada satu waktu.

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

Lingkungan spasial juga dapat menyertakan konten geometri 3D dalam standar glTF. Geometri lingkungan yang dimuat dengan cara ini akan otomatis disejajarkan 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 dengan 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 menetapkan lingkungan spasial aplikasi ke salah satu dari tiga konfigurasi berikut:

  • Kombinasi gambar skybox dan geometri glTF.
  • Permukaan passthrough, dengan lingkungan yang ditampilkan adalah feed langsung dari kamera perangkat yang menghadap ke luar. Pada opasitas penuh, permukaan passthrough ini sepenuhnya mengaburkan skybox dan geometri.
  • Konfigurasi campuran, dengan permukaan passthrough tidak pada opasitas penuh, juga tidak pada opasitas nol. Dalam hal ini, permukaan passthrough menjadi semi-transparan dan alpha menyatu 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 dengan menggunakan class Session.

Membuat resource 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 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 saat latar belakang XR dapat diubah dan kemampuan SpatialCapabilities.SPATIAL_CAPABILITY_APP_ENVIRONMENTtersedia, 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 tentang perubahan status SpatialEnvironment, gunakan addOnSpatialEnvironmentChangedListener.

Penggunaan dasar

Cuplikan kode ini membuat geometri lingkungan dan resource skybox, lalu menetapkan preferensi lingkungan spasial. Preferensi ini akan diingat, dan akan diterapkan saat aplikasi memiliki kemampuan untuk menetapkan 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 canggih saat Anda memerlukan kontrol yang lebih baik atas lingkungan, Anda dapat menggabungkan SpatialCapabilities pemeriksaan 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 permukaan 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 SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL tersedia. Setelah perangkat memasuki status saat opasitas passthrough dapat diubah, dan kemampuan SpatialCapabilities.SPATIAL_CAPABILITY_PASSTHROUGH_CONTROL tersedia, opasitas passthrough pilihan 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 yang dapat di-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 menetapkan 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 yang lebih canggih saat Anda memerlukan kontrol yang lebih baik atas opasitas passthrough, Anda dapat menggabungkan pemeriksaan SpatialCapabilities 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 mengoptimalkan aset Lingkungan.

Menentukan opasitas passthrough saat ini

val currentPassthroughOpacity = session.scene.spatialEnvironment.currentPassthroughOpacity

Lihat juga