Kể từ ngày 27 tháng 3 năm 2025, bạn nên sử dụng android-latest-release thay vì aosp-main để xây dựng và đóng góp cho AOSP. Để biết thêm thông tin, hãy xem phần Thay đổi đối với AOSP.

Trang này được dịch bởi Cloud Translation API.

Tiện ích Camera

Nhà sản xuất thiết bị có thể cung cấp các tiện ích như hiệu ứng bokeh, chế độ ban đêm và HDR cho nhà phát triển bên thứ ba thông qua giao diện Tiện ích camera do thư viện nhà cung cấp OEM cung cấp. Nhà phát triển có thể sử dụng Camera2 Extensions API và CameraX Extensions API để truy cập vào các tiện ích được triển khai trong thư viện nhà cung cấp OEM.

Để biết danh sách các tiện ích được hỗ trợ (giống nhau trên Camera2 và CameraX), hãy xem CameraX Extensions API. Nếu bạn muốn thêm một tiện ích, hãy báo cáo lỗi bằng Trình theo dõi vấn đề.

Trang này mô tả cách triển khai và bật thư viện nhà cung cấp OEM trên các thiết bị.

Kiến trúc

Sơ đồ sau đây mô tả cấu trúc của giao diện Camera Extensions hoặc extensions-interface: Kiến trúc

Hình 1. Sơ đồ cấu trúc của các tiện ích máy ảnh

Như trong sơ đồ, để hỗ trợ Tiện ích máy ảnh, bạn cần triển khai extensions-interface do thư viện nhà cung cấp OEM cung cấp. Thư viện nhà cung cấp OEM của bạn cho phép 2 API: CameraX Extensions API và Camera2 Extensions API. Các API này được ứng dụng CameraX và Camera2 dùng để truy cập vào các tiện ích của nhà cung cấp.

Triển khai thư viện nhà cung cấp OEM

Để triển khai thư viện của nhà cung cấp OEM, hãy sao chép các tệp camera-extensions-stub vào một dự án thư viện hệ thống. Các tệp này xác định giao diện Camera Extensions.

Các tệp camera-extensions-stub được chia thành các danh mục sau:

Các tệp giao diện thiết yếu (không được sửa đổi)

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

Triển khai bắt buộc (thêm cách triển khai của bạn)

ExtensionVersionImpl.java
InitializerImpl.java

Các lớp bộ mở rộng Bokeh (triển khai nếu tiện ích Bokeh được hỗ trợ)

BokehImageCaptureExtenderImpl.java
BokehPreviewExtenderImpl.java
advanced/BokehAdvancedExtenderImpl.java

Các lớp mở rộng ban đêm (triển khai nếu tính năng Mở rộng ban đêm được hỗ trợ)

NightImageCaptureExtenderImpl.java
NightPreviewExtenderImpl.java
advanced/NightAdvancedExtenderImpl.java

Các lớp trình mở rộng tự động (triển khai nếu Trình mở rộng tự động được hỗ trợ)

AutoImageCaptureExtenderImpl.java
AutoPreviewExtenderImpl.java
advanced/AutoAdvancedExtenderImpl.java

Các lớp mở rộng HDR (triển khai nếu tiện ích HDR được hỗ trợ)

HdrImageCaptureExtenderImpl.java
HdrPreviewExtenderImpl.java
advanced/HdrAdvancedExtenderImpl.java

Các lớp mở rộng của tính năng Làm đẹp khuôn mặt (triển khai nếu tiện ích Làm đẹp khuôn mặt được hỗ trợ)

BeautyImageCaptureExtenderImpl.java
BeautyPreviewExtenderImpl.java
advanced/BeautyAdvancedExtenderImpl.java

Tiện ích (không bắt buộc, có thể xoá)

advanced/Camera2OutputConfigImplBuilder.java
advanced/Camera2SessionConfigImplBuilder.java

Bạn không bắt buộc phải cung cấp phương thức triển khai cho mọi tiện ích. Nếu bạn không triển khai một tiện ích, hãy đặt isExtensionAvailable() để trả về false hoặc xoá các lớp Tiện ích tương ứng. Các API Camera2 và CameraX Extensions sẽ báo cáo cho ứng dụng rằng tiện ích không dùng được.

Hãy xem cách Camera2 và CameraX Extensions API tương tác với thư viện của nhà cung cấp để bật một tiện ích. Sơ đồ sau đây minh hoạ quy trình từ đầu đến cuối bằng cách sử dụng tiện ích Ban đêm làm ví dụ:

Mainflow

Hình 2. Triển khai tiện ích ban đêm

Xác minh phiên bản:

Camera2/X gọi ExtensionVersionImpl.checkApiVersion() để đảm bảo rằng phiên bản extensions-interface do OEM triển khai tương thích với các phiên bản được Camera2/X hỗ trợ.
Khởi chạy thư viện nhà cung cấp:

InitializerImpl có một phương thức init() để khởi chạy thư viện của nhà cung cấp. Camera2/X hoàn tất quá trình khởi chạy trước khi truy cập vào các lớp Trình mở rộng.
Khởi tạo các lớp Extender:

Tạo thực thể cho các lớp Extender cho tiện ích. Có hai loại Bộ mở rộng: Bộ mở rộng cơ bản và Bộ mở rộng nâng cao. Bạn phải triển khai một loại Trình mở rộng cho tất cả các Tiện ích. Để biết thêm thông tin, hãy xem bài viết Thiết bị mở rộng cơ bản so với thiết bị mở rộng nâng cao.

Camera2/X khởi tạo và tương tác với các lớp Extender để truy xuất thông tin và bật tiện ích. Đối với một tiện ích nhất định, Camera2/X có thể khởi tạo các lớp Extender nhiều lần. Do đó, đừng thực hiện quá trình khởi tạo tốn nhiều tài nguyên trong hàm khởi tạo hoặc lệnh gọi init(). Chỉ thực hiện các thao tác phức tạp khi phiên camera sắp bắt đầu, chẳng hạn như khi onInit() được gọi trong Trình mở rộng cơ bản hoặc initSession() được gọi trong Trình mở rộng nâng cao.

Đối với tiện ích Night, các lớp Extender sau đây được khởi tạo cho loại Basic Extender:
- NightImageCaptureExtenderImpl.java
- NightPreviewExtenderImpl.java
Và đối với loại Bộ mở rộng nâng cao:
- NightAdvancedExtenderImpl.java
Kiểm tra phạm vi cung cấp của tiện ích:

Trước khi bật tiện ích, isExtensionAvailable() sẽ kiểm tra xem tiện ích có dùng được trên mã nhận dạng camera đã chỉ định thông qua thực thể Extender hay không.
Khởi động Trình mở rộng bằng thông tin camera:

Camera2/X gọi init() trên thực thể Extender và truyền cho thực thể này mã nhận dạng camera và CameraCharacteristics.
Thông tin về cụm từ tìm kiếm:

Gọi lớp Extender để truy xuất thông tin, chẳng hạn như độ phân giải được hỗ trợ, độ trễ ước tính khi chụp ảnh tĩnh và khoá yêu cầu chụp từ Extender để chuẩn bị cho việc bật tiện ích.
Bật tiện ích trên Bộ mở rộng:

Lớp Extender cung cấp tất cả các giao diện cần thiết để bật lớp. Lớp này cung cấp một cơ chế để liên kết việc triển khai của OEM vào quy trình Camera2, chẳng hạn như chèn các tham số yêu cầu chụp hoặc bật một trình xử lý hậu kỳ.

Đối với loại Bộ mở rộng nâng cao, Camera2/X tương tác với SessionProcessorImpl để bật tiện ích. Camera2/X truy xuất thực thể SessionProcessorImpl bằng cách gọi createSessionProcessor() trên Trình mở rộng.

Các phần sau đây mô tả chi tiết hơn về quy trình mở rộng.

