Extensions API

CameraX menyediakan Extensions API untuk mengakses efek khusus berikut yang telah diimplementasikan oleh produsen pada berbagai perangkat Android (Ponsel, Tablet, atau lainnya)

• Otomatis: Menyesuaikan gambar akhir dengan latar pemandangan di sekitarnya secara otomatis. Misalnya, implementasi library vendor mungkin akan melakukan deteksi cahaya redup dan dapat beralih ke mode cahaya redup atau mode HDR untuk mengambil gambar, atau library mungkin akan otomatis menerapkan mode retouch wajah saat mengambil foto potret. Mode otomatis membiarkan implementasi library vendor untuk memilih mode.
• Bokeh: Mode Bokeh membuat karakter latar depan tampak lebih tajam dan memburamkan latar belakang foto. Secara umum, opsi ini ditujukan untuk mengambil foto potret orang dan mirip dengan yang akan dihasilkan oleh kamera dengan lensa besar.
• Retouch Wajah: Melakukan retouch warna kulit wajah, geometri, dan sebagainya saat mengambil gambar diam.
• Rentang Dinamis Tinggi (HDR): Mode HDR mengambil foto yang mempertahankan rentang tingkat pencahayaan scene yang lebih besar tetap terlihat pada gambar akhir. Misalnya, jika mengambil foto objek di depan jendela yang terang, baik objek maupun scene di belakang jendela mungkin terlihat saat menggunakan mode HDR. Namun, saat menggunakan mode normal, salah satu dari objek dan scene mungkin kurang jelas terlihat. Sebagai konsekuensinya, mode HDR biasanya memerlukan waktu lebih lama untuk mengambil satu foto, tidak memiliki kontrol pengguna, dan mungkin memiliki artefak lain bergantung pada metode HDR yang digunakan.
• Malam: Mendapatkan gambar diam terbaik dalam kondisi minim cahaya, biasanya di malam hari.

Untuk mendukung ekstensi vendor tersebut, perangkat harus memenuhi persyaratan berikut:

• Efek memiliki dukungan library dari ROM perangkat.
• Library ROM diinstal di perangkat saat ini.
• Perangkat memiliki versi sistem operasi yang diperlukan oleh library.

Anda dapat mengaktifkan ekstensi secara preferensial: jika ekstensi didukung oleh dan secara fisik ada di perangkat, ekstensi akan diaktifkan; jika tidak, ekstensi akan didegradasi halus.

Vendor tidak diharuskan menyediakan implementasi untuk setiap efek dan fitur. Kapabilitas yang tidak disertai implementasi vendor akan ditetapkan secara default ke implementasi CameraX. Implementasi default ini melaporkan bahwa kapabilitas tidak tersedia, sehingga langkah untuk mengaktifkannya dapat dilewati.

Arsitektur ekstensi

Gambar berikut menampilkan arsitektur untuk ekstensi dengan CameraX.

Ekstensi terpisah dari inti Camera2 CameraX. Dalam diagram, panah berwarna merah menunjukkan alur data utama saat pengguna memicu fitur berbasis ekstensi, seperti pengambilan gambar HDR.

Mengaktifkan efek untuk pratinjau dan pengambilan gambar

Sebelum menggunakan API ekstensi, ambil instance ExtensionsManager menggunakan metode ExtensionsManager#getInstanceAsync(Context, CameraProvider). Ini akan memungkinkan Anda mengkueri informasi ketersediaan ekstensi. Lalu, ambil CameraSelector yang mengaktifkan ekstensi. Mode ekstensi akan diterapkan pada kasus penggunaan pratinjau dan pengambilan gambar saat memanggil metode bindToLifecycle() dengan ekstensi CameraSelector yang diaktifkan.

Untuk mengimplementasikan ekstensi pada kasus penggunaan pratinjau dan pengambilan gambar, lihat contoh kode berikut:

import androidx.camera.extensions.ExtensionMode
import androidx.camera.extensions.ExtensionsManager

