Ekstensi kamera

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

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

Halaman ini menjelaskan cara menerapkan dan mengaktifkan library vendor OEM di 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 library vendor OEM. Library 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.

Mengimplementasikan library vendor OEM

Untuk menerapkan library vendor OEM, salin file camera-extensions-stub ke project library sistem. 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

Penerapan wajib (tambahkan penerapan Anda)

  • ExtensionVersionImpl.java
  • InitializerImpl.java

Class ekstensi bokeh (terapkan jika ekstensi Bokeh didukung)

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

Kelas ekstender malam (terapkan jika ekstensi Malam didukung)

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

Class alat perluasan otomatis (terapkan jika ekstensi Otomatis didukung)

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

Class HDR extender (terapkan jika ekstensi HDR didukung)

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

Class 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 perlu menyediakan implementasi untuk setiap ekstensi. Jika Anda tidak mengimplementasikan ekstensi, tetapkan isExtensionAvailable() untuk menampilkan false atau hapus class Extender yang sesuai. API Ekstensi Camera2 dan CameraX melaporkan ke aplikasi bahwa ekstensi tidak tersedia.

Mari kita bahas cara Camera2 dan CameraX Extensions API berinteraksi dengan library vendor untuk mengaktifkan ekstensi. Diagram berikut mengilustrasikan alur menyeluruh menggunakan ekstensi Night sebagai contoh:

Mainflow

Gambar 2. Penerapan ekstensi 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 library vendor:

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

  3. Buat instance class Extender:

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

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

    Untuk ekstensi Malam, class Extender berikut dibuat instance-nya untuk jenis Extender Dasar:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    Dan untuk jenis Advanced Extender:

    • NightAdvancedExtenderImpl.java

  4. Periksa ketersediaan ekstensi:

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

  5. Lakukan inisialisasi Extender dengan informasi kamera:

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

  6. Informasi kueri:

    Memanggil class Extender untuk mengambil informasi seperti resolusi yang didukung, tetap merekam estimasi latensi, dan merekam kunci permintaan dari Extender sebagai persiapan untuk mengaktifkan ekstensi.

  7. Aktifkan ekstensi di Extender:

    Class Extender menyediakan semua antarmuka yang diperlukan untuk mengaktifkan class. API ini menawarkan mekanisme untuk mengaitkan implementasi OEM ke dalam pipeline Camera2 seperti memasukkan parameter permintaan pengambilan atau mengaktifkan post-processor.

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

Bagian berikut menjelaskan alur ekstensi secara lebih mendetail.

Verifikasi versi

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

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

Kompatibilitas versi utama

Jika versi utama extension-interface berbeda antara Camera2/X dan library vendor, library tersebut dianggap tidak kompatibel dan ekstensi akan dinonaktifkan.

Kompatibilitas mundur

Selama versi utamanya identik, Camera2/X memastikan kompatibilitas mundur dengan library vendor OEM yang di-build dengan versi extensions-interface sebelumnya. Misalnya, jika Camera2/X mendukung extensions-interface 1.3.0, library vendor OEM yang menerapkan 1.0.0, 1.1.0, dan 1.2.0 masih kompatibel. Hal ini juga berarti bahwa setelah Anda menerapkan versi library vendor tertentu, Camera2/X akan memastikan library kompatibel dengan versi extension-interface mendatang.

Kompatibilitas dengan versi baru

Kompatibilitas maju dengan library vendor extensions-interface yang lebih baru bergantung pada Anda, OEM. Jika memerlukan beberapa fitur untuk menerapkan ekstensi, Anda dapat mengaktifkan ekstensi mulai dari versi tertentu. Dalam hal ini, Anda dapat menampilkan versi extensions-interface yang didukung saat versi library Camera2/X memenuhi persyaratan. Jika versi Camera2/X tidak didukung, Anda dapat menampilkan versi yang tidak kompatibel seperti 99.0.0 untuk menonaktifkan ekstensi.

Inisialisasi library vendor

Setelah memverifikasi versi extensions-interface yang diimplementasikan oleh library OEM, Camera2/X akan memulai proses inisialisasi. Metode InitializerImpl.init() memberikan sinyal ke library OEM bahwa aplikasi mencoba menggunakan ekstensi.

