Halaman ini diterjemahkan oleh Cloud Translation API.

Ekstensi Vendor CameraX

Produsen perangkat dapat menerapkan pustaka vendor OEM CameraX untuk mengekspos efek khusus perangkat kepada pengembang pihak ketiga melalui antarmuka ekstensi CameraX. CameraX mendefinisikan antarmuka ekstensi CameraX untuk kelas implementasi vendor yang dimuat saat runtime. Halaman ini menjelaskan cara menerapkan pustaka vendor OEM dan mengaktifkannya di perangkat.

Sebelum mengimplementasikan pustaka vendor, pastikan Anda memahami cara kerja pustaka dukungan CameraX Jetpack. Untuk mempelajari lebih lanjut tentang CameraX, lihat ikhtisar CameraX . Untuk informasi selengkapnya tentang ekstensi vendor, lihat Ekstensi vendor .

Arsitektur

Gambar 1. Diagram arsitektur ekstensi vendor

Diagram ini menjelaskan arsitektur ekstensi vendor CameraX. Aplikasi pihak ketiga dapat dibuat berdasarkan pustaka ekstensi CameraX ( camera-extensions ) dan menggunakan API publik ekstensi kamera ( camera-extensions API ). API ekstensi kamera ditentukan oleh CameraX dan diperbarui saat versi baru pustaka ekstensi kamera dirilis. Versi API publik ekstensi kamera dan pustaka ekstensi kamera adalah sama.

Dari Android 12, aplikasi pihak ketiga dapat dibuat dengan API ekstensi Camera2. Untuk mengaktifkan mode ekstensi yang didukung, aplikasi dapat membuat sesi pengambilan kamera ( CameraExtensionSession ) menggunakan CameraDevice#createExtensionSession() .

Antarmuka ekstensi ( extensions-interface ) yang ditentukan oleh CameraX memungkinkan pustaka ekstensi kamera CameraX dan API ekstensi Camera2 untuk berkomunikasi dengan pustaka vendor OEM ( camera-extensions-stub ). Ini berarti bahwa perangkat yang mengimplementasikan pustaka vendor OEM CameraX juga memiliki dukungan untuk API ekstensi Camera2.

Menerapkan perpustakaan vendor OEM

Petunjuk penerapan ini menggunakan ekstensi vendor bokeh (potret) sebagai contoh, tetapi Anda dapat menerapkannya ke ekstensi lain seperti HDR, retouch wajah, dan ekstensi mode malam. Untuk melakukannya, salin dan tempel kode yang digunakan untuk ekstensi bokeh dan ganti nama ekstensi dengan ekstensi yang diinginkan (misalnya, mengganti BokehImageCaptureExtenderImpl dengan HdrImageCaptureExtenderImpl ).

Anda tidak diharuskan untuk memberikan implementasi untuk setiap efek. Efek tanpa implementasi vendor default ke implementasi CameraX. Jika efek tidak tersedia, implementasi default tidak mengaktifkan efek dan melaporkan kepada pengembang pihak ketiga bahwa efek tidak tersedia.

Verifikasi versi

Saat memuat pustaka OEM, CameraX memverifikasi bahwa pustaka OEM berisi versi yang kompatibel dengan versi antarmuka ekstensi (disebut sebagai versi ekstensi dalam dokumen ini). Untuk menentukan kompatibilitas versi, CameraX hanya memeriksa versi mayor dan minor (misalnya, 1.0) tetapi tidak memeriksa versi patch karena itu hanya digunakan untuk perbaikan bug, bukan perubahan antarmuka. Versi ekstensi yang diperlukan untuk API tertentu dicatat dalam dokumen ini. API tanpa versi ekstensi yang ditentukan kompatibel dengan versi ekstensi 1.0.

Untuk memverifikasi versi, CameraX menanyakan antarmuka ExtensionVersionImpl . CameraX kemudian menggunakan versi yang dilaporkan oleh perpustakaan OEM untuk menentukan fungsionalitas yang dapat dipanggil.

inisialisasi

CameraX memulai proses inisialisasi ketika telah menentukan versi antarmuka ekstensi yang diterapkan oleh pustaka OEM. Metode InitializerImpl.init memberi sinyal ke pustaka OEM bahwa aplikasi ingin menggunakan ekstensi. Tidak ada panggilan lain ke pustaka OEM (selain pemeriksaan versi) yang dilakukan hingga OnExtensionsInitializedCallback dipanggil dengan status sukses.

Metode ini harus diterapkan pada ekstensi-versi 1.1. Untuk detailnya, lihat sumbernya di InitializerImpl .

Antarmuka ExtenderStateListener

CameraX menyediakan pengait ke beberapa tempat dalam salurannya untuk memungkinkan pustaka OEM menyetel nilai SessionParameters dan CaptureRequest yang relevan. Untuk mengizinkan pustaka OEM menyetel nilai ini pada waktu yang ditentukan, terapkan antarmuka ExtenderStateListener . Antarmuka ini harus diimplementasikan sebagai bagian dari perluasan apa pun, baik itu pratinjau, pengambilan gambar, bokeh, atau perluasan HDR.

Pengambilan gambar

Untuk mendukung ekstensi pengambilan gambar , terapkan antarmuka ImageCaptureExtender yang sesuai (misalnya, BokehImageCaptureExtenderImpl atau HdrImageCaptureExtenderImpl ).

ImageCaptureExtenderImpl menyertakan antarmuka yang diperlukan untuk ekstensi yang terkait dengan pengambilan gambar.

Antarmuka CaptureProcessorImpl harus diimplementasikan agar pemrosesan pasca dilakukan di lapisan aplikasi. Pada antarmuka ekstensi versi 1.1, hanya format gambar masukan YUV_420_888 yang harus didukung. Antarmuka CaptureProcessor tidak diperlukan jika pemrosesan dilakukan di kamera HAL.

