Jetpack SceneCore

Referensi API
androidx.xr.scenecore
androidx.xr.scenecore.testing

Buat dan manipulasi grafik tampilan Android XR dengan konten 3D.

Update Terbaru	Rilis Stabil	Kandidat Rilis	Rilis Beta	Rilis Alfa
12 Februari 2025	-	-	-	1.0.0-alpha02

Mendeklarasikan dependensi

Untuk menambahkan dependensi pada XR SceneCore, Anda harus menambahkan repositori Maven Google ke project Anda. Baca repositori Maven Google untuk mengetahui informasi selengkapnya.

Tambahkan dependensi untuk artefak yang diperlukan dalam file build.gradle bagi aplikasi atau modul Anda:

Groovy

dependencies {
    implementation "androidx.xr.scenecore:scenecore:1.0.0-alpha01"
    // Required for Java
    implementation "com.google.guava:listenableFuture:1.0"
    // Required for Kotlin
    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0"

    // Use to write unit tests
    testImplementation "androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha01")
    // Required for Java
    implementation("com.google.guava:listenableFuture:1.0")
    // Required for Kotlin
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-guava:1.9.0")

    // Use to write unit tests
    testImplementation("androidx.xr.scenecore:scenecore-testing:1.0.0-alpha01")
}

Untuk informasi dependensi selengkapnya, lihat Menambahkan dependensi build.

Masukan

Masukan Anda membantu meningkatkan kualitas Jetpack. Beri tahu kami jika Anda menemukan masalah baru atau mempunyai masukan untuk meningkatkan kualitas library ini. Harap periksa masalah yang sudah diketahui dalam library ini sebelum membuat laporan baru. Anda dapat memberikan suara untuk masalah yang sudah diketahui dengan mengklik tombol bintang.

Laporkan masalah baru

Lihat dokumentasi Issue Tracker untuk informasi selengkapnya.

Versi 1.0

Versi 1.0.0-alpha02

12 Februari 2025

androidx.xr.scenecore:scenecore:1.0.0-alpha02 dan androidx.xr.scenecore:scenecore-testing:1.0.0-alpha02 dirilis. Versi 1.0.0-alpha02 berisi commit ini.

Perubahan yang dapat menyebabkan gangguan mendatang yang memengaruhi aplikasi yang di-build sebelum 1.0.0-alpha02

Metode factory telah dipindahkan dari class Session ke metode pendamping pada setiap jenisnya:
- Session.createActivityPanelEntity(Dimensions, String, Activity, Pose) telah dihapus dan diganti dengan ActivityPanelEntity.create(Session, Dimensions, String, Pose)
- Session.createAnchorEntity(Anchor) telah dihapus dan diganti dengan AnchorEntity.create(Session, Anchor)
- Session.createAnchorEntity(Dimensions, Int, Int, Duration) telah dihapus dan diganti dengan AnchorEntity.create(Session, Dimensions, Int, Int, Duration)
- Session.createEntity(String, Pose) telah dihapus dan diganti dengan ContentlessEntity.create(Session, String, Pose)
- Session.createExrImageResource(String) telah dihapus dan diganti dengan ExrImage.create(Session, String)
- Session.createGltfEntity(GltfModel, Pose) telah dihapus dan diganti dengan GltfModelEntity.create(Session, GltfModel, Pose)
- Session.createGltfModelResource(String) telah dihapus dan diganti dengan GltfModel.create(Session, String)
- Session.createInteractableComponent(Executor, InputEventListener) telah dihapus dan diganti dengan InteractableComponent.create(Session, Executor, InputEventListener)
- Session.createMovableComponent(Boolean, Boolean, Set<AnchorPlacement>, Boolean) telah dihapus dan diganti dengan MovableComponent.create(Session, Boolean, Boolean, Set<AnchorPlacement>, Boolean)
- Session.createPanelEntity(View, Dimensions, Dimensions, String, Pose) telah dihapus dan diganti dengan PanelEntity.create(Session, View, Dimensions, Dimensions, String, Pose)
- Session.createResizableComponent(Dimensions, Dimensions) telah dihapus dan diganti dengan ResizableComponent.create(Session, Dimensions, Dimensions)
- Session.createStereoSurfaceEntity(Int, Dimensions, Pose) telah dihapus dan diganti dengan StereoSurface.create(Session, Int, Dimensions, Pose)
Metode berikut yang tidak digunakan lagi telah dihapus:
- Session.canEmbedActivityPanel(Activity) telah dihapus. Sebagai gantinya, gunakan getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
- Session.hasSpatialCapability(Int) telah dihapus. Metode ini telah diganti dengan menggunakan getSpatialCapabilities().hasCapability() sebagai cara yang lebih terkompartemen untuk memeriksa keberadaan kemampuan spasial karena getSpatialCapabilities() menampilkan objek SpatialCapabilities.
- Session.requestFullSpaceMode() telah dihapus dan diganti dengan SpatialEnvironment.requestFullSpaceMode()
- Session.requestHomeSpaceMode() telah dihapus dan diganti dengan SpatialEnvironment.requestHomeSpaceMode()
Session.setFullSpaceMode(Bundle) dan Session.setFullSpaceModeWithEnvironmentInherited(Bundle) telah dipindahkan ke fungsi ekstensi. File developer harus menambahkan impor baru untuk akses:
- import androidx.xr.scenecore.setFullSpaceMode
- import androidx.xr.scenecore.setFullSpaceModeWithEnvironmentInherited
Session.setPreferredAspectRatio(Activity, Float) telah dipindahkan ke fungsi ekstensi. File developer harus menambahkan impor baru untuk akses:
- import androidx.xr.scenecore.setPreferredAspectRatio
Session.getEntitiesOfType(Class<out T>) dan Session.getEntityForRtEntity(RtEntity) telah dipindahkan ke fungsi ekstensi. File developer harus menambahkan impor baru untuk akses:
- import androidx.xr.scenecore.getEntitiesOfType
- import androidx.xr.scenecore.getEntityForRtEntity
Session.unpersistAnchor(Anchor) telah dihapus
Session.createPersistedAnchorEntity(UUID) telah dihapus