Camera2/X tidak melakukan panggilan lain ke library OEM (selain pemeriksaan versi) hingga library vendor OEM memanggil OnExtensionsInitializedCallback.onSuccess() untuk memberi tahu penyelesaian inisialisasi.

Anda harus menerapkan InitializerImpl mulai extensions-interface 1.1.0. Camera2/X melewati langkah inisialisasi library jika library vendor OEM menerapkan extensions-interface 1.0.0.

Extender Dasar versus Advanced Extender

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

Terapkan Extender Dasar untuk ekstensi yang memproses gambar di HAL kamera atau gunakan post-processor yang mampu memproses streaming YUV.

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

Lihat tabel berikut untuk perbandingannya:

Ekstensi Dasar Ekstensi Lanjutan
Konfigurasi streaming Diperbaiki
Pratinjau: PRIVATE atau YUV_420_888 (jika prosesor ada)
Masih ambil gambar: JPEG atau YUV_420_888 (jika prosesor ada) 		Dapat disesuaikan oleh OEM.
Mengirim permintaan pengambilan Hanya Camera2/X yang dapat mengirim permintaan pengambilan gambar. Anda dapat menetapkan parameter ke permintaan ini. Saat prosesor disediakan untuk pengambilan gambar, Camera2/X dapat mengirim beberapa permintaan pengambilan dan mengirim semua gambar serta hasilnya ke prosesor. Instance RequestProcessorImpl disediakan untuk Anda untuk menjalankan permintaan pengambilan camera2 serta mendapatkan hasil dan Gambar.

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

Hook di pipeline kamera
  • onPresetSession menyediakan parameter sesi.
  • onEnableSession mengirimkan satu permintaan tepat setelah CameraCaptureSession dikonfigurasi.
  • onDisableSession mengirim satu permintaan sebelum CameraCaptureSession ditutup.
  • initSession melakukan inisialisasi dan menampilkan konfigurasi sesi camera2 yang disesuaikan untuk membuat sesi pengambilan.
  • onCaptureSessionStart dipanggil tepat setelah CameraCaptureSession dikonfigurasi.
  • onCaptureSessionEnd dipanggil sebelum CameraCaptureSession ditutup.
Cocok untuk Ekstensi yang diterapkan di HAL kamera atau dalam prosesor yang memproses image YUV.
  • Memiliki implementasi berbasis Camera2 untuk ekstensi.
  • Memerlukan konfigurasi streaming yang disesuaikan seperti streaming RAW.
  • Membutuhkan urutan Rekaman interaktif.
Versi API yang didukung Ekstensi Camera2: Android 13 atau yang lebih baru
Ekstensi CameraX: camera-extensions 1.1.0 atau yang lebih baru		 Ekstensi Camera2: Android 12L atau yang lebih tinggi
Ekstensi CameraX: camera-extensions 1.2.0-alpha03 atau yang lebih tinggi

Alur aplikasi

Tabel berikut menunjukkan tiga jenis alur aplikasi dan panggilan Camera Extensions API yang sesuai. Meskipun Camera2/X menyediakan API ini, Anda harus menerapkan library vendor dengan benar untuk mendukung alur ini, yang akan kami jelaskan secara lebih mendetail di bagian selanjutnya.

Ekstensi Camera2 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 dalam library.

Pratinjau dan pengambilan gambar diam dengan ekstensi diaktifkan CameraDevice. createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector

bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)

Ekstensi Dasar

Antarmuka Basic Extender menyediakan hook ke beberapa tempat di pipeline kamera. Setiap jenis ekstensi memiliki class Extender yang sesuai yang perlu diimplementasikan oleh OEM.

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

Class ekstensi yang akan diimplementasikan
Malam NightPreviewExtenderImpl.java

NightImageCaptureExtenderImpl.java

HDR HdrPreviewExtenderImpl.java

HdrImageCaptureExtenderImpl.java

Otomatis AutoPreviewExtenderImpl.java

AutoImageCaptureExtenderImpl.java

Bokeh BokehPreviewExtenderImpl.java

BokehImageCaptureExtenderImpl.java

