Ekstensi Kamera

Produsen perangkat dapat mengekspos ekstensi seperti bokeh, mode malam, dan HDR kepada pengembang pihak ketiga melalui antarmuka Ekstensi Kamera yang disediakan oleh perpustakaan vendor OEM. Pengembang dapat menggunakan Camera2 Extensions API dan CameraX Extensions API untuk mengakses ekstensi yang diterapkan di perpustakaan vendor OEM.

Untuk daftar ekstensi yang didukung, yang sama di Camera2 dan CameraX, lihat CameraX Extensions API . Jika Anda ingin menambahkan ekstensi, laporkan bug ke Issue Tracker .

Halaman ini menjelaskan cara menerapkan dan mengaktifkan perpustakaan vendor OEM pada perangkat.

Arsitektur

Diagram berikut menjelaskan arsitektur antarmuka Ekstensi Kamera atau extensions-interface : Arsitektur

Gambar 1. Diagram arsitektur Ekstensi Kamera

Seperti yang ditunjukkan dalam diagram, untuk mendukung Ekstensi Kamera, Anda perlu mengimplementasikan extensions-interface yang disediakan oleh perpustakaan vendor OEM. Pustaka vendor OEM Anda mengaktifkan dua API: CameraX Extensions API dan Camera2 Extensions API , yang masing-masing digunakan oleh aplikasi CameraX dan Camera2, untuk mengakses ekstensi vendor.

Menerapkan perpustakaan vendor OEM

Untuk mengimplementasikan pustaka vendor OEM, salin file camera-extensions-stub ke dalam proyek pustaka sistem. File-file ini menentukan antarmuka Ekstensi Kamera.

File camera-extensions-stub dibagi ke dalam kategori berikut:

File antarmuka penting (jangan diubah)

  • PreviewExtenderImpl.java
  • ImageCaptureExtenderImpl.java
  • ExtenderStateListener.java
  • ProcessorImpl.java
  • PreviewImageProcessorImpl.java
  • CaptureProcessorImpl.java
  • CaptureStageImpl.java
  • RequestUpdateProcessorImpl.java
  • ProcessResultImpl.java
  • advanced/AdvancedExtenderImpl.java
  • advanced/Camera2OutputConfigImpl.java
  • advanced/Camera2SessionConfigImpl.java
  • advanced/ImageProcessorImpl.java
  • advanced/ImageReaderOutputConfigImpl.java
  • advanced/ImageReferenceImpl.java
  • advanced/MultiResolutionImageReaderOutputConfigImpl.java
  • advanced/OutputSurfaceImpl.java
  • advanced/RequestProcessorImpl.java
  • advanced/SessionProcessorImpl.java
  • advanced/SurfaceOutputConfigImpl.java

Implementasi wajib (tambahkan implementasi Anda)

  • ExtensionVersionImpl.java
  • InitializerImpl.java

Kelas pemanjang Bokeh (terapkan jika ekstensi Bokeh didukung)

  • BokehImageCaptureExtenderImpl.java
  • BokehPreviewExtenderImpl.java
  • advanced/BokehAdvancedExtenderImpl.java

Kelas pemanjang malam (terapkan jika ekstensi Malam didukung)

  • NightImageCaptureExtenderImpl.java
  • NightPreviewExtenderImpl.java
  • advanced/NightAdvancedExtenderImpl.java

Kelas perluasan otomatis (terapkan jika ekstensi Otomatis didukung)

  • AutoImageCaptureExtenderImpl.java
  • AutoPreviewExtenderImpl.java
  • advanced/AutoAdvancedExtenderImpl.java

Kelas pemanjang HDR (terapkan jika ekstensi HDR didukung)

  • HdrImageCaptureExtenderImpl.java
  • HdrPreviewExtenderImpl.java
  • advanced/HdrAdvancedExtenderImpl.java

Kelas ekstender Retouch Wajah (terapkan jika ekstensi Retouch Wajah didukung)

  • BeautyImageCaptureExtenderImpl.java
  • BeautyPreviewExtenderImpl.java
  • advanced/BeautyAdvancedExtenderImpl.java

Utilitas (opsional, dapat dihapus)

  • advanced/Camera2OutputConfigImplBuilder.java
  • advanced/Camera2SessionConfigImplBuilder.java

Anda tidak diharuskan menyediakan implementasi untuk setiap ekstensi. Jika Anda tidak menerapkan ekstensi, setel isExtensionAvailable() untuk mengembalikan false atau menghapus kelas Extender yang sesuai. API Ekstensi Camera2 dan CameraX melaporkan ke aplikasi bahwa ekstensi tidak tersedia.

Mari kita lihat bagaimana Camera2 dan CameraX Extensions API berinteraksi dengan pustaka vendor untuk mengaktifkan ekstensi. Diagram berikut mengilustrasikan aliran end-to-end menggunakan ekstensi Night sebagai contoh:

Arus utama

Gambar 2. Implementasi perpanjangan malam

  1. Verifikasi versi:

    Camera2/X memanggil ExtensionVersionImpl.checkApiVersion() untuk memastikan bahwa versi extensions-interface yang diterapkan OEM kompatibel dengan versi yang didukung Camera2/X.

  2. Inisialisasi perpustakaan vendor:

    InitializerImpl memiliki metode init() yang menginisialisasi perpustakaan vendor. Camera2/X menyelesaikan inisialisasi sebelum mengakses kelas Extender.

  3. Membuat instance kelas Extender:

    Membuat instance kelas Extender untuk ekstensi. Ada dua jenis Extender: Basic Extender dan Advanced Extender. Anda harus menerapkan satu jenis Extender untuk semua Ekstensi. Untuk informasi lebih lanjut, lihat Basic Extender versus Advanced Extender .

    Camera2/X membuat instance dan berinteraksi dengan kelas Extender untuk mengambil informasi dan mengaktifkan ekstensi. Untuk ekstensi tertentu, Camera2/X dapat membuat instance kelas Extender beberapa kali. Oleh karena itu, jangan lakukan inisialisasi berat pada konstruktor atau panggilan init() . Lakukan pekerjaan berat hanya saat sesi kamera akan dimulai, misalnya saat onInit() dipanggil di Basic Extender atau initSession() dipanggil di Advanced Extender.

    Untuk ekstensi Malam, kelas Extender berikut dipakai untuk tipe Basic Extender:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    Dan untuk tipe Advanced Extender :

    • NightAdvancedExtenderImpl.java

  4. Periksa ketersediaan ekstensi:

    Sebelum mengaktifkan ekstensi, isExtensionAvailable() memeriksa apakah ekstensi tersedia pada ID kamera yang ditentukan melalui instance Extender.

  5. Inisialisasi Extender dengan informasi kamera:

    Camera2/X memanggil init() pada instance Extender dan meneruskan ID kamera dan CameraCharacteristics ke dalamnya.

  6. Informasi permintaan:

    Memanggil kelas Extender untuk mengambil informasi seperti resolusi yang didukung, tetap menangkap perkiraan latensi, dan mengambil kunci permintaan dari Extender sebagai persiapan untuk mengaktifkan ekstensi.

  7. Aktifkan ekstensi di Extender:

    Kelas Extender menyediakan semua antarmuka yang diperlukan untuk mengaktifkan kelas. Ia menawarkan mekanisme untuk menghubungkan implementasi OEM ke dalam pipeline Camera2 seperti memasukkan parameter permintaan pengambilan atau mengaktifkan post processor.

    Untuk tipe Advanced Extender, Camera2/X berinteraksi dengan SessionProcessorImpl untuk mengaktifkan ekstensi. Camera2/X mengambil instance SessionProcessorImpl dengan memanggil createSessionProcessor() pada Extender.