Masalah umum

PanelEntity.setCornerRadius() dan ActivityPanelEntity.setCornerRadius() mungkin tidak akan diterapkan hingga panel dipindahkan lagi, hal ini dapat dimitigasi dengan memindahkan panel ke posisinya saat ini
Saat BoundsChanged dipanggil di ActivitySpace, beberapa ActivityPose mungkin belum diperbarui dengan benar. Status ini akan diperbarui pada panggilan OnSpaceUpdated berikutnya pada ActivitySpace

Perubahan perilaku & yang dapat menyebabkan gangguan

PanelEntity dan ActivityPanelEntity akan memiliki radius sudut default 32 dp atau lebih kecil jika panel memiliki lebar atau tinggi yang lebih kecil dari 32 dp

API dan kemampuan baru

Memperkenalkan StereoSurface.CanvasShape, yang memungkinkan pembuatan kanvas Spherical dan Hemispherical untuk merender media imersif.
StereoSurfaceEntity.create() kini menerima parameter CanvasShape. (Parameter ini saat ini diabaikan, tetapi akan digunakan dalam rilis mendatang)
StereoSurfaceEntity.create() tidak lagi menggunakan parameter Dimensions. Aplikasi harus mengontrol ukuran kanvas melalui setelan CanvasShape
StereoSurfaceEntity memiliki anggota CanvasShape yang dapat ditetapkan secara dinamis.
StereoSurfaceEntity.dimensions kini menjadi properti hanya baca; aplikasi harus menetapkan CanvasShape untuk mengubah dimensi.
StereoSurfaceEntity kini memungkinkan StereoMode disetel ulang setelah pembuatan.

Perubahan lainnya

Mengurangi minSDK waktu kompilasi menjadi 24. Semua Jetpack XR API terus memerlukan API 34 saat runtime.
Factory Sesi SceneCore (Session.create) tidak lagi meluncurkan intent untuk mendapatkan izin SCENE_UNDERSTANDING. Sebagai gantinya, aplikasi klien harus meminta izin secara eksplisit dari pengguna, sebelum mencoba membuat anchor. Pembuatan anchor akan gagal jika izin tidak diberikan oleh pengguna.

Perbaikan bug

getActivitySpacePose() telah diperbaiki untuk memperhitungkan skala ActivitySpace dengan menampilkan nilai terjemahan dalam meter yang diskalakan, bukan selalu menampilkan meter yang tidak diskalakan. transformPoseTo kini juga menggunakan unit yang tepat untuk menghitung perubahan koordinat saat ActivitySpace terlibat dalam sumber atau tujuan.
Skybox kini akan disetel ke skybox hitam-hitam setiap kali preferensi skybox null diteruskan menggunakan setSpatialEnvironmentPreference(new SpatialEnvironmentPreference(null, geom)). Untuk kembali ke skybox dan geometri default sistem, gunakan setSpatialEnvironmentPreference(null).

Versi 1.0.0-alpha01

12 Desember 2024

androidx.xr.scenecore:scenecore-* 1.0.0-alpha01 dirilis.

Fitur Rilis Awal Rilis developer awal Jetpack SceneCore, library grafik tampilan 3D untuk membuat dan memanipulasi tampilan dan lingkungan imersif. Library ini memungkinkan Anda menempatkan dan mengatur model 3D dan panel konten secara relatif terhadap satu sama lain dan lingkungan virtual atau dunia nyata Anda.