Retouch wajah BeautyPreviewExtenderImpl.java

BeautyImageCaptureExtenderImpl.java

Kita menggunakan PreviewExtenderImpl dan ImageCaptureExtenderImpl sebagai placeholder dalam contoh berikut. Ganti ini dengan nama file aktual yang Anda terapkan.

Extender Dasar memiliki kemampuan berikut:

  • Memasukkan parameter sesi saat mengonfigurasi CameraCaptureSession ( onPresetSession).
  • Memberi tahu Anda tentang peristiwa awal dan penutupan sesi pengambilan dan mengirim satu permintaan untuk memberi tahu HAL dengan parameter yang ditampilkan (onEnableSession, onDisableSession).
  • Masukkan parameter pengambilan untuk permintaan (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
  • Menambahkan pemroses untuk pratinjau dan tetap merekam yang mampu memproses streaming YUV_420_888.

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

Alur aplikasi 1: Memeriksa ketersediaan ekstensi

BasicExtenderAppFlow1

Gambar 3. Alur aplikasi 1 di Extender Dasar

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

Sebelum mengaktifkan ekstensi, hal ini sering kali menjadi langkah pertama bagi aplikasi untuk memeriksa apakah jenis ekstensi tertentu didukung untuk ID kamera tertentu. Hal ini karena beberapa ekstensi hanya didukung pada ID kamera tertentu.

Alur aplikasi 2: Informasi kueri

BasicExtenderAppFlow2

Gambar 4. Alur aplikasi 2 di Extender Dasar

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

  • Rentang latensi pengambilan gambar diam: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange menampilkan rentang latensi pengambilan gambar untuk aplikasi guna mengevaluasi apakah perlu mengaktifkan ekstensi untuk skenario saat ini.

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

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

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X selalu memanggil init() terlebih dahulu pada class Extender ini sebelum membuat kueri untuk mengetahui informasi selengkapnya.

Alur aplikasi 3: Pratinjau/pengambilan gambar diam dengan ekstensi diaktifkan (penerapan HAL)

BasicExtenderAppFlow3

Gambar 5. Alur aplikasi 3 di Basic Extender

Diagram di atas mengilustrasikan alur utama untuk mengaktifkan pratinjau dan merekam diam dengan ekstensi tanpa prosesor apa pun. Artinya, HAL kamera memproses ekstensi.

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

Saat mengonfigurasi CameraCaptureSession, Camera2/X memanggil onPresetSession untuk mendapatkan parameter sesi. Setelah sesi pengambilan berhasil dikonfigurasi, Camera2/X memanggil onEnableSession, yang menampilkan instance CaptureStageImpl yang berisi parameter pengambilan. Camera2/X segera mengirimkan permintaan tunggal dengan parameter pengambilan ini untuk memberi tahu HAL. Demikian pula, sebelum sesi pengambilan ditutup, Camera2/X memanggil onDisableSession, lalu mengirim satu permintaan dengan parameter pengambilan yang ditampilkan.

Permintaan berulang yang dipicu oleh Camera2/X berisi parameter permintaan yang ditampilkan oleh PreviewExtenderImpl.getCaptureStage(). Selain itu, permintaan pengambilan gambar statis berisi parameter yang ditampilkan oleh ImageCaptureExtenderImpl.getCaptureStages().

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

Pemroses pratinjau

Selain HAL kamera, Anda juga dapat menerapkan ekstensi di prosesor.

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

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

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

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

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

    Anda perlu mengimplementasikan dan menampilkan instance PreviewImageProcessorImpl di PreviewExtenderImpl.getProcessor. Prosesor bertanggung jawab untuk memproses gambar input YUV_420_888. Perintah tersebut harus menulis output ke format pratinjau PRIVATE. Camera2/X menggunakan platform YUV_420_888, bukan PRIVATE, guna mengonfigurasi CameraCaptureSession untuk pratinjau.

    Lihat ilustrasi berikut untuk mengetahui alur:

Prosesor Pratinjau

Gambar 6. Pratinjau alur dengan PreviewImageProcessorImpl

Antarmuka PreviewImageProcessorImpl memperluas ProcessImpl dan memiliki tiga metode penting:

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

  • onResolutionUpdate(Size size) menetapkan ukuran gambar input.

  • onImageFormatUpdate(int imageFormat) menetapkan format gambar dari gambar input. Saat ini, hanya YUV_420_888 yang dapat digunakan.

Prosesor pengambilan gambar

Untuk pengambilan gambar diam, Anda dapat menerapkan prosesor dengan menampilkan instance CaptureProcessorImpl menggunakan ImageCaptureExtenderImpl.getCaptureProcessor. Prosesor bertanggung jawab untuk memproses daftar gambar YUV_420_888 dan instance TotalCaptureResult yang diambil serta menulis output ke platform YUV_420_888.

Anda dapat dengan aman berasumsi bahwa pratinjau telah diaktifkan dan berjalan sebelum mengirim permintaan perekaman diam.

Lihat alur dalam diagram di bawah:

CaptureProcessor

Gambar 7. Masih merekam alur dengan CaptureProcessorImpl

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

    • CaptureProcessorImpl.onImageFormatUpdate() dengan YUV_420_888.
    • CaptureProcessorImpl.onResolutionUpdate() dengan ukuran gambar input.
    • CaptureProcessorImpl.onOutputSurface() dengan platform YUV_420_888 output.

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

  3. Gambar yang diterima dan instance TotalCaptureResult dipaketkan bersama dan dikirim ke CaptureProcessorImpl untuk diproses.

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

Mendukung kunci dan hasil permintaan pengambilan gambar

Selain pratinjau dan pengambilan kamera, aplikasi dapat menyetel zoom, parameter flash, atau memicu ketuk untuk memfokuskan. Parameter ini mungkin tidak kompatibel dengan implementasi ekstensi Anda.

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

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

Jika HAL kamera memproses ekstensi, Camera2/X akan mengambil hasil pengambilan di CameraCaptureSession.CaptureCallback. Namun, jika pemroses diimplementasikan, Camera2/X akan mengambil hasil pengambilan gambar 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. Pada extensions-interface 1.3.0 atau yang 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 operasi kamera umum seperti zoom, ketuk untuk memfokuskan, flash, dan kompensasi eksposur, sebaiknya dukung tombol berikut untuk permintaan perekaman dan hasil perekaman:

  • Zoom:
    • CaptureRequest#CONTROL_ZOOM_RATIO
    • CaptureRequest#SCALER_CROP_REGION
  • Ketuk untuk memfokuskan:
    • CaptureRequest#CONTROL_AF_MODE
    • CaptureRequest#CONTROL_AF_TRIGGER
    • CaptureRequest#CONTROL_AF_REGIONS
    • CaptureRequest#CONTROL_AE_REGIONS
    • CaptureRequest#CONTROL_AWB_REGIONS
  • Flash:
    • CaptureRequest#CONTROL_AE_MODE
    • CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
    • CaptureRequest#FLASH_MODE
  • Exposure compensation:
    • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Untuk Extender Dasar yang menerapkan versi 1.2.0 atau yang lebih lama, CameraX Extensions API secara eksplisit mendukung semua kunci di atas. Untuk extensions-interface 1.3.0, CameraX dan Camera2 mematuhi daftar yang ditampilkan dan hanya mendukung kunci yang ada di dalamnya. Misalnya, jika Anda memutuskan untuk hanya menampilkan CaptureRequest#CONTROL_ZOOM_RATIO dan CaptureRequest#SCALER_CROP_REGION dalam implementasi 1.3.0, berarti hanya zoom yang didukung untuk aplikasi, sedangkan ketuk untuk memfokuskan, flash, dan kompensasi eksposi tidak diizinkan.

Advanced Extender

Advanced Extender adalah jenis implementasi vendor berdasarkan Camera2 API. 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 streaming kustom: Mengonfigurasi streaming kustom seperti streaming RAW atau memiliki beberapa streaming untuk ID kamera fisik yang berbeda.

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

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

File yang akan diterapkan

Untuk beralih ke implementasi Advanced Extender, metode isAdvancedExtenderImplemented() di ExtensionVersionImpl harus menampilkan true. Untuk setiap jenis ekstensi, OEM harus mengimplementasikan class Extender yang sesuai. File implementasi Advanced Extender berada dalam paket advanced.

Class ekstensi yang akan diimplementasikan
Malam advanced/NightAdvancedExtenderImpl.java
HDR advanced/HdrAdvancedExtenderImpl.java
Otomatis advanced/AutoAdvancedExtenderImpl.java
Bokeh advanced/BokehAdvancedExtenderImpl.java
Retouch Wajah advanced/BeautyAdvancedExtenderImpl.java

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

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

Alur aplikasi 1: Memeriksa ketersediaan ekstensi

AdvancedAppFlow1

Gambar 8. Alur aplikasi 1 di Advanced Extender

Pertama, aplikasi akan memeriksa apakah ekstensi yang diberikan didukung.

Alur aplikasi 2: Informasi kueri

AppFlow2 Lanjutan

Gambar 9. Alur aplikasi 2 di Advanced Extender

Setelah memanggil AdvancedExtenderImpl.init(), aplikasi dapat mengkueri informasi berikut di AdvancedExtenderImpl:

  • Perkiraan latensi pengambilan gambar diam: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() menampilkan rentang latensi pengambilan gambar untuk aplikasi guna mengevaluasi apakah perlu mengaktifkan ekstensi untuk skenario saat ini.

  • Resolusi yang didukung untuk pratinjau dan gambar diam:

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

    • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() menampilkan format dan ukuran yang didukung untuk platform pengambilan gambar diam. OEM harus mendukung output format JPEG dan YUV_420_888.

    • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() menampilkan ukuran yang didukung untuk streaming YUV_420_888 tambahan untuk analisis gambar. Jika platform YUV analisis gambar tidak didukung, getSupportedYuvAnalysisResolutions() akan menampilkan 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 gambar dan kunci hasil yang didukung dari penerapan Anda:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys

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

Alur aplikasi 3: Pratinjau/pengambilan gambar diam dengan ekstensi diaktifkan

AdvancedAppFlow3

Gambar 10. Alur aplikasi 3 di Advanced Extender

Diagram di atas menunjukkan alur utama untuk memulai pratinjau dan masih merekam untuk jenis Advanced Extender. Mari kita bahas satu per satu.

  1. Instance SessionProcessorImpl

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

  2. initSession

    SessionProcessorImpl.initSession() melakukan inisialisasi sesi untuk ekstensi. Di sinilah Anda mengalokasikan resource dan menampilkan konfigurasi sesi untuk menyiapkan CameraCaptureSession.

    Untuk parameter input, Camera2/X menentukan konfigurasi platform output untuk pratinjau, perekaman gambar diam, dan analisis gambar YUV opsional. Konfigurasi platform output ini (OutputSurfaceImpl) berisi platform, ukuran, dan format gambar yang diambil dengan mengikuti metode di AdvancedExtenderImpl:

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

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

    • Pemrosesan di HAL kamera: Anda dapat langsung menambahkan platform output ke CameraCaptureSession dengan implementasi SurfaceOutputConfigImpl. Tindakan ini mengonfigurasi platform output yang disediakan ke pipeline kamera dan memungkinkan HAL kamera memproses gambar.

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

      Anda perlu memproses gambar perantara dan menulis gambar hasilnya ke platform output.

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

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

  3. onCaptureSessionStart dan RequestProcessorImpl

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

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

    • Platform target ditentukan oleh ID instance Camera2OutputConfigImpl.
    • Kemampuan mengambil gambar 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. Memulai pratinjau dan mengambil gambar

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

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

    Anda harus mendukung minimal CaptureRequest.JPEG_ORIENTATION dan CaptureRequest.JPEG_QUALITY. extensions-interface 1.3.0 mendukung kunci permintaan dan hasil, yang ditampilkan oleh metode berikut:

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

    Saat developer menetapkan 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 yang tidak diiklankan di AdvancedExtenderImpl.getAvailableCaptureRequestKeys().

    startTrigger() telah didukung sejak extensions-interface 1.3.0. Hal ini memungkinkan aplikasi menerapkan ketuk untuk memfokuskan dan berkedip dengan ekstensi.

  6. Pembersihan

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

Mendukung pratinjau, pengambilan gambar diam, dan analisis gambar

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

Untuk jenis Basic Extender, terlepas dari apakah ekstensi diaktifkan untuk pratinjau, Anda harus mengimplementasikan ImageCaptureExtenderImpl dan PreviewExtenderImpl untuk ekstensi tertentu. Sering kali, aplikasi juga menggunakan streaming YUV untuk menganalisis konten gambar seperti menemukan kode QR atau teks. Untuk mendukung kasus penggunaan ini dengan lebih baik, Anda harus mendukung kombinasi streaming pratinjau, pengambilan gambar diam, dan streaming YUV_420_888 untuk mengonfigurasi CameraCaptureSession. Artinya, jika Anda menerapkan prosesor, Anda harus mendukung kombinasi streaming dari tiga streaming YUV_420_888.

Untuk Advanced Extender, Camera2/X meneruskan tiga platform output ke panggilan SessionProcessorImpl.initSession(). Platform output ini masing-masing ditujukan untuk pratinjau, pengambilan gambar diam, dan analisis gambar. Anda harus memastikan bahwa pratinjau dan masih mengambil platform output menampilkan output yang valid. Namun, untuk platform output analisis gambar, pastikan platform tersebut hanya berfungsi jika non-null. Jika implementasi Anda tidak dapat mendukung streaming analisis gambar, Anda dapat menampilkan daftar kosong di AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). Hal ini memastikan platform output analisis gambar selalu null di SessionProcessorImpl.initSession().