Bagian berikut menjelaskan alur perluasan secara lebih rinci.

Verifikasi versi

Saat memuat pustaka vendor OEM dari perangkat saat runtime, Camera2/X memverifikasi apakah pustaka tersebut kompatibel dengan versi extensions-interface . extensions-interface menggunakan versi semantik, atau MAJOR.MINOR.PATCH, misalnya, 1.1.0 atau 1.2.0. Namun, hanya versi mayor dan minor yang digunakan selama verifikasi versi.

Untuk memverifikasi versinya, Camera2/X memanggil ExtensionVersionImpl.checkApiVersion() dengan versi extensions-interface yang didukung. Camera2/X kemudian menggunakan versi yang dilaporkan oleh perpustakaan OEM untuk menentukan apakah ekstensi dapat diaktifkan dan kemampuan apa yang harus digunakan.

Kompatibilitas versi utama

Jika versi utama antarmuka ekstensi berbeda antara Camera2/X dan pustaka vendor, maka versi tersebut dianggap tidak kompatibel dan ekstensi dinonaktifkan.

Kompatibilitas terbalik

Selama versi utama identik, Camera2/X memastikan kompatibilitas dengan pustaka vendor OEM yang dibangun dengan versi extensions-interface sebelumnya. Misalnya, jika Camera2/X mendukung extensions-interface 1.3.0, pustaka vendor OEM yang menerapkan 1.0.0, 1.1.0, dan 1.2.0 masih kompatibel. Ini juga berarti bahwa setelah Anda mengimplementasikan versi tertentu dari pustaka vendor, Camera2/X memastikan bahwa pustaka tersebut kompatibel dengan versi extension-interface yang akan datang.

Kompatibilitas ke depan

Kompatibilitas ke depan dengan perpustakaan vendor extensions-interface yang lebih baru bergantung pada Anda, OEM. Jika Anda memerlukan beberapa fitur untuk mengimplementasikan ekstensi, Anda mungkin ingin mengaktifkan ekstensi mulai dari versi tertentu. Dalam hal ini, Anda dapat mengembalikan versi extensions-interface yang didukung ketika versi pustaka Camera2/X memenuhi persyaratan. Jika versi Camera2/X tidak didukung, Anda dapat mengembalikan versi yang tidak kompatibel seperti 99.0.0 untuk menonaktifkan ekstensi.

Inisialisasi perpustakaan vendor

Setelah memverifikasi versi extensions-interface yang diterapkan oleh perpustakaan OEM, Camera2/X memulai proses inisialisasi. Metode InitializerImpl.init() memberi sinyal ke pustaka OEM bahwa aplikasi mencoba menggunakan ekstensi.

Camera2/X tidak melakukan panggilan lain ke pustaka OEM (selain pemeriksaan versi) hingga pustaka vendor OEM memanggil OnExtensionsInitializedCallback.onSuccess() untuk memberitahukan selesainya inisialisasi.

Anda harus mengimplementasikan InitializerImpl pada extensions-interface 1.1.0. Camera2/X melewatkan langkah inisialisasi perpustakaan jika perpustakaan vendor OEM mengimplementasikan extensions-interface 1.0.0.

Extender Dasar versus Extender Tingkat Lanjut

Ada dua jenis implementasi extensions-interface : Basic Extender dan Advanced Extender. Advanced Extender telah didukung sejak extensions-interface 1.2.0.

Menerapkan Basic Extender untuk ekstensi yang memproses gambar di kamera HAL atau menggunakan post processor yang mampu memproses aliran YUV.

Terapkan Advanced Extender untuk ekstensi yang perlu menyesuaikan konfigurasi aliran Camera2 dan mengirim permintaan pengambilan sesuai kebutuhan.

Lihat tabel berikut untuk perbandingannya:

Ekstender Dasar Ekstender Tingkat Lanjut
Konfigurasi aliran Tetap
Pratinjau: PRIVATE atau YUV_420_888 (jika prosesor ada)
Masih menangkap: JPEG atau YUV_420_888 (jika prosesor ada)		 Dapat disesuaikan oleh OEM.
Mengirim permintaan penangkapan Hanya Camera2/X yang dapat mengirim permintaan pengambilan. Anda dapat mengatur parameter untuk permintaan ini. Ketika prosesor disediakan untuk pengambilan gambar, Camera2/X dapat mengirim beberapa permintaan pengambilan dan mengirimkan semua gambar serta hasil pengambilan ke prosesor. Instance RequestProcessorImpl diberikan kepada Anda untuk menjalankan permintaan pengambilan kamera2 dan mendapatkan hasil dan Gambar.

Camera2/X memanggil startRepeating dan startCapture pada SessionProcessorImpl untuk memberi sinyal kepada OEM agar memulai permintaan berulang untuk pratinjau dan memulai urutan pengambilan gambar diam.

Kait di pipa kamera
  • onPresetSession menyediakan parameter sesi.
  • onEnableSession mengirimkan satu permintaan tepat setelah CameraCaptureSession dikonfigurasi.
  • onDisableSession mengirimkan satu permintaan sebelum CameraCaptureSession ditutup.
  • initSession menginisialisasi dan mengembalikan konfigurasi sesi kamera2 yang disesuaikan untuk membuat sesi pengambilan.
  • onCaptureSessionStart dipanggil tepat setelah CameraCaptureSession dikonfigurasi.
  • onCaptureSessionEnd dipanggil sebelum CameraCaptureSession ditutup.
Cocok untuk Ekstensi diimplementasikan di kamera HAL atau di prosesor yang memproses gambar YUV.
  • Memiliki implementasi berbasis Camera2 untuk ekstensi.
  • Membutuhkan konfigurasi aliran yang disesuaikan seperti aliran RAW.
  • Memerlukan urutan pengambilan yang interaktif.
Versi API yang didukung Ekstensi Camera2: Android 13 atau lebih tinggi
Ekstensi CameraX: camera-extensions 1.1.0 atau lebih tinggi		 Ekstensi Camera2: Android 12L atau lebih tinggi
Ekstensi CameraX: camera-extensions 1.2.0-alpha03 atau lebih tinggi

