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.
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.
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
harusandroidx.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 .