Xác minh phiên bản

Khi tải thư viện nhà cung cấp OEM từ thiết bị trong thời gian chạy, Camera2/X sẽ xác minh xem thư viện có tương thích với phiên bản extensions-interface hay không. extensions-interface sử dụng định nghĩa phiên bản ngữ nghĩa hoặc MAJOR.MINOR.PATCH, ví dụ: 1.1.0 hoặc 1.2.0. Tuy nhiên, chỉ các phiên bản chính và phụ được dùng trong quá trình xác minh phiên bản.

Để xác minh phiên bản, Camera2/X sẽ gọi ExtensionVersionImpl.checkApiVersion() với phiên bản extensions-interface được hỗ trợ. Sau đó, Camera2/X sẽ sử dụng phiên bản do thư viện OEM báo cáo để xác định xem có thể bật tiện ích hay không và tiện ích nên gọi những chức năng nào.

Khả năng tương thích với phiên bản chính

Nếu các phiên bản chính của extension-interface khác nhau giữa Camera2/X và thư viện của nhà cung cấp, thì phiên bản đó sẽ được coi là không tương thích và tiện ích sẽ bị tắt.

Khả năng tương thích ngược

Miễn là phiên bản chính giống nhau, Camera2/X sẽ đảm bảo khả năng tương thích ngược với các thư viện của nhà cung cấp OEM được tạo bằng các phiên bản extensions-interface trước đó. Ví dụ: nếu Camera2/X hỗ trợ extensions-interface 1.3.0, thì các thư viện của nhà cung cấp OEM đã triển khai 1.0.0, 1.1.0 và 1.2.0 vẫn tương thích. Điều này cũng có nghĩa là sau khi bạn triển khai một phiên bản cụ thể của thư viện nhà cung cấp, Camera2/X sẽ đảm bảo thư viện đó tương thích ngược với các phiên bản extension-interface sắp tới.

Khả năng tương thích chuyển tiếp

Khả năng tương thích chuyển tiếp với các thư viện của nhà cung cấp extensions-interface mới hơn phụ thuộc vào bạn, tức là OEM. Nếu cần một số tính năng để triển khai các tiện ích, bạn có thể muốn bật các tiện ích này bắt đầu từ một phiên bản nhất định. Trong trường hợp này, bạn có thể trả về phiên bản extensions-interface được hỗ trợ khi phiên bản thư viện Camera2/X đáp ứng các yêu cầu. Nếu các phiên bản Camera2/X không được hỗ trợ, bạn có thể trả về một phiên bản không tương thích, chẳng hạn như 99.0.0 để tắt các tiện ích.

Khởi chạy thư viện của nhà cung cấp

Sau khi xác minh phiên bản extensions-interface do thư viện OEM triển khai, Camera2/X sẽ bắt đầu quy trình khởi chạy. Phương thức InitializerImpl.init() báo hiệu cho thư viện OEM rằng một ứng dụng đang cố gắng sử dụng các tiện ích.

Camera2/X không gọi thư viện OEM nào khác (ngoài việc kiểm tra phiên bản) cho đến khi thư viện nhà cung cấp OEM gọi OnExtensionsInitializedCallback.onSuccess() để thông báo hoàn tất quá trình khởi tạo.

Bạn phải triển khai InitializerImpl kể từ extensions-interface 1.1.0. Camera2/X bỏ qua bước khởi chạy thư viện nếu thư viện của nhà cung cấp OEM triển khai extensions-interface 1.0.0.

Thanh nối dài cơ bản so với thanh nối dài nâng cao

Có hai loại triển khai extensions-interface: Trình mở rộng cơ bản và Trình mở rộng nâng cao. Advanced Extender được hỗ trợ từ extensions-interface 1.2.0.

Triển khai Trình mở rộng cơ bản cho các tiện ích xử lý hình ảnh trong HAL camera hoặc sử dụng một trình xử lý hậu kỳ có khả năng xử lý luồng YUV.

Triển khai Trình mở rộng nâng cao cho những tiện ích cần tuỳ chỉnh cấu hình luồng Camera2 và gửi yêu cầu chụp nếu cần.

Hãy xem bảng sau để so sánh:

	Thanh nối dài cơ bản	Advanced Extender
Cấu hình luồng phát	Cố định Xem trước: `PRIVATE` hoặc `YUV_420_888` (nếu có bộ xử lý) Chụp ảnh tĩnh: `JPEG` hoặc `YUV_420_888` (nếu có bộ xử lý)	Nhà sản xuất thiết bị gốc (OEM) có thể tuỳ chỉnh.
Đang gửi yêu cầu chụp ảnh	Chỉ Camera2/X mới có thể gửi yêu cầu chụp. Bạn có thể đặt các tham số cho những yêu cầu này. Khi bộ xử lý được cung cấp để chụp ảnh, Camera2/X có thể gửi nhiều yêu cầu chụp và gửi tất cả hình ảnh cũng như kết quả chụp đến bộ xử lý.	Một thực thể `RequestProcessorImpl` được cung cấp cho bạn để thực thi yêu cầu chụp ảnh camera2 và nhận kết quả cũng như Hình ảnh. Camera2/X gọi `startRepeating` và `startCapture` trên `SessionProcessorImpl` để báo hiệu cho OEM bắt đầu yêu cầu lặp lại cho bản xem trước và bắt đầu trình tự chụp ảnh tĩnh tương ứng.
Các lệnh gọi trong quy trình camera	`onPresetSession` cung cấp các tham số phiên. `onEnableSession` sẽ gửi một yêu cầu ngay sau khi `CameraCaptureSession` được định cấu hình. `onDisableSession` sẽ gửi một yêu cầu trước khi `CameraCaptureSession` đóng.	`initSession` khởi chạy và trả về một cấu hình phiên camera2 tuỳ chỉnh để tạo phiên chụp. `onCaptureSessionStart` được gọi ngay sau khi `CameraCaptureSession` được định cấu hình. `onCaptureSessionEnd` được gọi trước khi `CameraCaptureSession` đóng.
Phù hợp với	Các tiện ích được triển khai trong HAL camera hoặc trong một bộ xử lý xử lý hình ảnh YUV.	Có các phương thức triển khai dựa trên Camera2 cho các tiện ích. Cần có cấu hình luồng tuỳ chỉnh, chẳng hạn như luồng RAW. Cần có trình tự Chụp tương tác.
Phiên bản API được hỗ trợ	Camera2 Extensions: Android 13 trở lên CameraX Extensions: `camera-extensions` 1.1.0 trở lên	Tiện ích Camera2: Android 12L trở lên Tiện ích CameraX: `camera-extensions` 1.2.0-alpha03 trở lên

Luồng ứng dụng

Bảng sau đây cho thấy 3 loại luồng ứng dụng và các lệnh gọi Camera Extensions API tương ứng. Mặc dù Camera2/X cung cấp các API này, nhưng bạn phải triển khai đúng thư viện của nhà cung cấp để hỗ trợ các quy trình này. Chúng tôi sẽ mô tả chi tiết hơn trong một phần sau.

Tiện ích Camera2 Tiện ích CameraX

Phạm vi cung cấp của phần mở rộng về cụm từ tìm kiếm CameraExtensionCharacteristics .getSupportedExtensions ExtensionsManager. isExtensionAvailable

	Tiện ích Camera2	Tiện ích CameraX
Phạm vi cung cấp của phần mở rộng về cụm từ tìm kiếm	`CameraExtensionCharacteristics .getSupportedExtensions`	`ExtensionsManager. isExtensionAvailable`
Thông tin về cụm từ tìm kiếm	`CameraExtensionCharacteristics. getExtensionSupportedSizes` `CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis` `CameraExtensionCharacteristics. getAvailableCaptureRequestKeys` `CameraExtensionCharacteristics. getAvailableCaptureResultKeys`	`ExtensionsManager. getEstimatedCaptureLatencyRange` CameraX xử lý phần còn lại của thông tin trong thư viện.
Xem trước và chụp ảnh tĩnh khi bật tiện ích	`CameraDevice. createExtensionSession` `cameraExtensionsSession. setRepeatingRequest` `cameraExtensionsSession. capture`	`val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector` `bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)`