Aliran aplikasi

Tabel berikut menunjukkan tiga jenis alur aplikasi dan panggilan API Ekstensi Kamera yang terkait. Meskipun Camera2/X menyediakan API ini, Anda harus mengimplementasikan pustaka vendor dengan benar untuk mendukung alur ini, yang akan kami jelaskan lebih detail di bagian selanjutnya.

Ekstensi Kamera2 Ekstensi CameraX
Ketersediaan ekstensi kueri CameraExtensionCharacteristics . getSupportedExtensions ExtensionsManager. isExtensionAvailable
Informasi kueri CameraExtensionCharacteristics. getExtensionSupportedSizes CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis CameraExtensionCharacteristics. getAvailableCaptureRequestKeys CameraExtensionCharacteristics. getAvailableCaptureResultKeys ExtensionsManager. getEstimatedCaptureLatencyRange

CameraX menangani informasi lainnya di dalam perpustakaan.

Pratinjau dan ambil gambar diam dengan ekstensi diaktifkan CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

 val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector bindToLifecycle(lifecycleOwner, cameraSelector, pratinjau, ...)

Ekstender Dasar

Antarmuka Basic Extender menyediakan pengait ke beberapa tempat di saluran kamera. Setiap jenis ekstensi memiliki kelas Extender terkait yang perlu diterapkan oleh OEM.

Tabel berikut mencantumkan kelas Extender yang perlu diterapkan oleh OEM untuk setiap ekstensi:

Kelas extender untuk diimplementasikan
Malam NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

HDR HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java
Mobil AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java
Bokeh BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java
Perbaikan wajah BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java

Kami menggunakan PreviewExtenderImpl dan ImageCaptureExtenderImpl sebagai placeholder dalam contoh berikut. Ganti ini dengan nama file sebenarnya yang Anda implementasikan.

Basic Extender memiliki kemampuan sebagai berikut:

  • Masukkan parameter sesi saat mengonfigurasi CameraCaptureSession ( onPresetSession ).
  • Memberi tahu Anda tentang peristiwa awal dan penutupan sesi pengambilan dan mengirimkan satu permintaan untuk memberi tahu HAL dengan parameter yang dikembalikan ( onEnableSession , onDisableSession ).
  • Masukkan parameter pengambilan untuk permintaan ( PreviewExtenderImpl.getCaptureStage , ImageCaptureExtenderImpl.getCaptureStages ).
  • Tambahkan prosesor untuk pratinjau dan pengambilan gambar yang mampu memproses aliran YUV_420_888 .

Mari kita lihat bagaimana Camera2/X memanggil extensions-interface untuk mencapai tiga alur aplikasi yang disebutkan di atas.

Alur aplikasi 1: Periksa ketersediaan ekstensi

BasicExtenderAppFlow1

Gambar 3. Alur aplikasi 1 pada Basic Extender

Dalam alur ini, Camera2/X secara langsung memanggil metode isExtensionAvailable() dari PreviewExtenderImpl dan ImageCaptureExtenderImpl tanpa memanggil init() . Kedua kelas Extender harus mengembalikan true untuk mengaktifkan ekstensi.

Ini sering kali merupakan langkah pertama bagi aplikasi untuk memeriksa apakah jenis ekstensi tertentu didukung untuk ID kamera tertentu sebelum mengaktifkan ekstensi. Hal ini karena beberapa ekstensi hanya didukung pada ID kamera tertentu.

Alur aplikasi 2: Informasi kueri

BasicExtenderAppFlow2

Gambar 4. Alur aplikasi 2 pada Basic Extender

Setelah menentukan apakah ekstensi tersedia, aplikasi harus menanyakan informasi berikut sebelum mengaktifkan ekstensi.

  • Masih menangkap rentang latensi: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange mengembalikan rentang latensi pengambilan untuk dievaluasi oleh aplikasi apakah pantas untuk mengaktifkan ekstensi untuk skenario saat ini.

  • Ukuran yang didukung untuk pratinjau dan pengambilan permukaan: ImageCaptureExtenderImpl.getSupportedResolutions dan PreviewExtenderImpl.getSupportedResolutions mengembalikan daftar format gambar dan ukuran yang didukung untuk format dan ukuran permukaan.

  • Kunci permintaan dan hasil yang didukung: Camera2/X memanggil metode berikut untuk mengambil kunci permintaan pengambilan dan kunci hasil yang didukung dari implementasi Anda:

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X selalu memanggil init() terlebih dahulu pada kelas Extender ini sebelum menanyakan informasi lebih lanjut.

Alur aplikasi 3: Pratinjau/pengambilan foto dengan ekstensi diaktifkan (implementasi HAL)

BasicExtenderAppFlow3

Gambar 5. Alur aplikasi 3 pada Basic Extender

Diagram di atas mengilustrasikan alur utama mengaktifkan pratinjau dan pengambilan gambar dengan ekstensi tanpa prosesor apa pun. Ini berarti kamera HAL memproses ekstensi.

Dalam alur ini, Camera2/X terlebih dahulu memanggil init() lalu onInit , yang memberi tahu Anda bahwa sesi kamera akan dimulai dengan ekstensi yang ditentukan. Anda dapat melakukan inisialisasi berat di onInit() .

Saat mengonfigurasi CameraCaptureSession , Camera2/X memanggil onPresetSession untuk mendapatkan parameter sesi. Setelah sesi pengambilan berhasil dikonfigurasi, Camera2/X memanggil onEnableSession yang mengembalikan instance CaptureStageImpl yang berisi parameter pengambilan. Camera2/X segera mengirimkan satu permintaan dengan parameter pengambilan ini untuk memberi tahu HAL. Demikian pula, sebelum sesi pengambilan gambar ditutup, Camera2/X memanggil onDisableSession dan kemudian mengirimkan satu permintaan dengan parameter pengambilan yang dikembalikan.

Permintaan berulang yang dipicu oleh Camera2/X berisi parameter permintaan yang dikembalikan oleh PreviewExtenderImpl.getCaptureStage() . Selain itu, permintaan still capture berisi parameter yang dikembalikan oleh ImageCaptureExtenderImpl.getCaptureStages() .

Terakhir, Camera2/X memanggil onDeInit() setelah sesi kamera selesai. Anda dapat melepaskan sumber daya di onDeinit() .

Pratinjau prosesor

Selain kamera HAL, Anda juga dapat mengimplementasikan ekstensi pada prosesor.