Mendukung perekaman video

Arsitektur Ekstensi Kamera saat ini hanya mendukung kasus penggunaan pratinjau dan pengambilan foto. Kami tidak mendukung pengaktifan ekstensi di platform MediaCodec atau MediaRecorder untuk merekam video. Namun, aplikasi mungkin dapat merekam output pratinjau.

Mendukung platform MediaCodec dan MediaRecorder sedang dalam penyelidikan.

Metadata khusus ekstensi

Untuk Android 14 dan yang lebih baru, metadata khusus ekstensi memungkinkan klien ekstensi kamera menetapkan dan menerima setelan dan hasil permintaan pengambilan khusus ekstensi. Secara khusus, klien ekstensi kamera dapat menggunakan parameter permintaan pengambilan EXTENSION_STRENGTH untuk mengontrol kekuatan ekstensi dan hasil pengambilan EXTENSION_CURRENT_TYPE untuk menunjukkan jenis ekstensi yang diaktifkan.

Menangkap permintaan

Parameter permintaan pengambilan EXTENSION_STRENGTH mengontrol kekuatan efek pascapemrosesan ekstensi. Hasil pengambilan yang sesuai menyertakan nilai kekuatan default jika parameter ini tidak ditetapkan secara eksplisit oleh klien. Parameter ini dapat diterapkan sebagai berikut untuk jenis ekstensi berikut:

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

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