Thông tin về cụm từ tìm kiếm

CameraExtensionCharacteristics.
   getExtensionSupportedSizes

CameraExtensionCharacteristics.
getEstimatedCaptureLatencyRangeMillis

CameraExtensionCharacteristics.
getAvailableCaptureRequestKeys

CameraExtensionCharacteristics.
getAvailableCaptureResultKeys

ExtensionsManager.
   getEstimatedCaptureLatencyRange

CameraX xử lý phần còn lại của thông tin trong thư viện.

Xem trước và chụp ảnh tĩnh khi bật tiện ích

CameraDevice.
   createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager.
   getExtensionEnabledCameraSelector

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

Thanh nối dài cơ bản

Giao diện Basic Extender cung cấp các hook vào một số vị trí trong quy trình camera. Mỗi loại tiện ích đều có các lớp Extender tương ứng mà OEM cần triển khai.

Bảng sau đây liệt kê các lớp Trình mở rộng mà OEM cần triển khai cho từng tiện ích:

	Các lớp tiện ích cần triển khai
Đêm	`NightPreviewExtenderImpl.java` `NightImageCaptureExtenderImpl.java`
HDR	`HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java`
Ô tô	`AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java`
Bokeh	`BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java`
Làm đẹp khuôn mặt	`BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java`

Chúng ta sử dụng PreviewExtenderImpl và ImageCaptureExtenderImpl làm phần giữ chỗ trong ví dụ sau. Thay thế các tên này bằng tên của các tệp thực tế mà bạn đang triển khai.

Basic Extender có các chức năng sau:

Chèn các thông số phiên khi định cấu hình CameraCaptureSession (onPresetSession).
Thông báo cho bạn về các sự kiện bắt đầu và đóng phiên chụp, đồng thời gửi một yêu cầu duy nhất để thông báo cho HAL bằng các tham số đã trả về (onEnableSession, onDisableSession).
Chèn các tham số ghi nhận cho yêu cầu (PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages).
Thêm các bộ xử lý để xem trước và chụp ảnh tĩnh có khả năng xử lý luồng YUV_420_888.

Hãy xem cách Camera2/X gọi extensions-interface để đạt được 3 quy trình của ứng dụng nêu trên.

Luồng ứng dụng 1: Kiểm tra phạm vi cung cấp tiện ích

BasicExtenderAppFlow1

Hình 3. Luồng ứng dụng 1 trên Bộ mở rộng cơ bản

Trong quy trình này, Camera2/X sẽ gọi trực tiếp phương thức isExtensionAvailable() của cả PreviewExtenderImpl và ImageCaptureExtenderImpl mà không cần gọi init(). Cả hai lớp Extender đều phải trả về true để bật các tiện ích.

Đây thường là bước đầu tiên để các ứng dụng kiểm tra xem loại tiện ích đã cho có được hỗ trợ cho một mã nhận dạng camera nhất định hay không trước khi bật tiện ích. Điều này là do một số tiện ích chỉ được hỗ trợ trên một số mã nhận dạng camera nhất định.

Luồng ứng dụng 2: Truy vấn thông tin

BasicExtenderAppFlow2

Hình 4. Luồng ứng dụng 2 trên Bộ mở rộng cơ bản

Sau khi xác định xem tiện ích có dùng được hay không, các ứng dụng nên truy vấn thông tin sau đây trước khi bật tiện ích.

Phạm vi độ trễ khi chụp ảnh tĩnh: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange trả về phạm vi độ trễ khi chụp để ứng dụng đánh giá xem có phù hợp để bật tiện ích cho trường hợp hiện tại hay không.
Kích thước được hỗ trợ cho bề mặt xem trước và chụp: ImageCaptureExtenderImpl.getSupportedResolutions và PreviewExtenderImpl.getSupportedResolutions trả về danh sách các định dạng hình ảnh và kích thước được hỗ trợ cho định dạng và kích thước bề mặt.
Các khoá yêu cầu và kết quả được hỗ trợ: Camera2/X sẽ gọi các phương thức sau để truy xuất các khoá yêu cầu chụp và khoá kết quả được hỗ trợ từ quá trình triển khai của bạn:
- ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
- ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X luôn gọi init() trước trên các lớp Trình mở rộng này trước khi truy vấn để biết thêm thông tin.

Luồng ứng dụng 3: Xem trước/chụp ảnh tĩnh khi bật tiện ích (triển khai HAL)

BasicExtenderAppFlow3

Hình 5. Luồng ứng dụng 3 trên Bộ mở rộng cơ bản

Sơ đồ trên minh hoạ quy trình chính để bật tính năng xem trước và chụp ảnh tĩnh bằng một tiện ích mà không cần bộ xử lý. Điều này có nghĩa là HAL camera sẽ xử lý tiện ích.

Trong quy trình này, Camera2/X trước tiên sẽ gọi init() rồi đến onInit, thông báo cho bạn rằng một phiên camera sắp bắt đầu với các tiện ích được chỉ định. Bạn có thể thực hiện quá trình khởi chạy có mức sử dụng tài nguyên cao trong onInit().

Khi định cấu hình CameraCaptureSession, Camera2/X sẽ gọi onPresetSession để lấy các tham số phiên. Sau khi phiên chụp được định cấu hình thành công, Camera2/X sẽ gọi onEnableSession, trả về một thực thể CaptureStageImpl chứa các tham số chụp. Camera2/X sẽ gửi ngay một yêu cầu duy nhất có các thông số chụp này để thông báo cho HAL. Tương tự, trước khi phiên chụp đóng, Camera2/X sẽ gọi onDisableSession rồi gửi một yêu cầu duy nhất với các tham số chụp đã trả về.

Yêu cầu lặp lại do Camera2/X kích hoạt chứa các tham số yêu cầu do PreviewExtenderImpl.getCaptureStage() trả về. Ngoài ra, yêu cầu chụp ảnh tĩnh chứa các tham số do ImageCaptureExtenderImpl.getCaptureStages() trả về.

Cuối cùng, Camera2/X sẽ gọi onDeInit() sau khi phiên máy ảnh kết thúc. Bạn có thể giải phóng tài nguyên trong onDeinit().

Trình xử lý xem trước

Ngoài HAL camera, bạn cũng có thể triển khai các tiện ích trong một bộ xử lý.

Triển khai PreviewExtenderImpl.getProcessorType để chỉ định loại bộ xử lý như giải thích bên dưới:

PROCESSOR_TYPE_NONE: Không có bộ xử lý. Hình ảnh được xử lý trong HAL của camera.
PROCESSOR_TYPE_REQUEST_UPDATE_ONLY: Loại bộ xử lý cho phép bạn cập nhật yêu cầu lặp lại bằng các tham số yêu cầu chụp mới dựa trên TotalCaptureResult mới nhất.

PreviewExtenderImpl.getProcessor phải trả về một thực thể RequestUpdateProcessorImpl xử lý thực thể TotalCaptureResult và trả về một thực thể CaptureStageImpl để cập nhật yêu cầu lặp lại. PreviewExtenderImpl.getCaptureStage() cũng phải phản ánh kết quả của quá trình xử lý và trả về CaptureStageImpl mới nhất.
PROCESSOR_TYPE_IMAGE_PROCESSOR: Loại này cho phép bạn triển khai một bộ xử lý để xử lý hình ảnh YUV_420_888 và ghi đầu ra vào một bề mặt PRIVATE.

