Ekstensi kamera

Produsen perangkat dapat mengekspos ekstensi seperti bokeh, mode malam, dan HDR kepada 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 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 Ekstensi Kamera interface atau extensions-interface: Arsitektur

Gambar 1. Diagram arsitektur Ekstensi Kamera

Seperti yang ditunjukkan dalam diagram, untuk mendukung Ekstensi Kamera, Anda harus menerapkan extensions-interface yang disediakan oleh library vendor OEM. Nama Library vendor OEM memungkinkan dua API: CameraX Extensions API dan Camera2 Extensions API, yang masing-masing digunakan oleh aplikasi CameraX dan Camera2 untuk mengakses ekstensi vendor.

Menerapkan library vendor OEM

Untuk menerapkan library vendor OEM, salin camera-extensions-stub ke dalam project library sistem. File berikut menentukan Ekstensi Kamera dalam antarmuka berbasis web yang sederhana.

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

File antarmuka penting (jangan dimodifikasi)

  • 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

Class alat ekstensi malam (terapkan jika ekstensi Night 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 alat ekstensi HDR (terapkan jika ekstensi HDR didukung)

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

Class alat ekstensi 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 menerapkan ekstensi, tetapkan isExtensionAvailable() agar menampilkan false atau menghapus class Extender yang sesuai. Ekstensi Camera2 dan CameraX API melaporkan ke aplikasi bahwa ekstensi tidak tersedia.

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

Alur utama

Gambar 2. Implementasi ekstensi malam

  1. Verifikasi versi:

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

  2. Inisialisasi library vendor:

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

  3. Membuat instance class Extender:

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

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

    Untuk ekstensi Night, class Extender berikut dibuat instance-nya untuk tipe Basic Extender:

    • NightImageCaptureExtenderImpl.java
    • NightPreviewExtenderImpl.java

    Dan untuk jenis Advanced Extender:

    • NightAdvancedExtenderImpl.java

  4. Periksa ketersediaan ekstensi:

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

  5. Lakukan inisialisasi Extender dengan informasi kamera:

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

  6. Informasi kueri:

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

  7. Aktifkan ekstensi di Extender:

    Class Extender menyediakan semua antarmuka yang diperlukan untuk mengaktifkan . Produk ini menawarkan mekanisme untuk memikat OEM implementasi ke dalam pipeline Camera2 seperti memasukkan permintaan pengambilan parameter atau mengaktifkan pemroses postingan.

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

Bagian berikut menjelaskan alur ekstensi secara lebih mendetail.

Verifikasi versi

Saat memuat library vendor OEM dari perangkat saat runtime, Camera2/X memastikan apakah library 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 digunakan selama verifikasi versi.

Untuk memverifikasi versi, Camera2/X memanggil ExtensionVersionImpl.checkApiVersion() dengan dukungan Versi extensions-interface. 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 di antara Camera2/X dan pustaka vendor, maka dianggap tidak kompatibel dan ekstensi dinonaktifkan.

Kompatibilitas mundur

Selama versi utamanya identik, Camera2/X memastikan kompatibilitas mundur dengan library vendor OEM yang dibuat dengan extensions-interface versi. 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. Ini juga berarti bahwa setelah Anda menerapkan versi tertentu dari pustaka vendor, Camera2/X memastikan bahwa kompatibel dengan versi extension-interface mendatang.

Kompatibilitas dengan versi baru

Meneruskan kompatibilitas dengan library vendor extensions-interface yang lebih baru bergantung pada Anda, OEM. Jika Anda memerlukan beberapa fitur untuk menerapkan ekstensi, Anda mungkin ingin mengaktifkan ekstensi mulai dari versi tertentu. Di sini ini, Anda dapat menampilkan versi extensions-interface yang didukung saat Versi library Camera2/X memenuhi persyaratan. Jika versi Camera2/X tidak didukung, Anda dapat mengembalikan versi yang tidak kompatibel seperti 99.0.0 ke menonaktifkan ekstensi.

Inisialisasi library vendor

Setelah memverifikasi versi extensions-interface yang diterapkan oleh OEM Camera2/X, lalu memulai proses inisialisasi. Tujuan Metode InitializerImpl.init() memberi tahu library OEM bahwa aplikasi sedang dicoba untuk 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 inisialisasi library jika library vendor OEM menerapkan extensions-interface 1.0.0.

Extender Dasar versus Advanced Extender

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

Terapkan Perluasan Dasar untuk ekstensi yang memproses gambar di HAL kamera atau menggunakan pemroses pasca-prosesor yang mampu memproses streaming YUV.

Menerapkan Advanced Extender untuk ekstensi yang perlu menyesuaikan Camera2 konfigurasi {i>stream <i}dan mengirimkan permintaan tangkapan sesuai kebutuhan.

Lihat tabel berikut untuk perbandingannya:

Ekstensi Dasar Ekstensi Lanjutan
Konfigurasi streaming Tetap
Pratinjau: PRIVATE atau YUV_420_888 (jika prosesor ada)
Masih merekam: 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 mengatur parameter untuk terhadap permintaan ini. Saat prosesor disediakan untuk pengambilan gambar, Camera2/X dapat mengirim beberapa permintaan pengambilan dan mengirim semua gambar dan ke prosesor. Instance RequestProcessorImpl diberikan kepada Anda untuk jalankan permintaan pengambilan kamera2 dan dapatkan hasil serta {i>Image<i}.

Camera2/X memanggil startRepeating dan startCapture aktif SessionProcessorImpl untuk memberi sinyal kepada OEM untuk memulai pengulangan permintaan pratinjau dan memulai urutan perekaman diam.

Hook di pipeline kamera
  • onPresetSession memberikan parameter sesi.
  • onEnableSession mengirimkan satu permintaan tepat setelah CameraCaptureSession dikonfigurasi.
  • onDisableSession mengirim satu permintaan sebelum CameraCaptureSession ditutup.
  • initSession melakukan inisialisasi dan menampilkan camera2 yang disesuaikan konfigurasi sesi untuk membuat sesi penangkapan.
  • onCaptureSessionStart dipanggil tepat setelah CameraCaptureSession dikonfigurasi.
  • onCaptureSessionEnd dipanggil sebelum CameraCaptureSession ditutup.
Cocok untuk Ekstensi yang diterapkan di HAL kamera atau dalam prosesor yang memproses Gambar 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 baru
Ekstensi CameraX: camera-extensions 1.2.0-alpha03 atau yang lebih baru

Alur aplikasi

Tabel berikut menunjukkan tiga jenis alur aplikasi dan alurnya yang sesuai untuk panggilan Camera Extensions API. Sementara Camera2/X menyediakan API ini, Anda harus menerapkan pustaka vendor dengan benar untuk alur, yang akan kami jelaskan secara lebih rinci 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.

Melihat pratinjau dan mengambil 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 kamera {i>pipelines<i} yang sama. Setiap jenis ekstensi memiliki class Extender yang sesuai yang diperlukan OEM untuk diimplementasikan.

Tabel berikut mencantumkan class Extender yang perlu diterapkan OEM untuk setiap class Extender 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 yang sebenarnya yang Anda terapkan.

Basic Extender memiliki kemampuan berikut:

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

Mari kita lihat bagaimana Camera2/X memanggil extensions-interface untuk mencapai ketiga 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 secara langsung memanggil metode isExtensionAvailable() PreviewExtenderImpl dan ImageCaptureExtenderImpl tanpa memanggil init(). Kedua class Extender harus menampilkan true untuk mengaktifkan ekstensi.

Hal ini sering kali menjadi langkah pertama bagi aplikasi untuk memeriksa apakah ekstensi yang diberikan 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 di Extender Dasar

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

  • Masih merekam rentang latensi: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange menampilkan rentang latensi perekaman untuk aplikasi guna mengevaluasi apakah sesuai untuk mengaktifkan ekstensi untuk skenario saat ini.

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

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

    • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
    • ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

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

Alur aplikasi 3: Melihat pratinjau/masih merekam dengan ekstensi diaktifkan (implementasi HAL)

BasicExtenderAppFlow3

Gambar 5. Alur aplikasi 3 di Extender Dasar

Diagram di atas mengilustrasikan alur utama pengaktifan pratinjau dan tetap merekam dengan ekstensi tanpa prosesor apa pun. Ini berarti HAL kamera memproses ekstensi.

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

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

Permintaan berulang yang dipicu oleh Camera2/X berisi parameter permintaan ditampilkan oleh PreviewExtenderImpl.getCaptureStage(). Selain itu, elemen permintaan pengambilan 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 bisa mengimplementasikan ekstensi di prosesor.

Mengimplementasikan 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 terbaru TotalCaptureResult.

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

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

    Anda perlu mengimplementasikan dan menampilkan PreviewImageProcessorImpl di PreviewExtenderImpl.getProcessor. Prosesor bertanggung jawab untuk memproses gambar input YUV_420_888. Fungsi tersebut harus menulis output ke Format pratinjau PRIVATE. Camera2/X menggunakan platform YUV_420_888 sebagai gantinya dari PRIVATE guna mengonfigurasi CameraCaptureSession untuk pratinjau.

    Lihat ilustrasi berikut untuk alurnya:

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 piksel seperti PixelFormat.RGBA_8888.

  • onResolutionUpdate(Size size) menetapkan ukuran gambar input.

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

Prosesor pengambilan gambar

Untuk pengambilan gambar diam, Anda bisa mengimplementasikan prosesor dengan menampilkan CaptureProcessorImpl menggunakan ImageCaptureExtenderImpl.getCaptureProcessor. Prosesornya adalah bertanggung jawab untuk memproses daftar YUV_420_888 gambar yang diambil dan ke instance TotalCaptureResult dan tulis output ke platform YUV_420_888.

Anda dapat berasumsi dengan aman bahwa pratinjau telah diaktifkan dan berjalan sebelum mengirim masih menangkap permintaan.

Lihat alurnya dalam diagram di bawah ini:

CaptureProcessor

Gambar 7. Masih merekam alur dengan CaptureProcessorImpl

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

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

  2. ImageCaptureExtenderImpl.getCaptureStages menampilkan daftar CaptureStageImpl , dengan setiap elemen dipetakan ke instance CaptureRequest dengan parameter tangkapan yang dikirim oleh Camera2/X. Misalnya, jika {i>output<i} yang ditampilkan adalah daftar tiga Instance CaptureStageImpl, Camera2/X mengirimkan tiga permintaan pengambilan parameter penangkapan yang sesuai menggunakan captureBurst Compute Engine API.

  3. Gambar yang diterima dan instance TotalCaptureResult dipaketkan menjadi satu 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 ke dalam gambar JPEG jika diperlukan.

Mendukung kunci dan hasil permintaan pengambilan

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

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

  • ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() akan menampilkan mengambil kunci permintaan yang didukung oleh implementasi Anda.
  • ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() akan menampilkan kunci hasil tangkapan yang terkandung dalam hasil tangkapan.

Jika HAL kamera memproses ekstensi, Camera2/X akan mengambil gambar menghasilkan CameraCaptureSession.CaptureCallback. Namun, jika prosesor diimplementasikan, kemudian Camera2/X mengambil hasil tangkapan di ProcessResultImpl , yang diteruskan ke process() metode di PreviewImageProcessorImpl dan CaptureProcessorImpl. Anda bertanggung jawab untuk melaporkan hasil pengambilan gambar 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 pengoperasian kamera umum seperti zoom, ketuk untuk memfokuskan, flash, dan eksposur kompensasi tersebut, sebaiknya dukung kunci berikut untuk kedua minta dan ambil hasil:

  • 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
  • Kompensasi eksposur:
    • CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Untuk Extender Dasar yang mengimplementasikan 1.2.0 atau versi sebelumnya, CameraX Extensions API secara eksplisit mendukung semua kunci di atas. Sebagai extensions-interface 1.3.0, CameraX dan Camera2 mengikuti daftar yang ditampilkan dan hanya mendukung kunci yang ada di dalamnya. Misalnya, jika Anda memutuskan untuk hanya CaptureRequest#CONTROL_ZOOM_RATIO dan CaptureRequest#SCALER_CROP_REGION dalam implementasi 1.3.0, maka berarti hanya zoom yang didukung untuk aplikasi saat ketuk untuk memfokuskan, flash, dan eksposur kompensasi tidak diizinkan.

Ekstensi Lanjutan

Advanced Extender adalah jenis implementasi vendor yang didasarkan pada Camera2 API. Jenis Extender ini ditambahkan di extensions-interface 1.2.0. Bergantung pada produsen perangkat, ekstensi mungkin diimplementasikan dalam lapisan aplikasi, yang bergantung pada faktor-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 interaksi yang rumit yang dapat mengirim permintaan penangkapan dengan parameter berdasarkan hasil permintaan sebelumnya.

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

File untuk diterapkan

Untuk beralih ke implementasi Advanced Extender, isAdvancedExtenderImplemented() metode di ExtensionVersionImpl harus menampilkan true. Untuk setiap jenis ekstensi, OEM harus menerapkan class Extender yang sesuai. File implementasi Advanced Extender 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 {i>Extender<i} untuk ekstensi yang Anda terapkan.

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

Alur aplikasi 1: Memeriksa ketersediaan ekstensi

AlurAplikasiLanjutan1

Gambar 8. Alur aplikasi 1 di Advanced Extender

Pertama, aplikasi akan memeriksa apakah ekstensi yang diberikan didukung.

Alur aplikasi 2: Informasi kueri

AdvancedAppFlow2

Gambar 9. Alur aplikasi 2 di Advanced Extender

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

  • Perkiraan latensi pengambilan gambar: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() menampilkan rentang latensi pengambilan untuk aplikasi guna mengevaluasi apakah sesuai untuk 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 platform pratinjau dan ukuran. OEM harus mendukung setidaknya format PRIVATE.

    • AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() akan menampilkan format dan ukuran yang didukung untuk permukaan gambar diam. OEM harus mendukung keduanya Output format JPEG dan YUV_420_888.

    • AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() akan menampilkan ukuran yang didukung untuk aliran YUV_420_888 tambahan bagi 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 tangkapan yang didukung kunci permintaan dan kunci hasil dari penerapan Anda:

    • AdvancedExtenderImpl.getAvailableCaptureRequestKeys
    • AdvancedExtenderImpl.getAvailableCaptureResultKeys

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

Alur aplikasi 3: Melihat pratinjau/tetap merekam dengan ekstensi diaktifkan

AdvancedAppFlow3

Gambar 10. Alur aplikasi 3 di Advanced Extender

Diagram di atas menunjukkan alur utama untuk memulai pratinjau dan tetap merekam berjenis Advanced Extender. Mari kita pelajari setiap langkahnya.

  1. Instance SessionProcessorImpl

    Implementasi inti Advanced Extender berada di SessionProcessorImpl, yang bertanggung jawab untuk menyediakan konfigurasi sesi yang disesuaikan dan mengirim merekam permintaan untuk memulai pratinjau dan tetap mencatat permintaan. AdvancedExtenderImpl.createSessionProcessor() dipanggil untuk menampilkan 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 input, Camera2/X menentukan konfigurasi platform output untuk pratinjau, gambar diam, dan analisis gambar YUV opsional. Output ini konfigurasi permukaan (OutputSurfaceImpl) berisi permukaan, ukuran, dan gambar format yang diambil dengan metode berikut 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 terhadap yang menghasilkan gambar kamera yang benar ke permukaan output yang diteruskan oleh Kamera2/X. Berikut beberapa opsi untuk mengaktifkan output:

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

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

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

    • Menggunakan fitur berbagi platform Camera2: Menggunakan berbagi platform dengan platform lain dengan menambahkan instance Camera2OutputConfigImpl ke Metode getSurfaceSharingOutputConfigs() dari yang lain Camera2OutputConfigImpl. Format dan ukuran platform harus identik.

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

  3. onCaptureSessionStart dan RequestProcessorImpl

    Saat CameraCaptureSession dimulai dan framework Kamera memanggil onConfigured(), lalu Camera2/X memanggil SessionProcessorImpl.onCaptureSessionStart() dengan permintaan Camera2 pembungkus RequestProcessImpl. Camera2/X mengimplementasikan RequestProcessImpl, yang memungkinkan Anda mengeksekusi permintaan pengambilan, dan ambil gambar jika ImageReaderOutputConfigImpl digunakan.

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

    • Platform target ditetapkan oleh ID platform Instance Camera2OutputConfigImpl.
    • Kemampuan mengambil gambar ImageReader.

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

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

  4. Memulai pratinjau dan mengambil gambar

    Dalam implementasi Advanced Extender, Anda bisa mengirim permintaan pengambilan gambar 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 masing-masing. Anda harus mengirimkan rekaman untuk memenuhi permintaan pratinjau dan perekaman diam ini.

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

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

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

    Saat developer menetapkan kunci dalam daftar getAvailableCaptureRequestKeys, Anda harus mengaktifkan parameter dan memastikan bahwa berisi kunci dalam daftar getAvailableCaptureResultKeys.

  5. startTrigger

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

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

  6. Pembersihan

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

Mendukung pratinjau, pengambilan gambar diam, dan analisis gambar

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

Untuk jenis Basic Extender, meskipun 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 lebih mendukung kasus penggunaan ini , Anda harus mendukung kombinasi streaming pratinjau, diam, dan aliran YUV_420_888 untuk mengonfigurasi CameraCaptureSession. Artinya jika Anda mengimplementasikan prosesor, maka Anda harus mendukung aliran data kombinasi dari tiga aliran data YUV_420_888.

Untuk Advanced Extender, Camera2/X meneruskan tiga permukaan output ke Panggilan SessionProcessorImpl.initSession(). Platform output ini adalah untuk pratinjau , gambar diam, dan analisis gambar. Anda harus memastikan bahwa pratinjau dan tetap merekam platform output menampilkan output yang valid. Namun, untuk gambar permukaan output analisis, pastikan objek itu hanya berfungsi jika nilainya bukan {i>null<i}. Jika tidak dapat mendukung aliran data analisis gambar, Anda dapat menampilkan output kosong daftar di AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). Ini memastikan platform output analisis gambar selalu null di SessionProcessorImpl.initSession().