Untuk menambahkan dukungan bagi EXTENSION_STRENGTH, gunakan API parameter khusus vendor yang diperkenalkan di antarmuka library ekstensi versi 1.3.0. Untuk informasi selengkapnya, lihat getAvailableCaptureRequestKeys().

Mengambil hasil

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

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

Estimasi latensi pengambilan gambar diam real-time

Untuk Android 14 dan yang lebih tinggi, klien ekstensi kamera dapat mengkueri estimasi latensi pengambilan gambar diam secara real time berdasarkan kondisi adegan dan lingkungan menggunakan getRealtimeStillCaptureLatency(). Metode ini memberikan estimasi yang lebih akurat daripada metode getEstimatedCaptureLatencyRangeMillis() statis. Berdasarkan estimasi latensi, aplikasi dapat memutuskan untuk melewati pemrosesan ekstensi atau menampilkan indikasi untuk memberi tahu pengguna tentang operasi yang 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 estimasi latensi pengambilan gambar diam secara real-time, terapkan hal berikut:

Menangkap callback progres pemrosesan

Untuk Android 14 dan yang lebih tinggi, klien ekstensi kamera dapat menerima callback untuk progres operasi pemrosesan pengambilan gambar statis yang berjalan lama. Aplikasi dapat menampilkan progres 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 callback progres pemrosesan pengambilan, implementasi vendor ekstensi Anda harus memanggil callback berikut dengan nilai progres saat ini:

Still capture pasca-penayangan

Untuk Android 14 dan yang lebih tinggi, ekstensi kamera dapat menyediakan postview (gambar pratinjau) menggunakan setPostviewOutputConfiguration. Untuk meningkatkan pengalaman pengguna, aplikasi dapat menampilkan gambar postview sebagai placeholder saat ekstensi mengalami peningkatan latensi pemrosesan, dan mengganti gambar saat gambar akhir tersedia. Aplikasi dapat mengonfigurasi dan mengeluarkan permintaan pengambilan 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 pengambilan gambar diam pasca-penayangan, penerapan vendor Anda harus menerapkan hal berikut:

Mendukung output SurfaceView

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

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

Jenis sesi khusus vendor

Fitur ini memungkinkan penerapan ekstensi vendor untuk memilih jenis sesi khusus vendor yang akan ditetapkan dalam sesi pengambilan gambar kamera internal, bukan nilai default.

Fitur ini berfungsi sepenuhnya dalam framework dan stack vendor serta tidak memiliki dampak API yang terlihat oleh klien/publik.

Untuk memilih jenis sesi khusus vendor, terapkan hal berikut untuk library ekstensi Anda: * ExtenderStateListener.onSessionType() untuk ekstensi dasar * Camera2SessionConfigImpl.getSessionType() untuk ekstensi lanjutan