Implementasikan PreviewExtenderImpl.getProcessorType untuk menentukan jenis prosesor seperti yang dijelaskan di bawah:

  • PROCESSOR_TYPE_NONE : Tidak ada prosesor. Gambar diproses di kamera HAL.

  • PROCESSOR_TYPE_REQUEST_UPDATE_ONLY : Jenis prosesor memungkinkan Anda memperbarui permintaan berulang dengan parameter permintaan pengambilan baru berdasarkan TotalCaptureResult terbaru.

    PreviewExtenderImpl.getProcessor harus mengembalikan instance RequestUpdateProcessorImpl yang memproses instance TotalCaptureResult dan mengembalikan instance CaptureStageImpl untuk memperbarui permintaan berulang. PreviewExtenderImpl.getCaptureStage() juga harus mencerminkan hasil pemrosesan dan mengembalikan CaptureStageImpl terbaru.

  • PROCESSOR_TYPE_IMAGE_PROCESSOR : Jenis ini memungkinkan Anda mengimplementasikan prosesor untuk memproses gambar YUV_420_888 dan menulis hasilnya ke permukaan PRIVATE .

    Anda perlu menerapkan dan mengembalikan instance PreviewImageProcessorImpl di PreviewExtenderImpl.getProcessor . Prosesor bertanggung jawab untuk memproses gambar masukan YUV_420_888 . Itu harus menulis output ke format pratinjau PRIVATE . Camera2/X menggunakan permukaan YUV_420_888 dan bukan PRIVATE untuk mengonfigurasi CameraCaptureSession untuk pratinjau.

    Lihat ilustrasi berikut untuk alurnya:

PratinjauProsesor

Gambar 6. Alur pratinjau dengan PreviewImageProcessorImpl

Antarmuka PreviewImageProcessorImpl memperluas ProcessImpl dan memiliki tiga metode penting:

  • onOutputSurface(Surface surface, int imageFormat) mengatur permukaan output untuk prosesor. Untuk PreviewImageProcessorImpl , imageFormat adalah format piksel seperti PixelFormat.RGBA_8888 .

  • onResolutionUpdate(Size size) mengatur ukuran gambar masukan.

  • onImageFormatUpdate(int imageFormat) mengatur format gambar dari gambar masukan. Saat ini, hanya dapat YUV_420_888 .

Prosesor pengambilan gambar

Untuk pengambilan diam, Anda dapat mengimplementasikan prosesor dengan mengembalikan instance CaptureProcessorImpl menggunakan ImageCaptureExtenderImpl.getCaptureProcessor . Prosesor bertanggung jawab untuk memproses daftar gambar YUV_420_888 yang diambil dan instance TotalCaptureResult dan menulis hasilnya ke permukaan YUV_420_888 .

Anda dapat dengan aman berasumsi bahwa pratinjau diaktifkan dan berjalan sebelum mengirim permintaan pengambilan gambar diam.

Lihat alurnya pada diagram di bawah ini:

Prosesor Tangkap

Gambar 7. Masih menangkap alur dengan CaptureProcessorImpl

  1. Camera2/X menggunakan permukaan format YUV_420_888 untuk pengambilan gambar diam guna mengonfigurasi sesi pengambilan. Camera2/X mempersiapkan CaptureProcessorImpl dengan memanggil:

    • CaptureProcessorImpl.onImageFormatUpdate() dengan YUV_420_888 .
    • CaptureProcessorImpl.onResolutionUpdate() dengan ukuran gambar masukan.
    • CaptureProcessorImpl.onOutputSurface() dengan permukaan keluaran YUV_420_888 .

  2. ImageCaptureExtenderImpl.getCaptureStages mengembalikan daftar CaptureStageImpl , dengan setiap elemen dipetakan ke instance CaptureRequest dengan parameter pengambilan yang dikirim oleh Camera2/X. Misalnya, jika mengembalikan daftar tiga instance CaptureStageImpl , Camera2/X mengirimkan tiga permintaan pengambilan dengan parameter pengambilan yang sesuai menggunakan API captureBurst .

  3. Gambar yang diterima dan instance TotalCaptureResult digabungkan menjadi satu dan dikirim ke CaptureProcessorImpl untuk diproses.

  4. CaptureProcessorImpl menulis Gambar hasil (format YUV_420_888 ) ke permukaan keluaran yang ditentukan oleh panggilan onOutputSurface() . Camera2/X mengubahnya menjadi gambar JPEG jika perlu.

Mendukung kunci dan hasil permintaan pengambilan

Selain pratinjau dan pengambilan kamera, aplikasi dapat mengatur zoom, parameter flash, atau memicu ketukan untuk fokus. Parameter ini mungkin tidak kompatibel dengan penerapan ekstensi Anda.

Metode berikut telah ditambahkan ke extensions-interface 1.3.0 untuk memungkinkan Anda mengekspos parameter yang didukung implementasi Anda:

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() mengembalikan kunci permintaan pengambilan yang didukung oleh implementasi Anda.
  • ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() mengembalikan kunci hasil pengambilan yang terdapat dalam hasil pengambilan.

Jika kamera HAL memproses ekstensi, Camera2/X mengambil hasil pengambilan di CameraCaptureSession.CaptureCallback . Namun, jika prosesor diimplementasikan, maka Camera2/X akan mengambil hasil tangkapan di ProcessResultImpl , yang diteruskan ke metode process() di PreviewImageProcessorImpl dan CaptureProcessorImpl . Anda bertanggung jawab untuk melaporkan hasil pengambilan melalui ProcessResultImpl ke Camera2/X.

Lihat definisi antarmuka CaptureProcessorImpl di bawah sebagai contoh. Di extensions-interface 1.3.0 atau lebih tinggi, panggilan process() kedua dipanggil:

Interface CaptureProcessorImpl extends ProcessorImpl {
    // invoked when extensions-interface version < 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results);
    // invoked when extensions-interface version >= 1.3.0
    void process(Map<Integer, Pair<Image, TotalCaptureResult>> results,
            ProcessResultImpl resultCallback, Executor executor);
}

Untuk pengoperasian kamera umum seperti zoom, ketuk untuk fokus, lampu kilat, dan kompensasi pencahayaan, kami sarankan untuk mendukung tombol berikut untuk permintaan pengambilan dan hasil pengambilan:

  • Perbesar:
    • CaptureRequest#CONTROL_ZOOM_RATIO
    • CaptureRequest#SCALER_CROP_REGION
  • Ketuk untuk fokus:
    • CaptureRequest#CONTROL_AF_MODE
    • CaptureRequest#CONTROL_AF_TRIGGER
    • CaptureRequest#CONTROL_AF_REGIONS
    • CaptureRequest#CONTROL_AE_REGIONS
    • CaptureRequest#CONTROL_AWB_REGIONS
  • Kilatan:
    • CaptureRequest#CONTROL_AE_MODE
    • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
    • CaptureRequest#FLASH_MODE
  • Kompensasi eksposur:
    • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Untuk Basic Extender yang mengimplementasikan versi 1.2.0 atau sebelumnya, CameraX Extensions API secara eksplisit mendukung semua kunci di atas. Untuk extensions-interface 1.3.0, CameraX dan Camera2 mengikuti daftar yang dikembalikan dan hanya mendukung kunci yang ada di dalamnya. Misalnya, jika Anda memutuskan untuk hanya mengembalikan CaptureRequest#CONTROL_ZOOM_RATIO dan CaptureRequest#SCALER_CROP_REGION dalam implementasi 1.3.0, itu berarti hanya zoom yang didukung untuk aplikasi sementara kompensasi tap-to-focus, flash, dan eksposur tidak diizinkan.

