Halaman ini diterjemahkan oleh Cloud Translation API.

Jetpack SceneCore

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

Buat dan manipulasi grafik adegan 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 sematan. Agar penanganan kembali 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 dalam 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 Parent, Activity, dan Real World, dan nilai default untuk parameter ini adalah Parent.
Metode ekstensi Callback Visibilitas Spasial ditambahkan ke SessionExt.kt untuk memantau saat konten adegan bergerak di dalam atau di luar bidang pandang pengguna.
setPointSourceParams telah ditambahkan ke SpatialAudioTrack, sehingga memungkinkan parameter diperbarui setelah jalur dibuat.
Menambahkan class baru, Scene, dengan referensi ke API Scenecore. 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 penunjuk, atau menonaktifkan ikon. Saat ini, Komponen ini hanya dapat dilampirkan ke instance PanelEntity.
Memperkenalkan factory PanelEntity baru, yang menggunakan dimensi panel dalam meter atau piksel. Pabrik PanelEntity lama yang menggunakan dua parameter jenis Dimensi untuk panel telah dihapus.

Perubahan API

Menghapus batasan RequiresApi(34) pada semua paket Jetpack XR. Pembatasan ini berlebihan karena Jetpack XR saat ini hanya tersedia di perangkat dengan level API 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 Session di SceneCore telah dihapus untuk mendukung Session di XR Runtime.
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 sekarang memerlukan PlaneTrackingMode untuk dikonfigurasi di Session.configure().
API SpatialUser kini memerlukan HeadTrackingMode untuk dikonfigurasi di Session.configure().
Jika ResizableComponent tidak terlampir, log tingkat INFO akan diberikan, bukan log tingkat ERROR.
Class Fov kini menjadi class Kotlin biasa.
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 di platform, dengan cara terbaik, untuk membantu proses pen-debug-an aplikasi.

Perbaikan Bug

Perbaikan ditambahkan untuk mencegah error yang dapat terjadi saat PanelEntity dengan MovableComponent dan AnchorPlacement dipindahkan
Memperbaiki masalah saat ResizableComponent memberikan ukuran yang tidak berlaku lagi di 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 pengecilan Proguard untuk Jetpack XR SceneCore (I4f47e)
Memperbarui aturan Jetpack XR Scenecore ProGuard untuk mencegah AbstractMethodError bagi klien yang di-minifikasi. (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 dibuat sebelum 1.0.0-alpha02

Metode factory telah dipindahkan dari class Session ke metode pendamping pada setiap jenis masing-masing:
- 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 yang tidak digunakan lagi berikut telah dihapus:
- Session.canEmbedActivityPanel(Activity) telah dihapus. Sebagai gantinya, gunakan getSpatialCapabilities.hasCapabilility(SPATIAL_CAPABILITY_EMBED_ACTIVITY).
- Session.hasSpatialCapability(Int) telah dihapus. getSpatialCapabilities() telah diganti dengan 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 berlaku hingga panel dipindahkan lagi. Hal ini dapat diatasi dengan memindahkan panel ke posisinya saat ini
Saat BoundsChanged dipanggil di ActivitySpace, beberapa ActivityPose mungkin belum diperbarui dengan benar. Informasi ini akan diperbarui pada panggilan OnSpaceUpdated berikutnya pada ActivitySpace

Perubahan yang dapat menyebabkan gangguan & perubahan perilaku

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 dengan menyetel CanvasShape
StereoSurfaceEntity memiliki anggota CanvasShape yang dapat ditetapkan secara dinamis.
StereoSurfaceEntity.dimensions sekarang menjadi properti hanya baca; aplikasi harus menyetel CanvasShape untuk mengubah dimensi.
StereoSurfaceEntity kini memungkinkan StereoMode disetel ulang setelah dibuat.

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 penanda akan gagal jika izin tidak diberikan oleh pengguna.

Perbaikan bug

getActivitySpacePose() telah diperbaiki untuk memperhitungkan skala ActivitySpace dengan menampilkan nilai terjemahan dalam meter berskala, bukan selalu menampilkan meter yang tidak berskala. 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 pekat 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 awal developer Jetpack SceneCore, library grafik adegan 3D untuk membuat dan memanipulasi adegan dan lingkungan imersif. Library ini memungkinkan Anda menempatkan dan mengatur model 3D dan panel konten relatif 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 adegan XR lingkungan Anda. Atau aktifkan passthrough, sehingga adegan virtual Anda dapat berintegrasi dengan lingkungan dunia nyata pengguna.
PanelEntity: Tambahkan konten 2D ke adegan 3D Anda dengan menyematkan tata letak dan Aktivitas Android standar ke dalam panel spasial yang dapat mengambang atau ditambatkan ke permukaan dunia nyata.
GltfModelEntity: Tempatkan, animasikan, dan berinteraksi dengan model 3D dalam adegan Anda. SceneCore mendukung format file glTF untuk memudahkan integrasi dengan model yang ada.
SpatialAudio: Tambahkan sumber audio sekitar dan titik ke dalam adegan 3D Anda untuk suara spasial yang sepenuhnya imersif.
StereoSurfaceEntity: SceneCore mendukung perutean konten mata kiri/kanan yang dirender ke Android Surface. Hal ini dapat digunakan untuk merender konten stereoskopik dalam format berdampingan atau atas-bawah, seperti foto stereo, video 3D, atau UI yang dirender secara dinamis lainnya. 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 passthrough diaktifkan, Anda dapat melampirkan panel dan model ke permukaan sebenarnya, sehingga pengguna dapat mengintegrasikan konten virtual dengan lancar di lingkungan dunia nyata mereka.
Pose Pengguna: Akses lokasi pengguna dalam adegan virtual, untuk mengarahkan konten Anda di sekitar posisi pengguna.
SpatialCapabilities: Buat aplikasi yang sepenuhnya adaptif yang memanfaatkan kemampuan spasialisasi jika tersedia, seperti penempatan konten UI 3D. Tidak hanya itu, aplikasi Anda dapat memantau perubahan kemampuan saat aplikasi sedang 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 berikut <uses-sdk tools:overrideLibrary="androidx.xr.scenecore, androidx.xr.compose"/> 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, solusi yang dapat dilakukan antara lain 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 Diubah Ukurannya tidak didukung di GltfEntity.
Entity.getSize() tidak didukung di GltfEntity.
Aplikasi XR Jetpack harus meminta izin android.permission.SCENE_UNDERSTANDING di AndroidManifest.
Membuat sesi hanya didukung di perangkat Android XR. Saat ini, jika Anda membuat Sesi dan mencoba menggunakannya di perangkat XR non-Android, 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. Pada rilis mendatang, scenecore akan menyertakan library ini sebagai dependensi api sehingga klien tidak perlu mendeklarasikannya secara eksplisit.
SceneCore secara keliru 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.