Histori versi antarmuka ekstensi

Tabel berikut menunjukkan histori versi antarmuka Ekstensi Kamera. Anda harus selalu menerapkan library vendor dengan versi terbaru.

Versi Fitur yang ditambahkan
1.0.0
  • Verifikasi versi
    • ExtensionVersionImpl
  • Perluasan Dasar
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • Inisialisasi library
    • InitializerImpl
  • Mengekspos resolusi yang didukung
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • AdvancedExtender
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • Mendapatkan perkiraan latensi pengambilan
    • ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange
1.3.0
  • Mengekspos kunci permintaan pengambilan/kunci hasil yang didukung
    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys dan getAvailableCaptureResultKeys
    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys dan getAvailableCaptureResultKeys
    • Panggilan process() baru yang menggunakan ProcessResultImpl di PreviewImageProcessorImpl dan CaptureProcessorImpl
    • Mendukung permintaan jenis pemicu
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Metadata khusus ekstensi
  • Estimasi latensi pengambilan gambar diam dinamis
  • Merekam callback progres pemrosesan
  • Still capture pasca-penayangan
  • Dukungan untuk output SurfaceView
  • Jenis sesi khusus vendor

Penerapan referensi

Implementasi library vendor OEM referensi berikut tersedia di frameworks/ex.

  • advancedSample: Implementasi dasar Advanced Extender.

  • sample: Implementasi dasar Basic Extender.

  • service_based_sample: Implementasi yang menunjukkan cara menghosting Ekstensi Kamera di Service. Implementasi ini berisi komponen berikut:

    • oem_library: Library OEM Ekstensi Kamera untuk Camera2 dan CameraX Extensions API yang mengimplementasikan Extensions-Interface. Ini berfungsi sebagai passthrough yang meneruskan panggilan dari Extensions-Interface ke layanan. Library ini juga menyediakan file AIDL dan class wrapper untuk berkomunikasi dengan layanan.

      Advanced Extender diaktifkan secara default. Untuk mengaktifkan Basic Extender, ubah ExtensionsVersionImpl#isAdvancedExtenderImplemented agar menampilkan false.

    • extensions_service: Contoh penerapan Layanan Ekstensi. Tambahkan penerapan Anda di sini. Antarmuka yang akan diimplementasikan dalam layanan mirip dengan Extensions-Interface. Misalnya, menerapkan IAdvancedExtenderImpl.Stub akan melakukan operasi yang sama dengan AdvancedExtenderImpl. ImageWrapper dan TotalCaptureResultWrapper diperlukan untuk membuat Image dan TotalCaptureResult dapat di-parcelle.

Menyiapkan library vendor di perangkat