Ekstender Tingkat Lanjut

Advanced Extender adalah jenis implementasi vendor berdasarkan API Camera2. Jenis Extender ini ditambahkan di extensions-interface 1.2.0. Bergantung pada produsen perangkat, ekstensi mungkin diterapkan di lapisan aplikasi, yang bergantung pada faktor berikut:

  • Konfigurasi aliran khusus: Konfigurasikan aliran khusus seperti aliran RAW atau memiliki beberapa aliran untuk ID kamera fisik yang berbeda.

  • Kemampuan untuk mengirim permintaan Camera2: Mendukung logika interaksi rumit yang dapat mengirim permintaan pengambilan dengan parameter berdasarkan hasil permintaan sebelumnya.

Advanced Extender menyediakan pembungkus, atau lapisan perantara, sehingga Anda dapat menyesuaikan konfigurasi aliran dan mengirim permintaan pengambilan sesuai permintaan.

File untuk diimplementasikan

Untuk beralih ke implementasi Advanced Extender, metode isAdvancedExtenderImplemented() di ExtensionVersionImpl harus mengembalikan true . Untuk setiap jenis ekstensi, OEM harus mengimplementasikan kelas Extender yang sesuai. File implementasi Advanced Extender ada dalam paket lanjutan .

Kelas extender untuk diimplementasikan
Malam advanced/NightAdvancedExtenderImpl.java
HDR advanced/HdrAdvancedExtenderImpl.java
Mobil advanced/AutoAdvancedExtenderImpl.java
Bokeh advanced/BokehAdvancedExtenderImpl.java
Perbaikan Wajah advanced/BeautyAdvancedExtenderImpl.java

Kami menggunakan AdvancedExtenderImpl sebagai placeholder dalam contoh berikut. Gantilah dengan nama file Extender untuk ekstensi yang Anda terapkan.

Mari kita lihat bagaimana Camera2/X memanggil extensions-interface untuk mencapai tiga alur aplikasi.

Alur aplikasi 1: Periksa ketersediaan ekstensi

LanjutanAppFlow1

Gambar 8. Alur aplikasi 1 pada Advanced Extender

Pertama, aplikasi memeriksa apakah ekstensi yang diberikan didukung.

Alur aplikasi 2: Informasi kueri

LanjutanAppFlow2

Gambar 9. Alur aplikasi 2 pada Advanced Extender

Setelah memanggil AdvancedExtenderImpl.init() , aplikasi dapat menanyakan informasi berikut tentang AdvancedExtenderImpl :

  • Perkiraan latensi pengambilan masih: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() mengembalikan rentang latensi pengambilan untuk dievaluasi oleh aplikasi apakah pantas untuk mengaktifkan ekstensi untuk skenario saat ini.

  • Resolusi yang didukung untuk pratinjau dan pengambilan gambar diam:

    • AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() mengembalikan peta format gambar ke daftar ukuran yang didukung untuk pratinjau format dan ukuran permukaan. OEM harus mendukung setidaknya format PRIVATE .

    • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() mengembalikan format dan ukuran yang didukung untuk permukaan pengambilan gambar diam. OEM harus mendukung keluaran format JPEG dan YUV_420_888 .

    • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() mengembalikan ukuran yang didukung untuk aliran YUV_420_888 tambahan untuk analisis gambar. Jika analisis gambar permukaan YUV tidak didukung, getSupportedYuvAnalysisResolutions() akan mengembalikan null atau daftar kosong.

  • Kunci/hasil permintaan pengambilan yang tersedia (ditambahkan di extensions-interface 1.3.0): Camera2/X memanggil metode berikut untuk mengambil kunci permintaan pengambilan dan kunci hasil yang didukung dari penerapan Anda:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys

Untuk informasi selengkapnya, lihat Mendukung kunci dan hasil permintaan pengambilan .

Alur aplikasi 3: Pratinjau/pengambilan foto dengan ekstensi diaktifkan

LanjutanAppFlow3

Gambar 10. Alur aplikasi 3 pada Advanced Extender