Bạn cần triển khai và trả về một thực thể PreviewImageProcessorImpl trong PreviewExtenderImpl.getProcessor. Bộ xử lý chịu trách nhiệm xử lý hình ảnh đầu vào YUV_420_888. Thao tác này sẽ ghi đầu ra vào định dạng PRIVATE của bản xem trước. Camera2/X sử dụng một nền tảng YUV_420_888 thay vì PRIVATE để định cấu hình CameraCaptureSession cho bản xem trước.

Xem hình minh hoạ sau đây để biết quy trình:

PreviewProcessor

Hình 6. Xem trước luồng bằng PreviewImageProcessorImpl

Giao diện PreviewImageProcessorImpl mở rộng ProcessImpl và có 3 phương thức quan trọng:

onOutputSurface(Surface surface, int imageFormat) đặt bề mặt đầu ra cho bộ xử lý. Đối với PreviewImageProcessorImpl, imageFormat là một định dạng pixel, chẳng hạn như PixelFormat.RGBA_8888.
onResolutionUpdate(Size size) đặt kích thước của hình ảnh đầu vào.
onImageFormatUpdate(int imageFormat) đặt định dạng hình ảnh của hình ảnh đầu vào. Hiện tại, bạn chỉ có thể chọn YUV_420_888.

Bộ xử lý chụp ảnh

Để chụp ảnh tĩnh, bạn có thể triển khai một bộ xử lý bằng cách trả về một thực thể CaptureProcessorImpl bằng cách sử dụng ImageCaptureExtenderImpl.getCaptureProcessor. Bộ xử lý chịu trách nhiệm xử lý danh sách các hình ảnh YUV_420_888 và các thực thể TotalCaptureResult đã chụp, đồng thời ghi đầu ra vào một bề mặt YUV_420_888.

Bạn có thể giả định một cách an toàn rằng bản xem trước đã được bật và đang chạy trước khi gửi yêu cầu chụp ảnh tĩnh.

Hãy xem quy trình trong sơ đồ bên dưới:

CaptureProcessor

Hình 7. Quy trình chụp ảnh tĩnh bằng CaptureProcessorImpl

Camera2/X sử dụng một vùng (surface) định dạng YUV_420_888 để chụp ảnh tĩnh nhằm định cấu hình phiên chụp. Camera2/X chuẩn bị CaptureProcessorImpl bằng cách gọi:
- CaptureProcessorImpl.onImageFormatUpdate() với YUV_420_888.
- CaptureProcessorImpl.onResolutionUpdate() với kích thước hình ảnh đầu vào.
- CaptureProcessorImpl.onOutputSurface() có một bề mặt đầu ra YUV_420_888.
ImageCaptureExtenderImpl.getCaptureStages trả về một danh sách CaptureStageImpl, trong đó mỗi phần tử ánh xạ đến một thực thể CaptureRequest có các tham số chụp do Camera2/X gửi. Ví dụ: nếu phương thức này trả về danh sách gồm 3 thực thể CaptureStageImpl, thì Camera2/X sẽ gửi 3 yêu cầu chụp với các tham số chụp tương ứng bằng API captureBurst.

Lưu ý: getCaptureStages() chỉ được phép trả về nhiều thực thể CaptureStageImpl khi getCaptureProcessor() trả về một thực thể.
Các hình ảnh và phiên bản TotalCaptureResult nhận được sẽ được kết hợp với nhau và gửi đến CaptureProcessorImpl để xử lý.
CaptureProcessorImpl ghi Hình ảnh kết quả (định dạng YUV_420_888) vào bề mặt đầu ra do lệnh gọi onOutputSurface() chỉ định. Camera2/X sẽ chuyển đổi thành hình ảnh JPEG nếu cần.

Hỗ trợ các khoá và kết quả của yêu cầu chụp

Ngoài tính năng xem trước và chụp ảnh, các ứng dụng có thể đặt các thông số thu phóng, đèn flash hoặc kích hoạt tính năng nhấn để lấy nét. Các tham số này có thể không tương thích với việc triển khai tiện ích của bạn.

Các phương thức sau đã được thêm vào extensions-interface 1.3.0 để cho phép bạn hiển thị các tham số mà quá trình triển khai của bạn hỗ trợ:

ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys() trả về các khoá yêu cầu chụp mà quá trình triển khai của bạn hỗ trợ.
ImageCaptureExtenderImpl.getAvailableCaptureResultKeys() trả về các khoá kết quả chụp có trong kết quả chụp.

Nếu HAL camera xử lý tiện ích này, Camera2/X sẽ truy xuất kết quả chụp trong CameraCaptureSession.CaptureCallback. Tuy nhiên, nếu bộ xử lý được triển khai, thì Camera2/X sẽ truy xuất kết quả chụp trong ProcessResultImpl, được truyền đến phương thức process() trong PreviewImageProcessorImpl và CaptureProcessorImpl. Bạn chịu trách nhiệm báo cáo kết quả chụp thông qua ProcessResultImpl cho Camera2/X.

Hãy xem định nghĩa về giao diện CaptureProcessorImpl bên dưới làm ví dụ. Trong extensions-interface 1.3.0 trở lên, lệnh gọi process() thứ hai sẽ được gọi:

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);
}

Đối với các thao tác phổ biến của camera như thu phóng, nhấn để lấy nét, đèn flash và bù phơi sáng, bạn nên hỗ trợ các khoá sau cho cả yêu cầu chụp và kết quả chụp:

Zoom:
- CaptureRequest#CONTROL_ZOOM_RATIO
- CaptureRequest#SCALER_CROP_REGION
Nhấn để lấy nét:
- 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
Bù phơi sáng:
- CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

Đối với các Tiện ích cơ bản triển khai phiên bản 1.2.0 trở xuống, CameraX Extensions API hỗ trợ rõ ràng tất cả các khoá nêu trên. Đối với extensions-interface 1.3.0, cả CameraX và Camera2 đều tuân theo danh sách được trả về và chỉ hỗ trợ các khoá có trong danh sách đó. Ví dụ: nếu bạn quyết định chỉ trả về CaptureRequest#CONTROL_ZOOM_RATIO và CaptureRequest#SCALER_CROP_REGION trong quá trình triển khai 1.3.0, thì điều đó có nghĩa là ứng dụng chỉ hỗ trợ tính năng thu phóng trong khi không cho phép các tính năng nhấn để lấy nét, đèn flash và bù phơi sáng.

Advanced Extender

Advanced Extender là một loại phương thức triển khai của nhà cung cấp dựa trên Camera2 API. Loại Extender này được thêm vào trong extensions-interface 1.2.0. Tuỳ thuộc vào nhà sản xuất thiết bị, các tiện ích có thể được triển khai ở lớp ứng dụng, tuỳ thuộc vào các yếu tố sau:

Cấu hình luồng tuỳ chỉnh: Định cấu hình các luồng tuỳ chỉnh như luồng RAW hoặc có nhiều luồng cho các mã nhận dạng camera thực khác nhau.
Khả năng gửi yêu cầu Camera2: Hỗ trợ logic tương tác phức tạp có thể gửi yêu cầu chụp ảnh kèm theo các tham số dựa trên kết quả của các yêu cầu trước đó.

Advanced Extender cung cấp một trình bao bọc hoặc một lớp trung gian để bạn có thể tuỳ chỉnh cấu hình luồng và gửi yêu cầu ghi hình theo ý muốn.

Các tệp cần triển khai

Để chuyển sang việc triển khai Advanced Extender, phương thức isAdvancedExtenderImplemented() trong ExtensionVersionImpl phải trả về true. Đối với mỗi loại phần mở rộng, OEM phải triển khai các lớp Trình mở rộng tương ứng. Các tệp triển khai Advanced Extender nằm trong gói advanced.

	Các lớp tiện ích cần triển khai