Mendukung perekaman video

Arsitektur Ekstensi Kamera saat ini hanya mendukung pratinjau dan tetap menangkap kasus penggunaan. Kami tidak mendukung pengaktifan ekstensi di MediaCodec atau MediaRecorder untuk merekam video. Namun, mungkin saja agar aplikasi 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 pengambilan gambar khusus ekstensi setelan dan hasil permintaan. Secara khusus, ekstensi kamera klien dapat menggunakan parameter permintaan pengambilan EXTENSION_STRENGTH untuk mengontrol kekuatan ekstensi dan hasil pengambilan EXTENSION_CURRENT_TYPE untuk menunjukkan jenis ekstensi yang diaktifkan.

Mencatat permintaan

Tujuan EXTENSION_STRENGTH ambil parameter permintaan mengontrol kekuatan efek pascapemrosesan ekstensi. Model hasil tangkapan mencakup nilai kekuatan default jika parameter ini tidak disetel secara eksplisit oleh klien. Parameter ini dapat diterapkan sebagai berikut untuk jenis ekstensi:

  • BOKEH: Mengontrol tingkat blur.
  • HDR dan NIGHT: Mengontrol jumlah gambar yang menyatu dan kecerahan gambar akhir.
  • FACE_RETOUCH: Mengontrol jumlah peningkatan kosmetik dan kulit {i>smoothing.<i}

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