Diagram di atas menunjukkan alur utama untuk memulai pratinjau dan pengambilan gambar untuk tipe Advanced Extender. Mari kita telusuri setiap langkahnya.

  1. Contoh SessionProcessorImpl

    Implementasi inti Advanced Extender ada di SessionProcessorImpl , yang bertanggung jawab untuk menyediakan konfigurasi sesi yang disesuaikan dan mengirimkan permintaan pengambilan untuk memulai pratinjau dan masih meminta pengambilan. AdvancedExtenderImpl.createSessionProcessor() dipanggil untuk mengembalikan instance SessionProcessorImpl .

  2. initSession

    SessionProcessorImpl.initSession() menginisialisasi sesi untuk ekstensi. Di sinilah Anda mengalokasikan sumber daya dan mengembalikan konfigurasi sesi untuk menyiapkan CameraCaptureSession .

    Untuk parameter masukan, Camera2/X menentukan konfigurasi permukaan keluaran untuk pratinjau, pengambilan gambar diam, dan analisis gambar YUV opsional. Konfigurasi permukaan keluaran ini ( OutputSurfaceImpl ) berisi permukaan, ukuran dan format gambar yang diambil dengan metode berikut di AdvancedExtenderImpl :

    • getSupportedPreviewOutputResolutions()
    • getSupportedCaptureOutputResolutions()
    • getSupportedYuvAnalysisResolutions()

    Anda harus mengembalikan instance Camera2SessionConfigImpl , yang terdiri dari daftar instance Camera2OutputConfigImpl dan parameter sesi yang digunakan untuk mengonfigurasi CameraCaptureSession . Anda bertanggung jawab untuk mengeluarkan gambar kamera yang benar ke permukaan keluaran yang diteruskan oleh Camera2/X. Berikut beberapa opsi untuk mengaktifkan output:

    • Memproses di kamera HAL: Anda dapat langsung menambahkan permukaan keluaran ke CameraCaptureSession dengan implementasi SurfaceOutputConfigImpl . Ini mengonfigurasi permukaan keluaran yang disediakan ke saluran kamera dan memungkinkan kamera HAL memproses gambar.

    • Memproses permukaan ImageReader perantara (RAW, YUV, dll): Tambahkan permukaan ImageReader perantara ke CameraCaptureSession dengan instance ImageReaderOutputConfigImpl .

      Anda perlu memproses gambar perantara dan menulis gambar hasil ke permukaan keluaran.

    • Gunakan berbagi permukaan Camera2: Gunakan berbagi permukaan dengan permukaan lain dengan menambahkan instance Camera2OutputConfigImpl ke metode getSurfaceSharingOutputConfigs() dari instance Camera2OutputConfigImpl lainnya. Format dan ukuran permukaan harus sama.

    Semua Camera2OutputConfigImpl termasuk SurfaceOutputConfigImpl dan ImageReaderOutputConfigImpl harus memiliki ID unik ( getId() ), yang digunakan untuk menentukan permukaan target dan mengambil gambar dari ImageReaderOutputConfigImpl .

  3. onCaptureSessionStart dan RequestProcessorImpl

    Saat CameraCaptureSession dimulai dan framework Camera memanggil onConfigured() , Camera2/X akan memanggil SessionProcessorImpl.onCaptureSessionStart() dengan pembungkus permintaan Camera2 RequestProcessImpl . Camera2/X mengimplementasikan RequestProcessImpl , yang memungkinkan Anda menjalankan permintaan pengambilan , dan mengambil gambar jika ImageReaderOutputConfigImpl digunakan.

    API RequestProcessImpl mirip dengan API Camera2 CameraCaptureSession dalam hal mengeksekusi permintaan. Perbedaannya adalah:

    • Permukaan target ditentukan oleh ID instance Camera2OutputConfigImpl .
    • Kemampuan mengambil gambar dari ImageReader .

    Anda dapat memanggil RequestProcessorImpl.setImageProcessor() dengan ID Camera2OutputConfigImpl yang ditentukan untuk mendaftarkan instance ImageProcessorImpl guna menerima gambar.

    Instance RequestProcessImpl menjadi tidak valid setelah Camera2/X memanggil SessionProcessorImpl.onCaptureSessionEnd() .

  4. Mulai pratinjau dan ambil gambar

    Dalam implementasi Advanced Extender, Anda dapat mengirim permintaan pengambilan melalui antarmuka RequestProcessorImpl . Camera2/X memberitahu Anda untuk memulai permintaan berulang untuk pratinjau atau urutan pengambilan diam dengan memanggil SessionProcessorImpl#startRepeating dan SessionProcessorImpl#startCapture masing-masing. Anda harus mengirimkan permintaan pengambilan untuk memenuhi permintaan pratinjau dan pengambilan gambar ini.

    Camera2/X juga menyetel parameter permintaan pengambilan melalui SessionProcessorImpl#setParameters . Anda harus mengatur parameter permintaan ini (jika parameter didukung) pada permintaan berulang dan permintaan tunggal.

    Anda harus mendukung setidaknya CaptureRequest.JPEG_ORIENTATION dan CaptureRequest.JPEG_QUALITY . extensions-interface 1.3.0 mendukung kunci permintaan dan hasil, yang diekspos dengan metode berikut:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys()
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys()

    Saat pengembang menyetel kunci dalam daftar getAvailableCaptureRequestKeys , Anda harus mengaktifkan parameter dan memastikan hasil pengambilan berisi kunci dalam daftar getAvailableCaptureResultKeys .

  5. startTrigger

    SessionProcessorImpl.startTrigger() dipanggil untuk memulai pemicu seperti CaptureRequest.CONTROL_AF_TRIGGER dan CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER . Anda dapat mengabaikan kunci permintaan pengambilan apa pun yang tidak diiklankan di AdvancedExtenderImpl.getAvailableCaptureRequestKeys() .

    startTrigger() telah didukung sejak extensions-interface 1.3.0. Hal ini memungkinkan aplikasi untuk menerapkan tap-to-focus dan flash dengan ekstensi.

  6. Membersihkan

    Saat menyelesaikan sesi pengambilan, SessionProcessorImpl.onCaptureSessionEnd() dipanggil sebelum penutupan CameraCaptureSession . Setelah sesi pengambilan ditutup, deInitSession() melakukan pembersihan.

Mendukung pratinjau, pengambilan gambar diam, dan analisis gambar

Anda harus menerapkan ekstensi untuk pratinjau dan tetap menangkap kasus penggunaan. Namun, jika latensi terlalu tinggi untuk menampilkan pratinjau dengan lancar, Anda dapat menerapkan ekstensi hanya untuk pengambilan gambar diam.

Untuk tipe Basic Extender, terlepas dari mengaktifkan ekstensi untuk pratinjau, Anda harus menerapkan ImageCaptureExtenderImpl dan PreviewExtenderImpl untuk ekstensi tertentu. Seringkali, suatu aplikasi juga menggunakan aliran YUV untuk menganalisis konten gambar seperti menemukan kode QR atau teks. Untuk mendukung kasus penggunaan ini dengan lebih baik, Anda harus mendukung kombinasi aliran pratinjau, masih menangkap, dan aliran YUV_420_888 untuk mengkonfigurasi CameraCaptureSession . Ini berarti bahwa jika Anda menerapkan prosesor, maka Anda harus mendukung kombinasi aliran tiga aliran YUV_420_888 .

Untuk Lanjutan Extender, Camera2/X melewati tiga permukaan output ke panggilan SessionProcessorImpl.initSession() . Permukaan output ini masing -masing untuk pratinjau, masih menangkap, dan analisis gambar. Anda harus memastikan bahwa pratinjau dan masih menangkap permukaan output menunjukkan output yang valid. Namun, untuk permukaan output analisis gambar, pastikan hanya berfungsi saat itu bukan nol. Jika implementasi Anda tidak dapat mendukung aliran analisis gambar, Anda dapat mengembalikan daftar kosong di AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() . Ini memastikan permukaan output analisis gambar selalu nol di SessionProcessorImpl.initSession() .

Dukung video penangkapan

Arsitektur ekstensi kamera saat ini hanya mendukung pratinjau dan masih menangkap kasus penggunaan. Kami tidak mendukung mengaktifkan ekstensi pada permukaan MediaCodec atau MediaRecorder untuk merekam video. Namun, mungkin bagi aplikasi untuk merekam output pratinjau.

Mendukung permukaan MediaCodec dan MediaRecorder sedang diselidiki.

Metadata khusus ekstensi

Untuk Android 14 dan lebih tinggi, metadata khusus ekstensi memungkinkan klien ekstensi kamera mengatur dan menerima pengaturan dan hasil permintaan penangkapan khusus ekstensi. Secara khusus, klien ekstensi kamera dapat menggunakan parameter Permintaan Capture EXTENSION_STRENGTH untuk mengontrol kekuatan ekstensi dan hasil penangkapan EXTENSION_CURRENT_TYPE untuk menunjukkan jenis ekstensi yang diaktifkan.

Permintaan menangkap

Parameter Permintaan Penangkapan EXTENSION_STRENGTH mengontrol kekuatan ekstensi efek pasca pemrosesan. Hasil penangkapan yang sesuai mencakup nilai kekuatan default jika parameter ini tidak diatur secara eksplisit oleh klien. Parameter ini dapat diterapkan sebagai berikut untuk jenis ekstensi ini:

  • BOKEH : Mengontrol jumlah Blur.
  • HDR dan NIGHT : Mengontrol jumlah gambar yang menyatu dan kecerahan gambar akhir.
  • FACE_RETOUCH : Mengontrol jumlah peningkatan kosmetik dan perataan kulit.