Library vendor OEM tidak terintegrasi dalam aplikasi; library ini dimuat dari perangkat saat runtime oleh Camera2/X. Di CameraX, tag <uses-library> mendeklarasikan bahwa library androidx.camera.extensions.impl, yang ditentukan dalam file AndroidManifest.xml dari library camera-extensions, adalah dependensi CameraX dan harus dimuat saat runtime. Di Camera2, framework memuat layanan ekstensi yang juga mendeklarasikan bahwa <uses-library> memuat library androidx.camera.extensions.impl yang sama saat runtime.

Hal ini memungkinkan aplikasi pihak ketiga yang menggunakan ekstensi untuk otomatis memuat library vendor OEM. Library OEM ditandai sebagai opsional sehingga aplikasi dapat berjalan di perangkat yang tidak memiliki library tersebut di perangkat. Camera2/X menangani perilaku ini secara otomatis saat aplikasi mencoba menggunakan ekstensi kamera selama produsen perangkat menempatkan library OEM di perangkat sehingga dapat ditemukan oleh aplikasi.

Untuk menyiapkan library OEM di 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 dalam direktori ini memberikan pemetaan library yang dinamai di <uses-library> ke jalur file sebenarnya di perangkat.

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

    • name harus androidx.camera.extensions.impl karena itulah library yang ditelusuri CameraX.
    • file adalah jalur absolut 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 yang lebih baru, perangkat yang mendukung ekstensi CameraX harus memiliki properti ro.camerax.extensions.enabled yang ditetapkan ke true, yang memungkinkan kueri apakah perangkat mendukung ekstensi. Untuk melakukannya, tambahkan baris berikut dalam file pembuatan perangkat:

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

Validasi

Untuk menguji penerapan library vendor OEM selama tahap pengembangan, gunakan aplikasi contoh di androidx-main/camera/integration-tests/extensionstestapp/, yang berjalan melalui berbagai ekstensi vendor.

Setelah Anda menyelesaikan implementasi, gunakan alat validasi ekstensi kamera untuk menjalankan pengujian otomatis dan manual guna memverifikasi bahwa library vendor diterapkan dengan benar.

Mode adegan yang diperluas versus ekstensi kamera

Untuk ekstensi bokeh, selain mengeksposnya menggunakan ekstensi kamera, Anda dapat mengekspos ekstensi tersebut menggunakan mode scene yang diperluas, yang diaktifkan melalui tombol CONTROL_EXTENDED_SCENE_MODE. Untuk detail penerapan selengkapnya, lihat Bokeh kamera.

Mode adegan yang diperluas memiliki batasan yang lebih sedikit dibandingkan dengan ekstensi kamera untuk aplikasi camera2. Misalnya, Anda dapat mengaktifkan mode scene yang diperluas dalam instance CameraCaptureSession reguler yang mendukung kombinasi streaming fleksibel dan mengambil parameter permintaan. Sebaliknya, ekstensi kamera hanya mendukung serangkaian jenis streaming tetap dan memiliki dukungan terbatas untuk parameter permintaan rekaman.

Kelemahan mode scene yang diperluas adalah Anda hanya dapat menerapkannya di HAL kamera, yang berarti mode tersebut harus diverifikasi agar berfungsi di semua kontrol ortogonal yang tersedia untuk developer aplikasi.

Sebaiknya ekspos bokeh menggunakan mode adegan yang diperluas dan Ekstensi Kamera karena aplikasi mungkin lebih memilih menggunakan API tertentu untuk mengaktifkan bokeh. Sebaiknya gunakan mode scene yang diperluas terlebih dahulu karena ini adalah cara yang paling fleksibel bagi aplikasi untuk mengaktifkan ekstensi bokeh. Kemudian, Anda dapat mengimplementasikan antarmuka ekstensi kamera berdasarkan mode scene yang diperluas. Jika menerapkan bokeh di HAL kamera sulit, misalnya, karena memerlukan post processor yang berjalan di lapisan aplikasi untuk memproses gambar, sebaiknya terapkan ekstensi bokeh menggunakan antarmuka Ekstensi Kamera.

Pertanyaan Umum (FAQ)

Apakah ada batasan pada level API?

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