Guna menambahkan dukungan untuk EXTENSION_STRENGTH, gunakan vendor API parameter spesifik yang diperkenalkan dalam library ekstensi versi 1.3.0 dalam antarmuka berbasis web yang sederhana. Untuk informasi selengkapnya, lihat getAvailableCaptureRequestKeys().

Mengambil hasil

Tujuan EXTENSION_CURRENT_TYPE hasil tangkapan memungkinkan penerapan ekstensi memberi tahu klien tentang jenis ekstensi.

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

Estimasi latensi pengambilan gambar real-time

Untuk Android 14 dan yang lebih baru, klien ekstensi kamera dapat mengkueri real-time masih dapat menangkap perkiraan latensi berdasarkan scene dan kondisi lingkungan menggunakan getRealtimeStillCaptureLatency() Ini memberikan estimasi yang lebih akurat dibandingkan metode statis getEstimatedCaptureLatencyRangeMillis() . Berdasarkan estimasi latensi, aplikasi dapat memutuskan untuk melewati ekstensi atau menampilkan indikasi untuk memberi tahu pengguna tentang yang sedang berjalan.

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 yang masih direkam secara real-time, terapkan hal berikut:

Merekam callback progres pemrosesan

Untuk Android 14 dan yang lebih baru, klien ekstensi kamera dapat menerima callback untuk kemajuan pemrosesan tangkapan yang masih berjalan lama operasional bisnis. 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, vendor ekstensi Anda harus memanggil callback berikut dengan progres saat ini nilai:

Postview masih ditangkap

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

Mendukung output SurfaceView

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

Untuk mendukung output SurfaceView, implementasi ekstensi vendor Anda harus yang mampu melakukan streaming dan menghasilkan output berupa pratinjau ke instance SurfaceView. Kepada memastikan bahwa skrip ini didukung, jalankan SurfaceViewExtensionPreviewTest.java modul CTS.

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 tambahan
1.0.0
  • Verifikasi versi
    • ExtensionVersionImpl
  • Ekstensi Dasar
    • PreviewExtenderImpl
    • ImageCaptureExtenderImpl
    • Processor
      • PreviewImageProcessorImpl
      • CaptureProcessorImpl
      • RequestUpdateProcessorImpl
1.1.0
  • Inisialisasi library
    • InitializerImpl
  • Mengekspos resolusi yang didukung
    • PreviewExtenderImpl.getSupportedResolutions
    • ImageCaptureExtenderImpl.getSupportedResolutions
1.2.0
  • Perpanjangan Lanjutan
    • AdvancedExtenderImpl
    • SessionProcessorImpl
  • Mendapatkan perkiraan latensi perekaman
    • 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 melakukan ProcessResultImpl dalam PreviewImageProcessorImpl dan CaptureProcessorImpl
    • Mendukung permintaan jenis pemicu
      • AdvancedExtenderImpl.startTrigger