fun onCreate() {
    // Create a camera provider
    val cameraProvider : ProcessCameraProvider = ... // Get the provider instance

    lifecycleScope.launch {
        // Create an extensions manager
        val extensionsManager =
                ExtensionsManager.getInstanceAsync(context, cameraProvider).await()

        // Select the camera
        val cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA

        // Query if extension is available.
        if (extensionsManager.isExtensionAvailable(
                cameraSelector,
                ExtensionMode.BOKEH
            )
        ) {
            // Unbind all use cases before enabling different extension modes.
            cameraProvider.unbindAll()

            // Retrieve extension enabled camera selector
            val bokehCameraSelector = extensionsManager.getExtensionEnabledCameraSelector(
                cameraSelector,
                ExtensionMode.BOKEH
            )

            // Bind image capture and preview use cases with the extension enabled camera selector.
            val imageCapture = ImageCapture.Builder().build()
            val preview = Preview.Builder().build()
            cameraProvider.bindToLifecycle(
                lifecycleOwner,
                bokehCameraSelector,
                imageCapture,
                preview
            )
        }
    }
}

import androidx.camera.extensions.ExtensionMode;
import androidx.camera.extensions.ExtensionsManager;

void onCreate() {
    // Create a camera provider
    ProcessCameraProvider cameraProvider = ... // Get the provider instance

    // Call the getInstanceAsync function to retrieve a ListenableFuture object
    ListenableFuture future =
            ExtensionsManager.getInstanceAsync(context, cameraProvider);

    // Obtain the ExtensionsManager instance from the returned ListenableFuture object
    future.addListener(() -> {
        try {
            ExtensionsManager extensionsManager = future.get();

            // Select the camera
            CameraSelector cameraSelector = CameraSelector.DEFAULT_BACK_CAMERA;

            // Query if extension is available.
            if (extensionsManager.isExtensionAvailable(cameraSelector, ExtensionMode.BOKEH)) {
                // Unbind all use cases before enabling different extension modes.
                cameraProvider.unbindAll();

                // Retrieve extension enabled camera selector
                CameraSelector bokehCameraSelector = extensionsManager
                    .getExtensionEnabledCameraSelector(cameraSelector, ExtensionMode.BOKEH);

                // Bind image capture and preview use cases with the extension enabled camera selector.
                ImageCapture imageCapture = new ImageCapture.Builder().build();
                Preview preview = new Preview.Builder().build();
                cameraProvider.bindToLifecycle(lifecycleOwner, bokehCameraSelector, imageCapture, preview);
            }
        } catch (ExecutionException | InterruptedException e) {
            // This should not happen unless the future is cancelled or the thread is interrupted by
            // applications.
        }
    }, ContextCompact.getMainExecutor(context));
}

Menonaktifkan efek

Untuk menonaktifkan ekstensi vendor, putuskan ikatan semua kasus penggunaan dan ikat ulang kasus penggunaan pratinjau dan pengambilan gambar dengan pemilih kamera normal. Misalnya, ikat ulang ke kamera belakang menggunakan CameraSelector.DEFAULT_BACK_CAMERA.

Dependensi

API Ekstensi CameraX diterapkan di library camera-extensions. Ekstensi bergantung pada modul inti CameraX (core, camera2, lifecycle).

dependencies {
  def camerax_version = "1.2.0-alpha04"
  implementation "androidx.camera:camera-core:${camerax_version}"
  implementation "androidx.camera:camera-camera2:${camerax_version}"
  implementation "androidx.camera:camera-lifecycle:${camerax_version}"
  //the CameraX Extensions library
  implementation "androidx.camera:camera-extensions:${camerax_version}"
    ...
}

dependencies {
  val camerax_version = "1.2.0-alpha04"
  implementation("androidx.camera:camera-core:${camerax_version}")
  implementation("androidx.camera:camera-camera2:${camerax_version}")
  implementation("androidx.camera:camera-lifecycle:${camerax_version}")
  // the CameraX Extensions library
  implementation("androidx.camera:camera-extensions:${camerax_version}")
    ...
}

Penghapusan API lama

Dengan API Ekstensi baru yang dirilis pada 1.0.0-alpha26, API Ekstensi lama yang dirilis pada bulan Agustus 2019 kini tidak digunakan lagi. Dimulai dari versi 1.0.0-alpha28, API Ekstensi lama telah dihapus dari library. Aplikasi yang menggunakan API Ekstensi baru kini harus mendapatkan CameraSelector yang mendukung ekstensi dan menggunakannya untuk mengikat kasus penggunaan.

Aplikasi yang menggunakan API Ekstensi lama harus dimigrasikan ke API Ekstensi baru untuk memastikan kompatibilitas dengan rilis CameraX mendatang.

Referensi lainnya

Untuk mempelajari CameraX lebih lanjut, lihat referensi tambahan berikut.

Codelab

Contoh kode

Referensi lainnya

Ekstensi Vendor CameraX

Alat Validasi Ekstensi Vendor CameraX