Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Halaman ini diterjemahkan oleh Cloud Translation API.

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 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:

Gambar 1. Diagram arsitektur Ekstensi Kamera

Seperti yang ditunjukkan dalam diagram, untuk mendukung Ekstensi Kamera, Anda perlu menerapkan 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 dalam project library sistem. File ini menentukan antarmuka Ekstensi Kamera.

File camera-extensions-stub dibagi menjadi 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 ekstender 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 diwajibkan untuk 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. Implementasi ekstensi malam

Verifikasi versi:

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

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

Membuat instance class Extender untuk ekstensi. Ada dua jenis Pengekstensi: Pengekstensi Dasar dan Pengekstensi Lanjutan. 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 Night, class Extender berikut dibuat instance-nya untuk jenis Basic Extender:
- NightImageCaptureExtenderImpl.java
- NightPreviewExtenderImpl.java
Dan untuk jenis Advanced Extender:
- NightAdvancedExtenderImpl.java
Periksa ketersediaan ekstensi:

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

Camera2/X memanggil init() pada instance Extender dan meneruskan ID kamera dan CameraCharacteristics.
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.
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() di 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 antarmuka ekstensi berbeda antara Camera2/X dan library vendor, maka dianggap tidak kompatibel dan ekstensi 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.

Ekstensi Dasar versus Ekstensi Lanjutan

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	Advanced Extender
Konfigurasi streaming	Tetap Pratinjau: `PRIVATE` atau `YUV_420_888` (jika prosesor ada) Perekaman diam: `JPEG` atau `YUV_420_888` (jika prosesor ada)	Dapat disesuaikan oleh OEM.
Mengirim permintaan pengambilan	Hanya Camera2/X yang dapat mengirim permintaan pengambilan. 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 hasil pengambilan ke prosesor.	Instance `RequestProcessorImpl` disediakan untuk Anda guna menjalankan permintaan pengambilan camera2 dan mendapatkan hasil serta 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 di prosesor yang memproses gambar YUV.	Memiliki implementasi berbasis Camera2 untuk ekstensi. Memerlukan konfigurasi streaming yang disesuaikan seperti streaming RAW. Memerlukan urutan pengambilan Interaktif.
Versi API yang didukung	Ekstensi Camera2: Android 13 atau yang lebih tinggi Ekstensi CameraX: `camera-extensions` 1.1.0 atau yang lebih tinggi	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

	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, ...)`

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 dalam 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 ekstender yang akan diterapkan
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:

Masukkan 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 Basic Extender

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

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

Alur aplikasi 2: Informasi kueri

BasicExtenderAppFlow2

Gambar 4. Alur aplikasi 2 di Basic Extender

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 pratinjau dan platform 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 di class Extender ini sebelum membuat kueri untuk 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 pengambilan gambar statis 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 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 satu permintaan 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 pemroses. 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. Tindakan ini akan menulis output ke format pratinjau PRIVATE. Camera2/X menggunakan platform YUV_420_888, bukan PRIVATE, untuk mengonfigurasi CameraCaptureSession untuk pratinjau.

Lihat ilustrasi berikut untuk mengetahui alur:

PreviewProcessor

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 mengasumsikan bahwa pratinjau diaktifkan dan berjalan sebelum mengirim permintaan pengambilan gambar diam.

Lihat alur dalam diagram di bawah:

CaptureProcessor

Gambar 7. Masih merekam alur dengan CaptureProcessorImpl

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

Catatan: getCaptureStages() diizinkan untuk menampilkan lebih dari satu instance CaptureStageImpl hanya jika getCaptureProcessor() menampilkan instance.
Gambar yang diterima dan instance TotalCaptureResult digabungkan dan dikirim ke CaptureProcessorImpl untuk diproses.
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 mengekspos parameter yang didukung implementasi 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 prosesor diimplementasikan, Camera2/X akan mengambil hasil pengambilan di ProcessResultImpl , yang diteruskan ke metode process() di PreviewImageProcessorImpl dan CaptureProcessorImpl. Anda bertanggung jawab untuk melaporkan hasil pengambilan melalui ProcessResultImpl ke Camera2/X.

Lihat definisi antarmuka CaptureProcessorImpl di bawah sebagai contoh. Di extensions-interface 1.3.0 atau yang lebih baru, 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 dapat diterapkan di 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 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 secara on demand.

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 Extender yang akan diterapkan
Malam	`advanced/NightAdvancedExtenderImpl.java`
HDR	`advanced/HdrAdvancedExtenderImpl.java`
Otomatis	`advanced/AutoAdvancedExtenderImpl.java`
Bokeh	`advanced/BokehAdvancedExtenderImpl.java`
Retouch Wajah	`advanced/BeautyAdvancedExtenderImpl.java`

Kita 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

AdvancedAppFlow2

Gambar 9. Alur aplikasi 2 di Advanced Extender

Setelah memanggil AdvancedExtenderImpl.init(), aplikasi dapat membuat kueri berikut informasi 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 pengambilan 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 gambar 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 implementasi Anda:
- AdvancedExtenderImpl.getAvailableCaptureRequestKeys
- AdvancedExtenderImpl.getAvailableCaptureResultKeys

Untuk informasi selengkapnya, lihat Mendukung kunci dan hasil 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 tetap merekam untuk jenis Advanced Extender. Mari kita bahas satu per satu.

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.

Catatan: Sesi kamera dapat menggunakan instance SessionProcessorImpl beberapa kali. Akibatnya, implementasi harus dapat mendukung beberapa panggilan initSession() dan deInitSession() untuk satu instance SessionProcessorImpl.
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.
Catatan: Camera2/X membuat dan mengelola instance ImageReader untuk Anda. Anda dapat menetapkan instance ImageProcessorImpl untuk mengambil gambar.
- 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.
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.

RequestProcessImpl API mirip dengan Camera2 CameraCaptureSession API 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().
Memulai pratinjau dan mengambil gambar

Dalam penerapan Advanced Extender, Anda dapat mengirim permintaan pengambilan 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.
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.
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 menerapkan 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 penerapan 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 dapat merekam output pratinjau.

Dukungan untuk platform MediaCodec dan MediaRecorder sedang diselidiki.

Metadata khusus ekstensi

Untuk Android 14 dan yang lebih tinggi, metadata khusus ekstensi memungkinkan klien ekstensi kamera menetapkan dan menerima setelan dan hasil permintaan perekaman 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 digabungkan dan kecerahan gambar akhir.
FACE_RETOUCH: Mengontrol jumlah peningkatan kosmetik dan penghalusan 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:

Ekstensi dasar: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
Ekstensi lanjutan: SessionProcessorImpl.getRealtimeCaptureLatency

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:

Ekstensi dasar: ProcessResultImpl.onCaptureProcessProgressed()
Ekstensi lanjutan: CaptureCallback.onCaptureProcessProgressed()

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 pasca-tampilan 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:

Ekstensi dasar: CaptureProcessorImpl.onPostviewOutputSurface dan CaptureProcessorImpl.processWithPostview
Ekstensi lanjutan: SessionProcessorImpl.startCaptureWithPostview

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 implementasi ekstensi vendor untuk memilih jenis sesi khusus vendor yang akan ditetapkan dalam sesi pengambilan 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.

Version	Fitur yang ditambahkan
1.0.0	Verifikasi versi `ExtensionVersionImpl` Extender 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/kunci hasil pengambilan yang didukung `ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys` dan `getAvailableCaptureResultKeys` `AdvancedExtenderImpl.getAvailableCaptureRequestKeys` dan `getAvailableCaptureResultKeys` Panggilan `process()` baru yang menggunakan `ProcessResultImpl` di `PreviewImageProcessorImpl` dan `CaptureProcessorImpl` Dukung permintaan jenis pemicu `AdvancedExtenderImpl.startTrigger`
1.4.0	Metadata khusus ekstensi Estimasi latensi pengambilan gambar diam dinamis Menangkap 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 diterapkan 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 di-build ke 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 OEM vendor. Library OEM ditandai sebagai opsional sehingga aplikasi dapat berjalan di perangkat yang tidak memiliki library 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:

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.
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 menyelesaikan penerapan, gunakan alat validasi ekstensi kamera untuk menjalankan pengujian otomatis dan manual guna memverifikasi bahwa library vendor diimplementasikan dengan benar.

Mode scene 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 kunci CONTROL_EXTENDED_SCENE_MODE. Untuk detail penerapan selengkapnya, lihat Bokeh kamera.

Mode scene yang diperluas memiliki lebih sedikit batasan dibandingkan dengan ekstensi kamera untuk aplikasi camera2. Misalnya, Anda dapat mengaktifkan mode scene yang diperluas di instance CameraCaptureSession reguler yang mendukung kombinasi streaming yang fleksibel dan menangkap 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 scene yang diperluas dan Ekstensi Kamera karena aplikasi mungkin lebih memilih untuk menggunakan API tertentu guna 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 di API level 28 dan yang lebih tinggi. Untuk mengetahui detail tentang metode antarmuka tertentu, lihat dokumentasi referensi API.