Đêm	`advanced/NightAdvancedExtenderImpl.java`
HDR	`advanced/HdrAdvancedExtenderImpl.java`
Ô tô	`advanced/AutoAdvancedExtenderImpl.java`
Bokeh	`advanced/BokehAdvancedExtenderImpl.java`
Làm đẹp khuôn mặt	`advanced/BeautyAdvancedExtenderImpl.java`

Chúng ta sử dụng AdvancedExtenderImpl làm phần giữ chỗ trong ví dụ sau. Thay thế bằng tên của tệp Trình mở rộng cho tiện ích mà bạn đang triển khai.

Hãy xem cách Camera2/X gọi extensions-interface để đạt được 3 quy trình của ứng dụng.

Luồng ứng dụng 1: Kiểm tra phạm vi cung cấp tiện ích

AdvancedAppFlow1

Hình 8. Luồng ứng dụng 1 trên Advanced Extender

Trước tiên, ứng dụng sẽ kiểm tra xem tiện ích đã cho có được hỗ trợ hay không.

Luồng ứng dụng 2: Truy vấn thông tin

AdvancedAppFlow2

Hình 9. Luồng ứng dụng 2 trên Advanced Extender

Sau khi gọi AdvancedExtenderImpl.init(), ứng dụng có thể truy vấn thông tin sau đây trên AdvancedExtenderImpl:

Độ trễ ước tính khi chụp ảnh tĩnh: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange() trả về phạm vi độ trễ chụp để ứng dụng đánh giá xem có phù hợp để bật tiện ích cho trường hợp hiện tại hay không.
Độ phân giải được hỗ trợ cho chế độ xem trước và chụp ảnh tĩnh:
- AdvancedExtenderImpl.getSupportedPreviewOutputResolutions() trả về một bản đồ định dạng hình ảnh cho danh sách kích thước được hỗ trợ cho định dạng và kích thước của nền tảng xem trước. Các OEM phải hỗ trợ ít nhất định dạng PRIVATE.
- AdvancedExtenderImpl.getSupportedCaptureOutputResolutions() trả về định dạng và kích thước được hỗ trợ cho bề mặt chụp ảnh tĩnh. Nhà sản xuất thiết bị gốc phải hỗ trợ cả đầu ra định dạng JPEG và YUV_420_888.
- AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions() trả về các kích thước được hỗ trợ cho một luồng YUV_420_888 bổ sung để phân tích hình ảnh. Nếu không hỗ trợ bề mặt YUV phân tích hình ảnh, getSupportedYuvAnalysisResolutions() sẽ trả về null hoặc một danh sách trống.
Các khoá/kết quả yêu cầu chụp có sẵn (được thêm vào extensions-interface 1.3.0): Camera2/X gọi các phương thức sau để truy xuất các khoá yêu cầu chụp và khoá kết quả được hỗ trợ từ quá trình triển khai của bạn:
- AdvancedExtenderImpl.getAvailableCaptureRequestKeys
- AdvancedExtenderImpl.getAvailableCaptureResultKeys

Để biết thêm thông tin, hãy xem phần Hỗ trợ khoá và kết quả của yêu cầu chụp.

Luồng ứng dụng 3: Xem trước/chụp ảnh tĩnh khi bật tiện ích

AdvancedAppFlow3

Hình 10. Luồng ứng dụng 3 trên Advanced Extender

Sơ đồ trên cho thấy quy trình chính để bắt đầu xem trước và chụp ảnh tĩnh cho loại Advanced Extender. Hãy cùng tìm hiểu từng bước.

SessionProcessorImpl phiên bản

Việc triển khai Advanced Extender cốt lõi nằm trong SessionProcessorImpl, chịu trách nhiệm cung cấp cấu hình phiên tuỳ chỉnh và gửi yêu cầu chụp để bắt đầu yêu cầu xem trước và chụp ảnh tĩnh. AdvancedExtenderImpl.createSessionProcessor() được gọi để trả về thực thể SessionProcessorImpl.

Lưu ý: Một phiên camera có thể sử dụng nhiều lần một thực thể SessionProcessorImpl. Do đó, quá trình triển khai phải hỗ trợ nhiều lệnh gọi initSession() và deInitSession() cho một phiên bản SessionProcessorImpl.
initSession

SessionProcessorImpl.initSession() khởi tạo phiên cho tiện ích. Đây là nơi bạn phân bổ tài nguyên và trả về cấu hình phiên để chuẩn bị một CameraCaptureSession.

Đối với các tham số đầu vào, Camera2/X chỉ định cấu hình bề mặt đầu ra để xem trước, chụp ảnh tĩnh và phân tích hình ảnh YUV (không bắt buộc). Cấu hình đầu ra này (OutputSurfaceImpl) chứa định dạng hình ảnh, kích thước và vùng hiển thị do các phương thức sau truy xuất trong AdvancedExtenderImpl:
- getSupportedPreviewOutputResolutions()
- getSupportedCaptureOutputResolutions()
- getSupportedYuvAnalysisResolutions()
Bạn phải trả về một thực thể Camera2SessionConfigImpl, bao gồm một danh sách các thực thể Camera2OutputConfigImpl và các thông số phiên được dùng để định cấu hình CameraCaptureSession. Bạn chịu trách nhiệm xuất hình ảnh chính xác từ camera vào các nền tảng đầu ra do Camera2/X truyền vào. Sau đây là một số lựa chọn để bật đầu ra:
- Xử lý trong HAL camera: Bạn có thể trực tiếp thêm các bề mặt đầu ra vào CameraCaptureSession bằng cách triển khai SurfaceOutputConfigImpl. Thao tác này sẽ định cấu hình bề mặt đầu ra được cung cấp cho quy trình camera và cho phép HAL camera xử lý hình ảnh.
- Xử lý bề mặt ImageReader trung gian (RAW, YUV, v.v.): Thêm các bề mặt ImageReader trung gian vào CameraCaptureSession bằng một thực thể ImageReaderOutputConfigImpl.
  
  Bạn cần xử lý các hình ảnh trung gian và ghi hình ảnh kết quả vào bề mặt đầu ra.
Lưu ý: Camera2/X sẽ tạo và quản lý các thực thể ImageReader cho bạn. Bạn có thể đặt một thực thể ImageProcessorImpl để truy xuất hình ảnh.
- Sử dụng tính năng chia sẻ bề mặt Camera2: Sử dụng tính năng chia sẻ bề mặt với một bề mặt khác bằng cách thêm mọi thực thể Camera2OutputConfigImpl vào phương thức getSurfaceSharingOutputConfigs() của một thực thể Camera2OutputConfigImpl khác. Định dạng và kích thước của vùng hiển thị phải giống nhau.
Tất cả Camera2OutputConfigImpl (bao gồm cả SurfaceOutputConfigImpl và ImageReaderOutputConfigImpl) đều phải có một mã nhận dạng duy nhất (getId()) dùng để chỉ định nền tảng mục tiêu và truy xuất hình ảnh từ ImageReaderOutputConfigImpl.
onCaptureSessionStart và RequestProcessorImpl

Khi CameraCaptureSession bắt đầu và khung Camera gọi onConfigured(), Camera2/X sẽ gọi SessionProcessorImpl.onCaptureSessionStart() bằng trình bao bọc yêu cầu Camera2 RequestProcessImpl. Camera2/X triển khai RequestProcessImpl, cho phép bạn thực thi các yêu cầu chụp và truy xuất hình ảnh nếu ImageReaderOutputConfigImpl được dùng.

Các API RequestProcessImpl tương tự như các API CameraCaptureSession Camera2 về việc thực thi các yêu cầu. Sau đây là những điểm khác biệt:
- Nền tảng mục tiêu được chỉ định bằng mã nhận dạng của thực thể Camera2OutputConfigImpl.
- Khả năng truy xuất hình ảnh của ImageReader.
Bạn có thể gọi RequestProcessorImpl.setImageProcessor() bằng một mã nhận dạng Camera2OutputConfigImpl đã chỉ định để đăng ký một thực thể ImageProcessorImpl nhằm nhận hình ảnh.