1.4.0
  • Metadata khusus ekstensi
  • Estimasi latensi pengambilan gambar dinamis tetap
  • Merekam callback progres pemrosesan
  • Postview masih ditangkap
  • Dukungan untuk output SurfaceView
  • Jenis sesi khusus vendor

Penerapan referensi

Penerapan library vendor OEM referensi berikut tersedia di frameworks/ex

  • advancedSample: Implementasi dasar Advanced Extender.

  • sample: Implementasi dasar Extender Dasar.

  • 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 bertindak 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 untuk menampilkan false.

    • extensions_service: Contoh implementasi Layanan Ekstensi. Tambahkan penerapan Anda di sini. Antarmuka yang akan diimplementasikan dalam layanan ini serupa ke Extensions-Interface. Misalnya, menerapkan IAdvancedExtenderImpl.Stub menjalankan operasi yang sama dengan AdvancedExtenderImpl. ImageWrapper dan TotalCaptureResultWrapper adalah diperlukan agar Image dan TotalCaptureResult dapat dibagikan.

Menyiapkan library vendor di perangkat

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

Hal ini memungkinkan aplikasi pihak ketiga yang menggunakan ekstensi untuk memuat OEM secara otomatis library vendor. Library OEM ditandai sebagai opsional sehingga aplikasi dapat berjalan di perangkat yang tidak memiliki {i>library <i}di perangkat. Camera2/X menangani perilaku ini secara otomatis saat aplikasi mencoba menggunakan kamera selama produsen perangkat menempatkan library OEM pada 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. Sebagai contoh, /etc/permissions/camera_extensions.xml. File dalam menyediakan pemetaan library yang dinamai di <uses-library> ke jalur file yang sebenarnya di perangkat.

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

    • name harus androidx.camera.extensions.impl karena library yang ditelusuri CameraX.
    • file adalah jalur absolut file yang berisi penerapan 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 CameraX ekstensi harus memiliki properti ro.camerax.extensions.enabled yang ditetapkan ke true, yang memungkinkan kueri apakah perangkat mendukung ekstensi. Untuk melakukannya, tambahkan baris berikut di 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 pustaka vendor diimplementasikan dengan benar.

Mode adegan yang diperluas versus ekstensi kamera

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

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

Kelemahan mode adegan yang diperluas adalah Anda hanya bisa menerapkannya dalam kamera HAL, yang berarti bahwa itu harus diverifikasi agar berfungsi di semua kontrol ortogonal yang tersedia untuk developer aplikasi.

Sebaiknya eksposur bokeh menggunakan mode pemandangan yang diperluas dan Kamera Ekstensi karena aplikasi mungkin lebih memilih menggunakan API tertentu untuk mengaktifkan bokeh. Sebaiknya gunakan mode pemandangan yang diperluas terlebih dahulu karena ini adalah fleksibel bagi aplikasi untuk mengaktifkan ekstensi bokeh. Selanjutnya Anda dapat menerapkan antarmuka ekstensi kamera berdasarkan mode adegan yang diperluas. Jika menerapkan bokeh di HAL kamera itu sulit, misalnya, karena memerlukan posting yang berjalan di lapisan aplikasi untuk memproses gambar, sebaiknya terapkan ekstensi bokeh menggunakan antarmuka Camera Extensions.

Pertanyaan Umum (FAQ)

Apakah ada batasan pada level API?

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