SpatialEnvironment: Buat pengalaman yang sepenuhnya imersif dengan gambar skybox dan/atau geometri model 3D sebagai latar belakang untuk scene XR lingkungan Anda. Atau, aktifkan passthrough, sehingga tampilan virtual Anda dapat berintegrasi dengan lingkungan dunia nyata pengguna.
PanelEntity: Tambahkan konten 2D ke tampilan 3D dengan menyematkan tata letak dan Aktivitas Android standar ke panel spasial yang dapat mengambang atau ditambatkan ke permukaan dunia nyata.
GltfModelEntity: Menempatkan, menganimasikan, dan berinteraksi dengan model 3D di tampilan Anda. SceneCore mendukung format file glTF untuk memudahkan integrasi dengan model yang ada.
SpatialAudio: Menambahkan sumber audio ambient dan titik ke dalam tampilan 3D untuk suara spasial yang sepenuhnya imersif.
StereoSurfaceEntity: SceneCore mendukung pemilihan mata kiri/kanan untuk konten yang dirender ke Platform Android. Hal ini dapat digunakan untuk merender konten stereoskopik dalam format berdampingan atau atas-bawah, seperti foto stereo, video 3D, atau UI lain yang dirender secara dinamis. Aplikasi harus menggunakan MediaPlayer atau ExoPlayer untuk decoding video.
Sistem Komponen: SceneCore menawarkan sistem komponen yang andal dan fleksibel untuk menambahkan kemampuan ke konten XR Anda, termasuk kemampuan bagi pengguna untuk memindahkan, mengubah ukuran, dan berinteraksi dengan model dan panel.
Anchor: Dengan mengaktifkan passthrough, Anda dapat memasang panel dan model ke permukaan sebenarnya, sehingga pengguna dapat melakukan integrasi konten virtual yang lancar di lingkungan dunia nyata mereka.
Pose Pengguna: Mengakses lokasi pengguna di tampilan virtual, untuk mengorientasikan konten Anda di sekitar posisi pengguna.
SpatialCapabilities: Buat aplikasi yang sepenuhnya adaptif dan memanfaatkan kemampuan spasial jika tersedia, seperti pemosisian 3D konten UI. Tidak hanya itu, aplikasi Anda juga dapat memantau perubahan pada kemampuan saat aplikasi dieksekusi, untuk mengubah pengalaman berdasarkan cara pengguna menggunakan perangkat Android XR mereka.

Masalah Umum

Saat ini, minSDK 30 diperlukan untuk menggunakan Jetpack SceneCore. Sebagai solusi, tambahkan entri manifes <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> berikut agar dapat mem-build dan menjalankan dengan minSDK 23.
Sesi dapat menjadi tidak valid dalam berbagai situasi yang otomatis membuat ulang Aktivitas, termasuk mengubah ukuran panel utama, menghubungkan periferal, dan beralih antara mode terang dan gelap. Jika Anda mengalami masalah pembatalan validasi sesi, solusinya termasuk membuat panel utama tidak dapat diubah ukurannya, menggunakan entity panel dinamis, menonaktifkan pembuatan ulang aktivitas untuk perubahan konfigurasi tertentu, atau menonaktifkan perubahan tema mode terang/gelap.
Komponen yang Dapat Dipindahkan dan Dapat Diubah Ukurannya tidak didukung di GltfEntity.
Entity.getSize() tidak didukung di GltfEntity.
Aplikasi Jetpack XR diperlukan untuk meminta izin android.permission.SCENE_UNDERSTANDING di AndroidManifest.
Pembuatan sesi hanya didukung di perangkat Android XR. Saat ini, jika Anda membuat Sesi dan mencoba menggunakannya di perangkat non-Android XR, Anda akan mendapatkan RuntimeException.
Menetapkan skybox ke null melalui `SpatialEnvironment.setSpatialEnvironmentPreference() tidak menghasilkan skybox hitam solid seperti yang didokumentasikan. Hal ini dapat menyebabkan skybox default sistem atau tidak ada perubahan pada skybox saat ini.
Klien SceneCore harus menambahkan implementation(“com.google.guava:listenablefuture-1.0”) ke konfigurasi Gradle untuk dependensi aplikasi mereka. Dalam rilis mendatang, scenecore akan menyertakan library ini sebagai dependensi api sehingga klien tidak perlu mendeklarasikannya secara eksplisit.
SceneCore salah menyertakan com.google.guava:guava-31.1-android dan com.google.protobuf:protobuf-javalite sebagai dependensi transitif. Jika hal ini menyebabkan error class duplikat dalam build Anda, kedua dependensi ini dapat dikecualikan dengan aman.
Jika aplikasi Anda menggunakan SceneCore dan mengaktifkan ProGuard, aplikasi akan error saat Anda membuat Sesi. Sebagai solusi, nonaktifkan ProGuard. Lihat panduan ini untuk mengetahui informasi selengkapnya tentang cara mengaktifkan ProGuard.