Thực thể RequestProcessImpl sẽ không hợp lệ sau khi Camera2/X gọi SessionProcessorImpl.onCaptureSessionEnd().
Bắt đầu xem trước và chụp ảnh

Trong quá trình triển khai Advanced Extender, bạn có thể gửi các yêu cầu chụp thông qua giao diện RequestProcessorImpl. Camera2/X sẽ thông báo cho bạn bắt đầu yêu cầu lặp lại cho bản xem trước hoặc trình tự chụp ảnh tĩnh bằng cách gọi lần lượt SessionProcessorImpl#startRepeating và SessionProcessorImpl#startCapture. Bạn nên gửi yêu cầu chụp để đáp ứng các yêu cầu xem trước và chụp ảnh tĩnh này.

Camera2/X cũng đặt các tham số yêu cầu chụp thông qua SessionProcessorImpl#setParameters. Bạn phải đặt các tham số yêu cầu này (nếu tham số được hỗ trợ) cho cả yêu cầu lặp lại và yêu cầu đơn lẻ.

Bạn phải hỗ trợ ít nhất CaptureRequest.JPEG_ORIENTATION và CaptureRequest.JPEG_QUALITY. extensions-interface 1.3.0 hỗ trợ các khoá yêu cầu và kết quả. Các khoá này được hiển thị bằng các phương thức sau:
- AdvancedExtenderImpl.getAvailableCaptureRequestKeys()
- AdvancedExtenderImpl.getAvailableCaptureResultKeys()
Khi nhà phát triển đặt các khoá trong danh sách getAvailableCaptureRequestKeys, bạn phải bật các tham số và đảm bảo kết quả chụp chứa các khoá trong danh sách getAvailableCaptureResultKeys.
startTrigger

SessionProcessorImpl.startTrigger() được gọi để bắt đầu điều kiện kích hoạt, chẳng hạn như CaptureRequest.CONTROL_AF_TRIGGER và CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER. Bạn có thể bỏ qua mọi khoá yêu cầu chụp không được quảng cáo trong AdvancedExtenderImpl.getAvailableCaptureRequestKeys().

startTrigger() đã được hỗ trợ kể từ phiên bản extensions-interface 1.3.0. Cho phép các ứng dụng triển khai tính năng nhấn để lấy nét và đèn flash bằng các tiện ích.
Dọn dẹp

Khi kết thúc một phiên chụp, SessionProcessorImpl.onCaptureSessionEnd() sẽ được gọi trước khi đóng CameraCaptureSession. Sau khi phiên chụp kết thúc, deInitSession() sẽ dọn dẹp.

Hỗ trợ xem trước, chụp ảnh tĩnh và phân tích hình ảnh

Bạn nên áp dụng tiện ích cho cả trường hợp sử dụng xem trước và chụp ảnh tĩnh. Tuy nhiên, nếu độ trễ quá cao để hiển thị bản xem trước một cách mượt mà, thì bạn chỉ có thể áp dụng tiện ích cho chế độ chụp ảnh tĩnh.

Đối với loại Basic Extender, bất kể bạn có bật tiện ích để xem trước hay không, bạn phải triển khai cả ImageCaptureExtenderImpl và PreviewExtenderImpl cho một tiện ích nhất định. Thông thường, ứng dụng cũng sử dụng luồng YUV để phân tích nội dung hình ảnh, chẳng hạn như tìm mã QR hoặc văn bản. Để hỗ trợ tốt hơn cho trường hợp sử dụng này, bạn nên hỗ trợ sự kết hợp luồng của bản xem trước, ảnh chụp tĩnh và luồng YUV_420_888 để định cấu hình CameraCaptureSession. Điều này có nghĩa là nếu triển khai một bộ xử lý, thì bạn phải hỗ trợ tổ hợp luồng gồm 3 luồng YUV_420_888.

Đối với Advanced Extender, Camera2/X sẽ truyền 3 bề mặt đầu ra đến lệnh gọi SessionProcessorImpl.initSession(). Các bề mặt đầu ra này lần lượt dành cho chế độ xem trước, chụp ảnh tĩnh và phân tích hình ảnh. Bạn phải đảm bảo rằng các bề mặt đầu ra xem trước và chụp ảnh tĩnh cho thấy đầu ra hợp lệ. Tuy nhiên, đối với bề mặt đầu ra phân tích hình ảnh, hãy đảm bảo rằng bề mặt này chỉ hoạt động khi không có giá trị rỗng. Nếu quá trình triển khai của bạn không hỗ trợ luồng phân tích hình ảnh, bạn có thể trả về một danh sách trống trong AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions(). Điều này đảm bảo bề mặt đầu ra phân tích hình ảnh luôn có giá trị rỗng trong SessionProcessorImpl.initSession().

Hỗ trợ quay video

Cấu trúc Tiện ích camera hiện tại chỉ hỗ trợ các trường hợp sử dụng bản xem trước và chụp ảnh tĩnh. Chúng tôi không hỗ trợ việc bật tiện ích này trên nền tảng MediaCodec hoặc MediaRecorder để ghi hình. Tuy nhiên, các ứng dụng có thể ghi lại đầu ra xem trước.

Chúng tôi đang điều tra việc hỗ trợ các nền tảng MediaCodec và MediaRecorder.

Siêu dữ liệu dành riêng cho tiện ích

Đối với Android 14 trở lên, siêu dữ liệu dành riêng cho tiện ích cho phép các ứng dụng tiện ích camera đặt và nhận các chế độ cài đặt và kết quả yêu cầu chụp dành riêng cho tiện ích. Cụ thể, các ứng dụng tiện ích camera có thể sử dụng tham số yêu cầu chụp EXTENSION_STRENGTH để kiểm soát mức độ mạnh của tiện ích và kết quả chụp EXTENSION_CURRENT_TYPE để cho biết loại tiện ích đã bật.

Yêu cầu chụp ảnh

Tham số yêu cầu chụp EXTENSION_STRENGTH kiểm soát mức độ mạnh của hiệu ứng hậu xử lý tiện ích. Kết quả chụp tương ứng bao gồm giá trị độ mạnh mặc định nếu tham số này không được thiết lập rõ ràng bởi máy khách. Bạn có thể áp dụng tham số này như sau cho các loại tiện ích này:

BOKEH: Kiểm soát mức độ mờ.
HDR và NIGHT: Kiểm soát số lượng hình ảnh được kết hợp và độ sáng của hình ảnh cuối cùng.
FACE_RETOUCH: Kiểm soát mức độ cải thiện thẩm mỹ và làm mịn da.

Phạm vi được hỗ trợ cho tham số EXTENSION_STRENGTH là từ 0 đến 100, trong đó 0 cho biết không có quá trình xử lý phần mở rộng hoặc chỉ truyền qua đơn giản và 100 cho biết cường độ mở rộng tối đa của hiệu ứng xử lý.

Để thêm chế độ hỗ trợ cho EXTENSION_STRENGTH, hãy sử dụng các API tham số dành riêng cho nhà cung cấp được giới thiệu trong phiên bản 1.3.0 của giao diện thư viện tiện ích. Để biết thêm thông tin, hãy xem getAvailableCaptureRequestKeys().

Kết quả chụp

Kết quả chụp EXTENSION_CURRENT_TYPE cho phép các hoạt động triển khai tiện ích thông báo cho ứng dụng về loại tiện ích đang hoạt động.

Vì các tiện ích sử dụng loại AUTO sẽ tự động chuyển đổi giữa các loại tiện ích như HDR và NIGHT tuỳ thuộc vào điều kiện cảnh, nên các ứng dụng tiện ích camera có thể sử dụng EXTENSION_CURRENT_TYPE để hiển thị thông tin về tiện ích hiện tại do tiện ích AUTO chọn.