Diagram berikut menggambarkan alur proses pengambilan gambar.

Alur proses pengambilan gambar

Gambar 2. Diagram alur pengambilan gambar

Contoh: BokehImageCaptureExtenderImpl

Untuk mendukung ekstensi bokeh untuk pengambilan gambar, implementasikan kelas BokehImageCaptureExtenderImpl dalam paket androidx.camera.extensions.impl .

Pratinjau

Untuk mendukung ekstensi untuk preview , terapkan antarmuka PreviewExtender yang sesuai (misalnya, BokehPreviewExtenderImpl atau HdrPreviewExtenderImpl ). Antarmuka PreviewExtender mencakup antarmuka yang diperlukan untuk ekstensi terkait pratinjau.

Untuk detailnya, lihat sumbernya di PreviewExtenderImpl .

Pemrosesan gambar untuk ekstensi pratinjau dapat dilakukan di HAL kamera atau lapisan aplikasi. Ini ditentukan oleh nilai ProcessorType , yang dikembalikan oleh PreviewExtenderImpl .

Jika tipe PROCESSOR_TYPE_REQUEST_UPDATE_ONLY dikembalikan, pemrosesan dilakukan di HAL melalui kunci CaptureRequest . Jika tipe PROCESSOR_TYPE_IMAGE_PROCESSOR dikembalikan, pemrosesan dilakukan di lapisan aplikasi oleh antarmuka PreviewImageProcessorImpl . Antarmuka ini beroperasi pada pasangan Image dan TotalCaptureResult . Pada antarmuka ekstensi versi 1.1, hanya format gambar masukan YUV_420_888 yang harus didukung.

Diagram berikut mengilustrasikan alur proses untuk ekstensi vendor pratinjau.

Pratinjau diagram alur

Gambar 3. Diagram alir pratinjau

Contoh: BokehPreviewExtenderImpl

Untuk mendukung bokeh untuk pratinjau, implementasikan kelas BokehPreviewExtenderImpl dalam paket androidx.camera.extensions.impl .

Implementasi referensi

Untuk implementasi pustaka vendor OEM referensi, lihat camera-testlib-extensions . Perhatikan bahwa implementasi ini melakukan passthrough tanpa benar-benar mengimplementasikan efeknya.

Menyiapkan perpustakaan vendor di perangkat

Pustaka vendor OEM tidak dibangun ke dalam aplikasi tetapi dimuat dari perangkat saat runtime oleh CameraX. Tag <uses-library> mendeklarasikan bahwa library androidx.camera.extensions.impl , yang didefinisikan dalam file AndroidManifest.xml , adalah dependensi CameraX dan harus dimuat saat runtime. Ini memungkinkan aplikasi pihak ketiga yang menggunakan ekstensi vendor untuk secara otomatis mencoba memuat pustaka vendor OEM. Pustaka OEM ditandai sebagai opsional sehingga aplikasi dapat berjalan di perangkat yang tidak memiliki pustaka di perangkat.

CameraX menangani perilaku ini secara otomatis saat aplikasi mencoba menggunakan ekstensi vendor selama produsen perangkat menempatkan pustaka OEM di perangkat sehingga dapat ditemukan oleh aplikasi.

Untuk menyiapkan perpustakaan OEM di perangkat, lakukan hal berikut:

Tambahkan file izin, yang diperlukan oleh <uses-library> , menggunakan format berikut: /etc/permissions/ ANY_FILENAME .xml . Misalnya, /etc/permissions/camera_extensions.xml . File dalam direktori ini menyediakan pemetaan pustaka yang diberi nama di <uses-library> ke jalur file sebenarnya di perangkat.
Gunakan contoh di bawah ini untuk menambahkan informasi yang diperlukan ke file.
- name harus androidx.camera.extensions.impl karena itulah perpustakaan yang dicari CameraX.
- file adalah path absolut dari file yang berisi implementasi ekstensi (misalnya, /system/framework/androidx.camera.extensions.impl.jar ).
```
<?xml version="1.0" encoding="utf-8"?>
<permissions>
    <library name="androidx.camera.extensions.impl"
             file="OEM_IMPLEMENTED_JAR" />
</permissions>
```

Di Android 12 atau lebih tinggi, perangkat yang mendukung ekstensi CameraX harus memiliki properti ro.camerax.extensions.enabled disetel ke true , yang memungkinkan untuk menanyakan apakah perangkat mendukung ekstensi. Untuk melakukan ini, tambahkan baris berikut di file make perangkat:

PRODUCT_VENDOR_PROPERTIES += \
    ro.camerax.extensions.enabled=true \

Validasi

Untuk menguji implementasi pustaka vendor OEM Anda selama tahap pengembangan, gunakan aplikasi contoh di androidx-main/camera/integration-tests/extensionstestapp/ , yang dijalankan melalui berbagai ekstensi vendor.

Setelah Anda menyelesaikan penerapan Anda, gunakan Alat Validasi Ekstensi Vendor CameraX untuk menjalankan pengujian otomatis dan manual untuk memverifikasi bahwa pustaka vendor diterapkan dengan benar.

Pertanyaan yang sering diajukan (FAQ)

Apakah ada batasan pada level API?

Ya. Ini bergantung pada kumpulan fitur Android API yang diperlukan oleh implementasi pustaka vendor OEM. Misalnya, ExtenderStateListener.onPresetSession() menggunakan panggilan SessionConfiguration.setSessionParameters() untuk menetapkan kumpulan tag dasar. Panggilan ini hanya tersedia di API level 28 dan lebih tinggi. Untuk detail tentang metode antarmuka tertentu, lihat dokumentasi referensi API .