Kisaran yang didukung untuk parameter EXTENSION_STRENGTH adalah antara 0 dan 100 , dengan 0 menunjukkan tidak ada pemrosesan ekstensi atau passhrough sederhana dan 100 menunjukkan kekuatan ekstensi maksimum dari efek pemrosesan.

Untuk menambahkan dukungan untuk EXTENSION_STRENGTH , gunakan API parameter spesifik vendor yang diperkenalkan dalam versi 1.3.0 dari antarmuka perpustakaan ekstensi. Untuk informasi lebih lanjut, lihat getAvailableCaptureRequestKeys() .

Tangkap hasilnya

Hasil penangkapan EXTENSION_CURRENT_TYPE memungkinkan implementasi ekstensi memberi tahu klien tentang jenis ekstensi aktif.

Karena ekstensi menggunakan tipe AUTO secara dinamis beralih antara jenis ekstensi seperti HDR dan NIGHT tergantung pada kondisi pemandangan, aplikasi ekstensi kamera dapat menggunakan EXTENSION_CURRENT_TYPE untuk menampilkan informasi tentang ekstensi saat ini yang dipilih oleh ekstensi AUTO .

Waktu nyata masih menangkap perkiraan latensi

Untuk Android 14 dan lebih tinggi, klien ekstensi kamera dapat menanyakan perkiraan latensi waktu yang nyata berdasarkan kondisi adegan dan lingkungan menggunakan getRealtimeStillCaptureLatency() . Metode ini memberikan perkiraan yang lebih akurat daripada metode statis getEstimatedCaptureLatencyRangeMillis() . Berdasarkan estimasi latensi, aplikasi dapat memutuskan untuk melewatkan pemrosesan ekstensi atau untuk menampilkan indikasi untuk memberi tahu pengguna tentang operasi yang sudah berjalan lama.

CameraExtensionSession.StillCaptureLatency latency;

latency = extensionSession.getRealtimeStillCaptureLatency();

// The capture latency from ExtensionCaptureCallback#onCaptureStarted() until ExtensionCaptureCallback#onCaptureProcessStarted().

latency.getCaptureLatency();

// The processing latency from  ExtensionCaptureCallback#onCaptureProcessStarted() until  the processed frame returns to the client.

latency.getProcessingLatency();

Untuk mendukung perkiraan latensi waktu nyata masih menangkap, mengimplementasikan yang berikut:

Capture Process Progress Callbacks

Untuk Android 14 dan lebih tinggi, klien ekstensi kamera dapat menerima panggilan balik untuk kemajuan operasi pemrosesan yang sudah berjalan lama. Aplikasi dapat menampilkan kemajuan saat ini kepada pengguna untuk meningkatkan pengalaman pengguna secara keseluruhan.

Aplikasi dapat menggunakan kode berikut untuk mengintegrasikan fitur ini:

import android.hardware.camera2.CameraExtensionSession.
ExtensionCaptureCallback;

{
…
  class AppCallbackImpl extends ExtensionCaptureCallback {
…
    @Override
    public void onCaptureProcessProgressed(
      @NonNull CameraExtensionSession session,
      @NonNull CaptureRequest request,
      @IntRange(from = 0, to = 100) int progress) {
      // Update app UI with current progress
    }
  }
…
}

Untuk mendukung pemrosesan pemrosesan Callbacks, implementasi vendor ekstensi Anda harus memanggil panggilan balik berikut dengan nilai kemajuan saat ini:

Postview masih menangkap

Untuk Android 14 dan lebih tinggi, ekstensi kamera dapat menyediakan postview (gambar pratinjau) menggunakan setPostviewOutputConfiguration . Untuk meningkatkan pengalaman pengguna, aplikasi dapat menampilkan gambar postview sebagai penampung ketika ekstensi mengalami peningkatan latensi pemrosesan, dan mengganti gambar ketika gambar akhir tersedia. Aplikasi dapat mengonfigurasi dan mengeluarkan permintaan penangkapan postview menggunakan kode referensi berikut:

{
…
if (!CameraExtensionCharacteristics.isPostviewAvailable()) {
    continue;
}
…
ExtensionSessionConfiguration extensionConfiguration = new
        ExtensionSessionConfiguration(
                CameraExtensionCharacteristics.EXTENSION_NIGHT,
                outputConfig,
                backgroundExecutor,
                extensionSessionStateCallback
    );

extensionConfiguration.setPostviewOutputConfiguration(
    postviewImageOutput);
…
CaptureRequest.Builder captureRequestBuilder =
    cameraDevice.createCaptureRequest(
        CameraDevice.TEMPLATE_STILL_CAPTURE);
captureRequestBuilder.addTarget(stillImageReader.getSurface());
captureRequestBuilder.addTarget(postviewImageSurface);

CaptureRequest captureRequest = captureRequestBuilder.build();
…
}

Untuk mendukung Postview yang masih menangkap, implementasi vendor Anda harus mengimplementasikan yang berikut:

Dukungan output Surfaceview

Untuk Android 14 dan lebih tinggi, klien ekstensi kamera dapat menggunakan jalur render pratinjau daya dan pratinjau yang dioptimalkan dengan mendaftarkan instance SurfaceView untuk output pratinjau untuk mengulangi permintaan.

Untuk mendukung output SurfaceView , implementasi ekstensi vendor Anda harus mampu streaming dan mengeluarkan pratinjau ke contoh SurfaceView . Untuk memverifikasi bahwa ini didukung, jalankan modul CTS SurfaceViewExtensionPreviewTest.java .

Jenis sesi spesifik vendor

Fitur ini memungkinkan implementasi ekstensi vendor untuk memilih jenis sesi spesifik vendor yang akan diatur dalam sesi pengambilan kamera internal alih -alih nilai default.

Fitur ini berfungsi sepenuhnya dalam kerangka kerja dan tumpukan vendor dan tidak memiliki dampak API yang terlihat klien/publik.

Untuk memilih jenis sesi spesifik vendor, terapkan yang berikut untuk perpustakaan ekstensi Anda: * ExtenderStateListener.onSessionType() untuk ekstensi dasar * Camera2SessionConfigImpl.getSessionType() untuk ekstensi lanjutan

Ekstensi Sejarah Versi Antarmuka

Tabel berikut menunjukkan riwayat versi antarmuka ekstensi kamera. Anda harus selalu mengimplementasikan perpustakaan vendor dengan versi terbaru.

