{ } { }

Jetpack SceneCore

Buat dan manipulasi grafik tampilan Android XR dengan konten 3D.
Update Terbaru Rilis Stabil Kandidat Rilis Rilis Beta Rilis Alfa
7 Mei 2025 - - - 1.0.0-alpha04

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-alpha04"
    // 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-alpha04"
}

Kotlin

dependencies {
    implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha04")
    // 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-alpha04")
}

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-alpha04

7 Mei 2025

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

Fitur Baru

  • Penanganan kembali kini akan berfungsi pada entity panel tanpa aktivitas tersemat. Agar penanganan balik berfungsi, Anda harus menentukan android:enableOnBackInvokedCallback= "true" dalam manifes Android.
  • StereoSurfaceEntity kini mendukung pemutaran MV-HEVC melalui dua nilai StereoMode baru: MULTIVIEW_LEFT_PRIMARY dan MULTIVIEW_RIGHT_PRIMARY.
  • PanelEntity.setSize dan PanelEntity.getSize kini menampilkan ukuran di ruang induk.
  • Entity.setPose, Entity.getPose, Entity.setScale, Entity.getScale, Entity.setAlpha, dan Entity.getAlpha kini menggunakan parameter baru relativeTo, yang memungkinkan nilai get/set relatif terhadap ruang yang berbeda. Nilai yang didukung adalah ruang Induk, Aktivitas, dan Dunia Nyata, dan nilai default untuk parameter ini adalah Induk.
  • Metode ekstensi Callback Visibilitas Spasial ditambahkan ke SessionExt.kt untuk memantau kapan konten tampilan bergerak di dalam atau di luar bidang pandang pengguna.
  • setPointSourceParams telah ditambahkan ke SpatialAudioTrack, sehingga parameter dapat diperbarui setelah jalur dibuat.
  • Menambahkan class baru, Scene, dengan referensi ke Scenecore API. Scene akan dapat diakses sebagai properti ekstensi Sesi. Fungsi di dalam SessionExt telah dipindahkan ke Scene sehingga impor perlu disesuaikan; misalnya, SessionExt.getScene(session).addSpatialCapababilitiesChangedListener versus SessionExt.addSpatialCapabilitiesChangedListener.
  • ActivityPose.hitTestAsync telah ditambahkan, sehingga memungkinkan hitTest terhadap konten virtual.
  • Menambahkan jenis Komponen baru SpatialPointerComponent, yang memungkinkan klien menentukan ikon yang dirender untuk pointer, atau menonaktifkan ikon. Komponen ini saat ini hanya dapat dilampirkan ke instance PanelEntity.
  • Memperkenalkan factory PanelEntity baru, yang menggunakan dimensi panel dalam meter atau piksel. Factory PanelEntity lama yang menggunakan dua parameter jenis Dimensi untuk panel telah dihapus.

Perubahan API

  • Menghapus batasan RequiresApi(34) di semua paket Jetpack XR. Pembatasan ini tidak diperlukan karena Jetpack XR saat ini hanya tersedia di perangkat dengan API level 34+. (Iae0f8)
  • Project yang dirilis dengan Kotlin 2.0 memerlukan KGP 2.0.0 atau yang lebih baru untuk digunakan (Idb6b5)
  • Class PermissionHelper telah dihapus.
  • PanelEntity.getPixelDensity tidak digunakan lagi.
  • PanelEntity.setPixelDimensions dan PanelEntity.getPixelDimension dihapus, diganti dengan setSizeInPixels dan getSizeInPixels.
  • Entity.getActivitySpaceAlpha dihapus. Dapat diganti dengan Entity.getAlpha(Space.Activity).
  • Entity.getWorldSpaceScale dihapus. Dapat diganti dengan Entity.getScale(Space.REAL\_WORLD).
  • Class Sesi di SceneCore telah dihapus untuk mendukung Sesi di Runtime XR.
  • StereoSurfaceEntity diganti namanya menjadi SurfaceEntity.
  • Entity.setSize dan Entity.getSize dihapus, dan metode yang sama ditambahkan ke PanelEntity.
  • PointSourceAttributes diganti namanya menjadi PointSourceParams.
  • SpatializerConstants.SOURCE\_TYPE\_BYPASS diganti namanya menjadi SpatializerConstants.SOURCE\_TYPE\_DEFAULT.
  • Entitas PointSourceParams telah diubah dari akses publik menjadi internal.
  • AnchorEntity.create kini mewajibkan PlaneTrackingMode dikonfigurasi di Session.configure().
  • SpatialUser API kini mewajibkan HeadTrackingMode dikonfigurasi di Session.configure().
  • Jika ResizableComponent tidak dilampirkan, log level INFO akan diberikan, bukan log level ERROR.
  • Class Fov kini menjadi class Kotlin reguler.
  • Pisahkan Entity.kt untuk menempatkan setiap jenis entitas konkret ke dalam filenya sendiri.
  • Saat membuat PanelEntity baru, sebagian besar Tampilan akan diubah induknya ke FrameLayout. Hal ini memfasilitasi penggunaan LayoutInspector dengan Panel Spasial.
  • Instance XrExtensions yang saat ini digunakan kini terdaftar dengan platform, dengan cara terbaik, untuk membantu proses debug aplikasi.

Perbaikan Bug

  • Perbaikan telah ditambahkan untuk mencegah error yang dapat terjadi saat PanelEntity dengan MovableComponent dan AnchorPlacement dipindahkan
  • Memperbaiki masalah saat ResizableComponent memberikan ukuran yang sudah tidak berlaku dalam callback onResizeStart.
  • Memperbaiki error saat dispose() JxrPlatformAdapterAxr dipanggil beberapa kali.

Versi 1.0.0-alpha03

26 Februari 2025

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

Fitur Baru

  • Minifikasi Proguard kini didukung untuk kode Jetpack XR

Perbaikan Bug

  • Perbaikan tambahan untuk mendukung minifikasi Proguard untuk Jetpack XR SceneCore (I4f47e)
  • Memperbarui aturan ProGuard Jetpack XR Scenecore untuk mencegah AbstractMethodError untuk klien yang diminifikasi. (I91a01)

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 mendapatkan 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 mendapatkan 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 penetapan 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 terintegrasi 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 platform 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: Tambahkan sumber audio ambient dan titik ke dalam tampilan 3D Anda untuk mendapatkan 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 yang 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 secara 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 mencakup 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.