Mulai menggunakan Sceneform

Halaman ini menjelaskan konsep utama dengan mempelajari kode dalam aplikasi contoh Hello Sceneform. Catatan:

  • Contoh ini menggunakan Sceneform dan ARCore.

    Untuk menggunakan Sceneform tanpa ARCore, ikuti langkah-langkah di bawah ini dengan mengabaikan dependensi ARCore dan persyaratan izin KAMERA. Gunakan SceneView dalam tata letak aplikasi Anda seperti yang dijelaskan dalam Mem-build Scene.

  • Aplikasi contoh ini ditulis sebagai aplikasi Diperlukan AR.

    Untuk mempelajari aplikasi AR Opsional vs. AR Diperlukan lebih lanjut, lihat Mengaktifkan ARCore.

Untuk mulai menggunakan Sceneform dalam project, Anda perlu:

  1. Impor plugin Sceneform
  2. Mengonfigurasi file build.gradle project
  3. Perbarui AndroidManifest.xml Anda
  4. Melakukan pemeriksaan runtime dan membuat tampilan scene
  5. Membuat item yang dapat dirender
  6. Buat Tampilan

Mengimpor plugin Sceneform ke dalam project Anda

Setelah diinstal, plugin Sceneform memungkinkan Anda mengimpor, melihat, dan mem-build aset 3D di Sceneform SDK untuk aplikasi AR di Android Studio. Versi ini memerlukan Android Studio versi 3.1 dan yang lebih baru.

Untuk menginstal plugin:

  1. Di Android Studio, buka setelan Plugins:

    • Windows: File > Setelan > Plugin > Jelajahi Repositori

    • macOS: Android Studio > Preferences > Plugin

  2. Klik Cari repositori, lalu instal Google Sceneform Tools (Beta).