Versi: kapan Fitur tambahan
1.0.0
  • Verifikasi Versi
    • ExtensionVersionImpl
  • Extender Dasar
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • Inisialisasi Perpustakaan
    • InitializerImpl
  • Mengekspos resolusi yang didukung
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • Advancedextender
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • Dapatkan perkiraan latensi penangkapan
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • Mengekspos kunci permintaan penangkapan yang didukung/tombol hasil
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys dan getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys dan getAvailableCaptureResultKeys
    • process() Panggilan yang Mengambil ProcessResultImpl di PreviewImageProcessorImpl dan CaptureProcessorImpl
    • Dukungan Permintaan Jenis Pemicu
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Metadata khusus ekstensi
  • Dinamis masih menangkap estimasi latensi
  • Capture Process Progress Callbacks
  • Postview masih menangkap
  • Dukungan untuk output SurfaceView
  • Jenis sesi spesifik vendor

Implementasi referensi

Implementasi perpustakaan vendor OEM referensi berikut tersedia dalam frameworks/ex .

  • advancedSample : Implementasi Dasar Lanjutan Extender.

  • sample : Implementasi Dasar Extender Dasar.

  • service_based_sample : Implementasi yang menunjukkan cara meng -host ekstensi kamera dalam suatu Service . Implementasi ini berisi komponen berikut:

    • oem_library : Perpustakaan ekstensi kamera OEM untuk API ekstensi Camera2 dan Camerax yang mengimplementasikan Extensions-Interface . Ini bertindak sebagai passthrough yang meneruskan panggilan dari Extensions-Interface ke layanan. Perpustakaan ini juga menyediakan file AIDL dan kelas pembungkus untuk berkomunikasi dengan Layanan.

      Advanced Extender diaktifkan secara default. Untuk mengaktifkan Extender Dasar, ubah ExtensionsVersionImpl#isAdvancedExtenderImplemented untuk mengembalikan false .

    • extensions_service : Implementasi sampel dari layanan ekstensi. Tambahkan implementasi Anda di sini. Antarmuka untuk diimplementasikan dalam Layanan mirip dengan Extensions-Interface . Misalnya, mengimplementasikan IAdvancedExtenderImpl.Stub melakukan operasi yang sama dengan AdvancedExtenderImpl . ImageWrapper dan TotalCaptureResultWrapper diharuskan untuk membuat Image dan TotalCaptureResult Parcelable.

Siapkan Perpustakaan Vendor di perangkat

Perpustakaan Vendor OEM tidak dibangun ke dalam aplikasi; Ini dimuat dari perangkat saat runtime oleh kamera2/x. Di Camerax, tag <uses-library> menyatakan bahwa pustaka androidx.camera.extensions.impl , yang didefinisikan dalam file AndroidManifest.xml dari perpustakaan camera-extensions , adalah ketergantungan Camerax dan harus dimuat pada saat runtime. Di Camera2, kerangka kerja memuat layanan ekstensi yang juga menyatakan bahwa <uses-library> memuat perpustakaan androidx.camera.extensions.impl yang sama saat runtime.

Ini memungkinkan aplikasi pihak ketiga menggunakan ekstensi untuk secara otomatis memuat pustaka vendor OEM. Perpustakaan OEM ditandai sebagai opsional sehingga aplikasi dapat berjalan pada perangkat yang tidak memiliki pustaka di perangkat. Camera2/X menangani perilaku ini secara otomatis ketika aplikasi mencoba menggunakan ekstensi kamera selama produsen perangkat menempatkan perpustakaan OEM pada perangkat sehingga dapat ditemukan oleh aplikasi.

Untuk mengatur perpustakaan OEM pada perangkat, lakukan hal berikut:

  1. Tambahkan file izin, yang diperlukan oleh tag <uses-library> , menggunakan format berikut: /etc/permissions/ ANY_FILENAME .xml . Misalnya, /etc/permissions/camera_extensions.xml . File-file dalam direktori ini menyediakan pemetaan perpustakaan yang disebutkan di <uses-library> ke jalur file yang sebenarnya pada perangkat.

  2. Gunakan contoh di bawah ini untuk menambahkan informasi yang diperlukan ke file.

    • name harus androidx.camera.extensions.impl sebagai pustaka yang dicari Camerax.
    • file adalah jalur 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 true ro.camerax.extensions.enabled extensions. Untuk melakukan ini, tambahkan baris berikut di perangkat membuat file:

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

Validasi

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

Setelah Anda menyelesaikan implementasi Anda, gunakan alat validasi ekstensi kamera untuk menjalankan tes otomatis dan manual untuk memverifikasi bahwa perpustakaan vendor diimplementasikan dengan benar.

Mode adegan diperpanjang versus ekstensi kamera

Untuk ekstensi bokeh, selain mengeksposnya menggunakan ekstensi kamera, Anda dapat mengekspos ekstensi menggunakan mode adegan yang diperluas, yang diaktifkan melalui kunci CONTROL_EXTENDED_SCENE_MODE . Untuk detail implementasi lebih lanjut, lihat Kamera Bokeh .

Mode adegan yang diperluas memiliki batasan yang lebih sedikit dibandingkan dengan ekstensi kamera untuk aplikasi Camera2. Misalnya, Anda dapat mengaktifkan mode adegan yang diperluas dalam instance CameraCaptureSession reguler yang mendukung kombinasi aliran fleksibel dan menangkap parameter permintaan. Sebaliknya, ekstensi kamera hanya mendukung satu set jenis aliran tetap dan memiliki dukungan terbatas untuk parameter permintaan penangkapan.

Kelemahan dari mode adegan yang diperluas adalah bahwa Anda hanya dapat mengimplementasikannya di Camera HAL, yang berarti harus diverifikasi untuk bekerja di semua kontrol ortogonal yang tersedia untuk pengembang aplikasi.

Kami merekomendasikan mengekspos bokeh menggunakan mode adegan yang diperluas dan ekstensi kamera karena aplikasi mungkin lebih suka menggunakan API tertentu untuk mengaktifkan bokeh. Kami merekomendasikan terlebih dahulu menggunakan mode adegan yang diperluas karena ini adalah cara yang paling fleksibel bagi aplikasi untuk mengaktifkan ekstensi bokeh. Kemudian Anda dapat menerapkan antarmuka ekstensi kamera berdasarkan mode adegan yang diperluas. Jika menerapkan bokeh di kamera hal itu sulit, misalnya, karena membutuhkan prosesor pos yang berjalan di lapisan aplikasi untuk memproses gambar, kami sarankan mengimplementasikan ekstensi bokeh menggunakan antarmuka ekstensi kamera.

Pertanyaan yang sering diajukan (FAQ)

Apakah ada batasan pada tingkat API?

Ya. Ini tergantung pada set fitur API Android yang diperlukan oleh Implementasi Perpustakaan Vendor OEM. Misalnya, ExtenderStateListener.onPresetSession() menggunakan panggilan SessionConfiguration.setSessionParameters() untuk mengatur set tag baseline. Panggilan ini hanya tersedia di API Level 28 dan lebih tinggi. Untuk detail tentang metode antarmuka tertentu, lihat dokumentasi referensi API .