Ước tính độ trễ khi chụp ảnh tĩnh theo thời gian thực

Đối với Android 14 trở lên, các ứng dụng camera có thể truy vấn thông tin ước tính về độ trễ chụp ảnh tĩnh theo thời gian thực dựa trên điều kiện cảnh và môi trường bằng cách sử dụng getRealtimeStillCaptureLatency(). Phương thức này cung cấp thông tin ước tính chính xác hơn so với phương thức getEstimatedCaptureLatencyRangeMillis() tĩnh. Dựa trên mức ước tính độ trễ, các ứng dụng có thể quyết định bỏ qua quá trình xử lý tiện ích hoặc hiển thị một chỉ báo để thông báo cho người dùng về một thao tác chạy trong thời gian dài.

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();

Để hỗ trợ thông tin ước tính về độ trễ khi chụp ảnh tĩnh theo thời gian thực, hãy triển khai như sau:

Tiện ích cơ bản: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
Tiện ích nâng cao: SessionProcessorImpl.getRealtimeCaptureLatency

Chụp các lệnh gọi lại tiến trình xử lý

Đối với Android 14 trở lên, các ứng dụng tiện ích máy ảnh có thể nhận được lệnh gọi lại cho tiến trình của các thao tác xử lý ảnh chụp tĩnh diễn ra trong thời gian dài. Các ứng dụng có thể hiển thị tiến trình hiện tại cho người dùng để cải thiện trải nghiệm tổng thể của người dùng.

Các ứng dụng có thể sử dụng mã sau để tích hợp tính năng này:

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
    }
  }
…
}

Để hỗ trợ các lệnh gọi lại tiến trình xử lý hoạt động ghi hình, quá trình triển khai của nhà cung cấp tiện ích phải gọi các lệnh gọi lại sau đây bằng giá trị tiến trình hiện tại:

Tiện ích cơ bản: ProcessResultImpl.onCaptureProcessProgressed()
Tiện ích nâng cao: CaptureCallback.onCaptureProcessProgressed()

Ảnh chụp sau khi xem

Đối với Android 14 trở lên, các tiện ích máy ảnh có thể cung cấp một chế độ xem sau (hình ảnh xem trước) bằng cách sử dụng setPostviewOutputConfiguration. Để cải thiện trải nghiệm người dùng, các ứng dụng có thể hiển thị hình ảnh hậu kỳ dưới dạng phần giữ chỗ khi tiện ích đang gặp phải tình trạng tăng độ trễ xử lý và thay thế hình ảnh khi có hình ảnh cuối cùng. Các ứng dụng có thể định cấu hình và đưa ra yêu cầu chụp ảnh sau khi xem bằng mã tham chiếu sau:

{
…
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();
…
}

Để hỗ trợ tính năng chụp ảnh tĩnh sau khi xem, quá trình triển khai của nhà cung cấp phải triển khai những nội dung sau:

Các tiện ích cơ bản: CaptureProcessorImpl.onPostviewOutputSurface và CaptureProcessorImpl.processWithPostview
Tiện ích nâng cao: SessionProcessorImpl.startCaptureWithPostview

Hỗ trợ đầu ra SurfaceView

Đối với Android 14 trở lên, các ứng dụng tiện ích camera có thể sử dụng các đường kết xuất xem trước được tối ưu hoá về hiệu suất và mức tiêu thụ điện năng bằng cách đăng ký một thực thể SurfaceView cho đầu ra xem trước cho các yêu cầu lặp lại.

Để hỗ trợ đầu ra SurfaceView, quá trình triển khai tiện ích của nhà cung cấp phải có khả năng truyền phát và xuất bản xem trước đến các phiên bản SurfaceView. Để xác minh rằng thiết bị có hỗ trợ tính năng này, hãy chạy mô-đun SurfaceViewExtensionPreviewTest.javaCTS.

Loại phiên dành riêng cho nhà cung cấp

Tính năng này cho phép các hoạt động triển khai tiện ích của nhà cung cấp chọn một loại phiên cụ thể của nhà cung cấp sẽ được đặt trong phiên chụp ảnh nội bộ của camera thay vì giá trị mặc định.

Tính năng này hoạt động hoàn toàn trong khuôn khổ và ngăn xếp của nhà cung cấp, đồng thời không ảnh hưởng đến API công khai/máy khách.

Để chọn một loại phiên cụ thể của nhà cung cấp, hãy triển khai những nội dung sau cho các thư viện tiện ích của bạn: * ExtenderStateListener.onSessionType() cho các tiện ích cơ bản * Camera2SessionConfigImpl.getSessionType() cho các tiện ích nâng cao

Nhật ký phiên bản giao diện của tiện ích

Bảng sau đây cho thấy nhật ký phiên bản của giao diện Camera Extension. Bạn nên luôn triển khai thư viện của nhà cung cấp bằng phiên bản mới nhất.

Phiên bản	Các tính năng mới
1.0.0	Xác minh phiên bản `ExtensionVersionImpl` Basic Extender `PreviewExtenderImpl` `ImageCaptureExtenderImpl` `Processor` `PreviewImageProcessorImpl` `CaptureProcessorImpl` `RequestUpdateProcessorImpl`
1.1.0	Khởi chạy thư viện `InitializerImpl` Hiển thị độ phân giải được hỗ trợ `PreviewExtenderImpl.getSupportedResolutions` `ImageCaptureExtenderImpl.getSupportedResolutions`
1.2.0	AdvancedExtender `AdvancedExtenderImpl` `SessionProcessorImpl` Lấy độ trễ chụp ước tính `ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange`
1.3.0	Hiển thị các khoá/kết quả yêu cầu chụp được hỗ trợ `ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys` và `getAvailableCaptureResultKeys` `AdvancedExtenderImpl.getAvailableCaptureRequestKeys` và `getAvailableCaptureResultKeys` Cuộc gọi `process()` mới diễn ra trong `ProcessResultImpl` tại `PreviewImageProcessorImpl` và `CaptureProcessorImpl` Yêu cầu loại trình kích hoạt hỗ trợ `AdvancedExtenderImpl.startTrigger`
1.4.0	Siêu dữ liệu dành riêng cho tiện ích Ước tính độ trễ chụp ảnh tĩnh động Chụp các lệnh gọi lại tiến trình xử lý Ảnh chụp sau khi xem Hỗ trợ đầu ra `SurfaceView` Loại phiên dành riêng cho nhà cung cấp

Triển khai tham chiếu

Các cách triển khai thư viện tham chiếu của nhà cung cấp OEM sau đây có trong frameworks/ex.

advancedSample: Một cách triển khai cơ bản của Advanced Extender.
sample: Cách triển khai cơ bản của Trình mở rộng cơ bản.
service_based_sample: Một phương thức triển khai minh hoạ cách lưu trữ Tiện ích máy ảnh trong Service. Việc triển khai này bao gồm các thành phần sau:
- oem_library: Thư viện Camera Extensions OEM cho Camera2 và CameraX Extensions API triển khai Extensions-Interface. Đây đóng vai trò là một đường truyền chuyển tiếp các lệnh gọi từ Extensions-Interface đến dịch vụ. Thư viện này cũng cung cấp các tệp AIDL và lớp trình bao bọc để giao tiếp với dịch vụ.
  
  Theo mặc định, tính năng Trình mở rộng nâng cao sẽ được bật. Để bật Basic Extender, hãy thay đổi ExtensionsVersionImpl#isAdvancedExtenderImplemented để trả về false.
- extensions_service: Một mẫu triển khai Dịch vụ tiện ích. Thêm quá trình triển khai của bạn vào đây. Giao diện để triển khai trong dịch vụ này tương tự như Extensions-Interface. Ví dụ: việc triển khai IAdvancedExtenderImpl.Stub sẽ thực hiện các thao tác tương tự như AdvancedExtenderImpl. Bạn phải có ImageWrapper và TotalCaptureResultWrapper để tạo Image và TotalCaptureResult có thể phân chia.