Konfigurasikan file build.gradle project Anda

  1. Pastikan build.gradle project Anda menyertakan repositori Maven Google:

    allprojects {
    repositories {
        google()
        …

  2. Perbarui build.gradle app's untuk menambahkan dependensi ARCore dan Sceneform UX terbaru, dan pastikan setelan project Anda kompatibel dengan kedua library.

    android {
    …
    defaultConfig {
        // Sceneform requires minSdkVersion >= 24.
        minSdkVersion 24
        …
    }
    // Sceneform libraries use language constructs from Java 8.
    // Add these compile options if targeting minSdkVersion < 26.
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    …
    // Provides ARCore Session and related resources.
    implementation 'com.google.ar:core:1.15.0'

    // Provides ArFragment, and other UX resources.
    implementation 'com.google.ar.sceneform.ux:sceneform-ux:1.15.0'

    // Alternatively, use ArSceneView without the UX dependency.
    implementation 'com.google.ar.sceneform:core:1.15.0'
}

Perbarui AndroidManifest.xml

Ubah AndroidManifest.xml Anda untuk menunjukkan bahwa aplikasi Anda menggunakan (AR Opsional) atau memerlukan akses (AR Diperlukan) ARCore dan KAMERA:

<!-- Both "AR Optional" and "AR Required" apps require CAMERA permission. -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Sceneform requires OpenGL ES 3.0 or later. -->
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

<!-- Indicates that app requires ARCore ("AR Required"). Ensures the app is
     visible only in the Google Play Store on devices that support ARCore.
     For "AR Optional" apps remove this line. -->
<uses-feature android:name="android.hardware.camera.ar" />

<application>
    …
    <!-- Indicates that app requires ARCore ("AR Required"). Causes the Google
         Play Store to download and install Google Play Services for AR along
         with the app. For an "AR Optional" app, specify "optional" instead of
         "required".
    -->
    <meta-data android:name="com.google.ar.core" android:value="required" />
</application>

Melakukan pemeriksaan runtime dan membuat tampilan scene

Cara termudah untuk mulai menggunakan Sceneform dan membuat tampilan scene adalah dengan menggunakan ArFragment, yang secara otomatis menangani pengelolaan sesi ARCore setelah melakukan pemeriksaan runtime ARCore yang diperlukan:

  1. Memeriksa apakah versi Layanan Google Play untuk AR yang kompatibel diinstal, yang meminta pengguna untuk menginstal atau mengupdate versi yang diperlukan

  2. Memeriksa apakah aplikasi memiliki akses ke kamera, dan meminta izin kepada pengguna jika belum diberikan

Jika aplikasi Anda perlu meminta izin tambahan, atau ingin menyesuaikan cara dan waktu sesi AR dibuat, Anda dapat:

  • Buat subclass dari ArFragment untuk meminta izin tambahan.

  • Menggunakan atau memperluas ArSceneView secara langsung. Aplikasi Anda harus melakukan pemeriksaan versi ARCore dan memanggil setupSession() untuk membuat sesi ARCore secara manual, seperti yang ditunjukkan dalam contoh Solar System.

Setelah pemeriksaan lulus, ArFragment akan membuat:

  1. ArSceneView, yang dapat diakses melalui getArSceneView(), yang:

    • Merender gambar kamera dari sesi ke permukaannya

    • Merender animasi UX Sceneform bawaan yang menunjukkan kepada pengguna cara memindahkan ponsel untuk mengaktifkan pengalaman AR.

    • Sorotan terdeteksi Planes menggunakan PlaneRenderer default

  2. ARCore Session, dapat diakses melalui getSession()

Untuk menggunakan ArFragment di aplikasi Anda, tambahkan ke tata letak aktivitas Anda, seperti yang ditunjukkan dalam activity_ux.xml dalam contoh Hello Sceneform:

<fragment android:name="com.google.ar.sceneform.ux.ArFragment"
    android:id="@+id/ux_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Membuat render

Renderable adalah model 3D yang dapat ditempatkan di mana saja dalam scene dan terdiri dari Mesh, Material, dan Tekstur.

Render dapat dibuat dari:

Aplikasi contoh membuat file yang dapat dirender dari file aset andy.obj 3D. Saat aset ini diimpor, plugin Sceneform akan mengupdate build.gradle aplikasi untuk menerapkan plugin dan menambahkan entri sceneform.asset() untuk model yang diimpor:

apply plugin: 'com.google.ar.sceneform.plugin'

sceneform.asset('sampledata/models/andy.obj', // 'Source Asset Path' specified during import.
                'default',                    // 'Material Path' specified during import.
                'sampledata/models/andy.sfa', // '.sfa Output Path' specified during import.
                'src/main/res/raw/andy')      // '.sfb Output Path' specified during import.

Resource res/raw/andy digunakan untuk membuat ModelRenderable:

private ModelRenderable andyRenderable;

@Override
protected void onCreate(Bundle savedInstanceState) {
    …

    ModelRenderable.builder()
        .setSource(this, R.raw.andy)
        .build()
        .thenAccept(renderable -> andyRenderable = renderable)
        .exceptionally(
            throwable -> {
            Log.e(TAG, "Unable to load Renderable.", throwable);
            return null;
        });
}

Membuat Tampilan

ARSceneView memiliki Scene yang terkait. Scene adalah struktur data seperti pohon yang menyimpan Node yang merupakan objek virtual yang akan dirender.

Di sini andy dapat dirender secara langsung ke node Scene root:

Node node = new Node();
node.setParent(arFragment.getArSceneView().getScene());
node.setRenderable(andyRenderable);

Setiap node berisi semua informasi Sceneform yang diperlukan untuk merendernya (termasuk posisi, orientasi, dan objek yang dapat dirender) serta berinteraksi dengannya (termasuk bentuk konflik dan pemroses peristiwanya).

Node dapat ditambahkan ke node lain, sehingga membentuk hubungan induk-turunan. Jika node adalah turunan dari node lain, node akan bergerak, berputar, dan diskalakan dengan induknya—seperti bagaimana lengan Anda bergerak saat tubuh bergerak. Node dapat memiliki beberapa turunan, tetapi hanya satu induk, sehingga membentuk struktur seperti pohon. Struktur ini dikenal sebagai grafik adegan.

Setiap frame, Sceneform merender grafik scene dari sudut pandang Kamera (dipandu oleh pelacakan gerakan ARCore). Aplikasi Anda dapat berinteraksi dengan scene dengan memproses peristiwa sentuh dan gestur, menjalankan pengujian hit terhadap node, dan menempatkan anchor. Untuk mengetahui informasi selengkapnya, lihat Mem-build dan Berinteraksi dengan Scene.