Thiết lập thư viện nhà cung cấp trên thiết bị

Thư viện của nhà cung cấp OEM không được tích hợp vào ứng dụng; thư viện này được Camera2/X tải từ thiết bị trong thời gian chạy. Trong CameraX, thẻ <uses-library> khai báo rằng thư viện androidx.camera.extensions.impl (được xác định trong tệp AndroidManifest.xml của thư viện camera-extensions) là một phần phụ thuộc của CameraX và phải được tải trong thời gian chạy. Trong Camera2, khung này tải một dịch vụ tiện ích cũng khai báo rằng <uses-library> tải cùng một thư viện androidx.camera.extensions.impl trong thời gian chạy.

Điều này cho phép các ứng dụng bên thứ ba sử dụng các tiện ích tự động tải thư viện nhà cung cấp OEM. Thư viện OEM được đánh dấu là không bắt buộc để các ứng dụng có thể chạy trên những thiết bị không có thư viện này. Camera2/X tự động xử lý hành vi này khi một ứng dụng cố gắng sử dụng tiện ích camera, miễn là nhà sản xuất thiết bị đặt thư viện OEM trên thiết bị để ứng dụng có thể phát hiện ra thư viện đó.

Để thiết lập thư viện OEM trên thiết bị, hãy làm như sau:

Thêm một tệp quyền (bắt buộc đối với thẻ <uses-library>) bằng cách sử dụng định dạng sau: /etc/permissions/ANY_FILENAME.xml. Ví dụ: /etc/permissions/camera_extensions.xml. Các tệp trong thư mục này cung cấp một mối liên kết giữa thư viện có tên trong <uses-library> với đường dẫn thực tế của tệp trên thiết bị.
Hãy sử dụng ví dụ bên dưới để thêm thông tin bắt buộc vào tệp.
- name phải là androidx.camera.extensions.impl vì đó là thư viện mà CameraX tìm kiếm.
- file là đường dẫn tuyệt đối của tệp chứa quá trình triển khai các tiện ích (ví dụ: /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>
```

Trong Android 12 trở lên, các thiết bị hỗ trợ các tiện ích CameraX phải có thuộc tính ro.camerax.extensions.enabled được đặt thành true, cho phép truy vấn xem một thiết bị có hỗ trợ các tiện ích hay không. Để thực hiện việc này, hãy thêm dòng sau vào tệp make của thiết bị:

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

Xác nhận kết quả

Để kiểm thử việc triển khai thư viện nhà cung cấp OEM trong giai đoạn phát triển, hãy sử dụng ứng dụng mẫu tại androidx-main/camera/integration-tests/extensionstestapp/. Ứng dụng này sẽ chạy thông qua nhiều tiện ích của nhà cung cấp.

Sau khi hoàn tất quá trình triển khai, hãy sử dụng công cụ xác thực các tiện ích camera để chạy các kiểm thử tự động và thủ công nhằm xác minh rằng thư viện của nhà cung cấp được triển khai đúng cách.

Chế độ cảnh mở rộng so với tiện ích máy ảnh

Đối với tiện ích làm mờ nền, ngoài việc hiển thị tiện ích này bằng tiện ích máy ảnh, bạn có thể hiển thị tiện ích này bằng chế độ cảnh mở rộng. Chế độ này được bật thông qua khoá CONTROL_EXTENDED_SCENE_MODE. Để biết thêm thông tin chi tiết về cách triển khai, hãy xem phần Hiệu ứng xoá phông của camera.

Chế độ cảnh mở rộng có ít hạn chế hơn so với các tiện ích camera cho ứng dụng camera2. Ví dụ: bạn có thể bật chế độ cảnh mở rộng trong một phiên bản CameraCaptureSession thông thường hỗ trợ các tổ hợp luồng linh hoạt và tham số yêu cầu chụp. Ngược lại, các tiện ích máy ảnh chỉ hỗ trợ một số loại luồng cố định và có hỗ trợ hạn chế cho các tham số yêu cầu chụp.

Nhược điểm của chế độ cảnh mở rộng là bạn chỉ có thể triển khai chế độ này trong HAL camera. Điều này có nghĩa là chế độ này phải được xác minh để hoạt động trên tất cả các chế độ kiểm soát trực giao mà nhà phát triển ứng dụng có thể sử dụng.

Bạn nên hiển thị hiệu ứng bokeh bằng cả chế độ cảnh mở rộng và Camera Extensions vì các ứng dụng có thể muốn dùng một API cụ thể để bật hiệu ứng bokeh. Trước tiên, bạn nên sử dụng chế độ cảnh mở rộng vì đây là cách linh hoạt nhất để các ứng dụng bật tiện ích làm mờ nền. Sau đó, bạn có thể triển khai giao diện tiện ích camera dựa trên chế độ cảnh mở rộng. Nếu khó triển khai hiệu ứng bokeh trong HAL camera, chẳng hạn như vì hiệu ứng này yêu cầu một bộ xử lý hậu kỳ chạy trong lớp ứng dụng để xử lý hình ảnh, thì bạn nên triển khai tiện ích bokeh bằng giao diện Tiện ích camera.

Câu hỏi thường gặp

Có hạn chế nào về cấp độ API không?

Có. Điều này phụ thuộc vào bộ tính năng API Android mà quá trình triển khai thư viện của nhà cung cấp OEM yêu cầu. Ví dụ: ExtenderStateListener.onPresetSession() sử dụng lệnh gọi SessionConfiguration.setSessionParameters() để đặt một nhóm thẻ cơ sở. Lệnh gọi này chỉ có ở API cấp 28 trở lên. Để biết thông tin chi tiết về các phương thức giao diện cụ thể, hãy xem tài liệu tham khảo API.

Tiện ích Camera Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Kiến trúc

Triển khai thư viện nhà cung cấp OEM

Xác minh phiên bản

Khả năng tương thích với phiên bản chính

Khả năng tương thích ngược

Khả năng tương thích chuyển tiếp

Khởi chạy thư viện của nhà cung cấp

Thanh nối dài cơ bản so với thanh nối dài nâng cao

Luồng ứng dụng

Thanh nối dài cơ bản

Luồng ứng dụng 1: Kiểm tra phạm vi cung cấp tiện ích

Luồng ứng dụng 2: Truy vấn thông tin

Luồng ứng dụng 3: Xem trước/chụp ảnh tĩnh khi bật tiện ích (triển khai HAL)

Trình xử lý xem trước

Bộ xử lý chụp ảnh

Hỗ trợ các khoá và kết quả của yêu cầu chụp

Advanced Extender

Các tệp cần triển khai

Luồng ứng dụng 1: Kiểm tra phạm vi cung cấp tiện ích

Luồng ứng dụng 2: Truy vấn thông tin

Luồng ứng dụng 3: Xem trước/chụp ảnh tĩnh khi bật tiện ích

Hỗ trợ xem trước, chụp ảnh tĩnh và phân tích hình ảnh

Hỗ trợ quay video

Siêu dữ liệu dành riêng cho tiện ích

Yêu cầu chụp ảnh

Kết quả chụp

Ước tính độ trễ khi chụp ảnh tĩnh theo thời gian thực

Chụp các lệnh gọi lại tiến trình xử lý

Ảnh chụp sau khi xem

Hỗ trợ đầu ra SurfaceView

Loại phiên dành riêng cho nhà cung cấp

Nhật ký phiên bản giao diện của tiện ích

Triển khai tham chiếu

Thiết lập thư viện nhà cung cấp trên thiết bị

Xác nhận kết quả

Chế độ cảnh mở rộng so với tiện ích máy ảnh

Câu hỏi thường gặp

Có hạn chế nào về cấp độ API không?

Tiện ích Camera