카메라 확장 프로그램

기기 제조업체는 OEM 공급업체 라이브러리에서 제공하는 카메라 확장 프로그램 인터페이스를 통해 빛망울 효과, 야간 모드, HDR과 같은 확장 프로그램을 서드 파티 개발자에게 노출할 수 있습니다. 개발자는 Camera2 Extensions API 및 CameraX Extensions API를 사용하여 OEM 공급업체 라이브러리에 구현된 확장 프로그램에 액세스할 수 있습니다.

지원되는 확장 프로그램 목록(Camera2와 CameraX 간에 동일)은 CameraX Extensions API를 참고하세요. 확장 프로그램을 추가하려면 Issue Tracker를 사용하여 버그를 신고하세요.

이 페이지에서는 기기에서 OEM 공급업체 라이브러리를 구현하고 사용 설정하는 방법을 설명합니다.

아키텍처

다음 다이어그램은 카메라 확장 프로그램 인터페이스 또는 extensions-interface의 아키텍처를 설명합니다.

그림 1. 카메라 확장 프로그램 아키텍처 다이어그램

다이어그램과 같이 카메라 확장 프로그램을 지원하려면 OEM 공급업체 라이브러리에서 제공하는 extensions-interface를 구현해야 합니다. OEM 공급업체 라이브러리는 각각 CameraX 및 Camera2 앱에서 사용하는 두 API인 CameraX Extensions API와 Camera2 Extensions API를 사용 설정하여 공급업체 확장 프로그램에 액세스합니다.

OEM 공급업체 라이브러리 구현

OEM 공급업체 라이브러리를 구현하려면 camera-extensions-stub 파일을 시스템 라이브러리 프로젝트에 복사합니다. 이러한 파일은 카메라 확장 프로그램 인터페이스를 정의합니다.

camera-extensions-stub 파일은 다음 카테고리로 분류됩니다.

필수 인터페이스 파일(수정하면 안 됨)

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

필수 구현(구현 추가)

ExtensionVersionImpl.java
InitializerImpl.java

빛망울 효과 확장기 클래스(빛망울 효과 확장 프로그램이 지원되는 경우 구현)

BokehImageCaptureExtenderImpl.java
BokehPreviewExtenderImpl.java
advanced/BokehAdvancedExtenderImpl.java

야간 확장기 클래스(야간 확장 프로그램이 지원되는 경우 구현)

NightImageCaptureExtenderImpl.java
NightPreviewExtenderImpl.java
advanced/NightAdvancedExtenderImpl.java

자동 확장기 클래스(자동 확장 프로그램이 지원되는 경우 구현)

AutoImageCaptureExtenderImpl.java
AutoPreviewExtenderImpl.java
advanced/AutoAdvancedExtenderImpl.java

HDR 확장기 클래스(HDR 확장 프로그램이 지원되는 경우 구현)

HdrImageCaptureExtenderImpl.java
HdrPreviewExtenderImpl.java
advanced/HdrAdvancedExtenderImpl.java

얼굴 보정 확장기 클래스(얼굴 보정 확장 프로그램이 지원되는 경우 구현)

BeautyImageCaptureExtenderImpl.java
BeautyPreviewExtenderImpl.java
advanced/BeautyAdvancedExtenderImpl.java

유틸리티(선택사항, 삭제 가능)

advanced/Camera2OutputConfigImplBuilder.java
advanced/Camera2SessionConfigImplBuilder.java

모든 확장 프로그램의 구현을 제공할 필요는 없습니다. 확장 프로그램을 구현하지 않는 경우 false를 반환하도록 isExtensionAvailable()을 설정하거나 상응하는 확장기 클래스를 삭제합니다. Camera2 Extensions API와 CameraX Extensions API는 확장 프로그램을 사용할 수 없다고 앱에 보고합니다.

Camera2 및 CameraX Extensions API가 공급업체 라이브러리와 상호작용하여 확장 프로그램을 사용 설정하는 방법을 살펴보겠습니다. 다음 다이어그램은 야간 확장 프로그램을 사용한 엔드 투 엔드 흐름을 예로 보여줍니다.

Mainflow

그림 2. 야간 확장 프로그램 구현

버전 확인

Camera2/X는 ExtensionVersionImpl.checkApiVersion()을 호출하여 OEM에서 구현한 extensions-interface 버전이 Camera2/X 지원 버전과 호환되는지 확인합니다.
공급업체 라이브러리 초기화

InitializerImpl에는 공급업체 라이브러리를 초기화하는 init() 메서드가 있습니다. Camera2/X는 확장기 클래스에 액세스하기 전에 초기화를 완료합니다.
확장기 클래스 인스턴스화

확장 프로그램의 확장기 클래스를 인스턴스화합니다. 확장기에는 두 가지 유형인 기본 확장기와 고급 확장기가 있습니다. 모든 확장 프로그램에 한 가지 확장기 유형을 구현해야 합니다. 자세한 내용은 기본 확장기와 고급 확장기 비교를 참고하세요.

Camera2/X는 확장기 클래스를 인스턴스화하고 이 클래스와 상호작용하여 정보를 검색하고 확장 프로그램을 사용 설정합니다. Camera2/X는 한 확장 프로그램에 대해 확장기 클래스를 여러 번 인스턴스화할 수 있습니다. 따라서 생성자에서 또는 init() 호출에서 복잡한 초기화 작업을 하지 마세요. onInit()가 기본 확장기에서 호출되거나 initSession()이 고급 확장기에서 호출되는 경우와 같이 카메라 세션이 시작되려고 할 때만 복잡한 초기화 작업을 실행하세요.

야간 확장 프로그램의 경우 다음 확장기 클래스가 기본 확장기 유형에 인스턴스화됩니다.
- NightImageCaptureExtenderImpl.java
- NightPreviewExtenderImpl.java
고급 확장기 유형에는 다음 확장기 클래스가 인스턴스화됩니다.
- NightAdvancedExtenderImpl.java
확장 프로그램 사용 가능 여부 확인

확장 프로그램을 사용 설정하기 전에 isExtensionAvailable()은 지정된 카메라 ID에서 확장기 인스턴스를 통해 확장 프로그램을 사용할 수 있는지 확인합니다.
카메라 정보로 확장기 초기화

Camera2/X는 확장기 인스턴스에서 init()를 호출하여 카메라 ID 및 CameraCharacteristics를 전달합니다.
쿼리 정보

확장기 클래스를 호출하여 정보(예: 지원되는 해상도)를 검색하고 예상 지연 시간을 스틸 캡처하며 확장 프로그램을 사용할 수 있도록 준비하기 위해 확장기에서 요청 키를 캡처합니다.
확장기에서 확장 프로그램 사용 설정

확장기 클래스는 클래스를 사용 설정하는 데 필요한 모든 인터페이스를 제공합니다. 캡처 요청 매개변수를 삽입하거나 포스트 프로세서를 사용 설정하는 등 OEM 구현을 Camera2 파이프라인에 연결하는 메커니즘을 제공합니다.

고급 확장기 유형의 경우 Camera2/X는 SessionProcessorImpl과 상호작용하여 확장 프로그램을 사용 설정합니다. Camera2/X는 확장기에서 createSessionProcessor()를 호출하여 SessionProcessorImpl 인스턴스를 가져옵니다.

다음 섹션에서는 확장 프로그램 흐름을 자세히 설명합니다.

버전 확인

런타임에 기기에서 OEM 공급업체 라이브러리를 로드할 때 Camera2/X는 라이브러리가 extensions-interface 버전과 호환되는지 확인합니다. extensions-interface는 시맨틱 버전 관리 또는 MAJOR.MINOR.PATCH(예: 1.1.0 또는 1.2.0)를 사용합니다. 그러나 버전 확인 중에는 메이저 버전과 마이너 버전만 사용됩니다.

버전을 확인하기 위해 Camera2/X는 지원되는 extensions-interface 버전으로 ExtensionVersionImpl.checkApiVersion()을 호출합니다. 그런 다음 Camera2/X는 OEM 라이브러리에서 보고된 버전을 사용하여 확장 프로그램을 사용 설정할 수 있는지, 어떤 기능을 호출해야 하는지 확인합니다.

메이저 버전 호환성

extension-interface의 메이저 버전이 Camera2/X와 공급업체 라이브러리 간에 다르면 호환되지 않는 것으로 간주하고 확장 프로그램은 사용 중지됩니다.

이전 버전과의 호환성

메이저 버전이 동일한 경우 Camera2/X는 이전 extensions-interface 버전으로 빌드된 OEM 공급업체 라이브러리와의 하위 호환성을 보장합니다. 예를 들어 Camera2/X가 extensions-interface 1.3.0을 지원하는 경우 1.0.0, 1.1.0, 1.2.0을 구현한 OEM 공급업체 라이브러리는 계속 호환됩니다. 또한 특정 버전의 공급업체 라이브러리가 구현된 후 Camera2/X는 라이브러리가 향후 extension-interface 버전과 하위 호환되도록 합니다.

향후 호환성

최신 extensions-interface 공급업체 라이브러리와의 향후 호환성은 OEM에 따라 다릅니다. 확장 프로그램을 구현하는 데 일부 기능이 필요하다면 특정 버전에서 시작하는 확장 프로그램을 사용 설정하는 것이 좋습니다. 이 경우 Camera2/X 라이브러리 버전이 요구사항을 충족하면 지원되는 extensions-interface 버전을 반환할 수 있습니다. Camera2/X 버전이 지원되지 않으면 99.0.0과 같은 호환되지 않는 버전을 반환하여 확장 프로그램을 사용 중지할 수 있습니다.

공급업체 라이브러리 초기화

OEM 라이브러리에서 구현한 extensions-interface 버전을 확인한 후 Camera2/X는 초기화 프로세스를 시작합니다. InitializerImpl.init() 메서드는 앱이 확장 프로그램을 사용하려고 한다고 OEM 라이브러리에 알립니다.

Camera2/X는 OEM 공급업체 라이브러리가 OnExtensionsInitializedCallback.onSuccess()를 호출하여 초기화 완료를 알릴 때까지 OEM 라이브러리에 대한 다른 호출을 하지 않습니다(버전 확인 제외).

extensions-interface 1.1.0부터 InitializerImpl을 구현해야 합니다. Camera2/X는 OEM 공급업체 라이브러리가 extensions-interface 1.0.0을 구현하면 라이브러리 초기화 단계를 건너뜁니다.

기본 확장기와 고급 확장기 비교

extensions-interface 구현에는 기본 확장기와 고급 확장기라는 두 가지 유형이 있습니다. 고급 확장기는 extensions-interface 1.2.0부터 지원되었습니다.

카메라 HAL에서 이미지를 처리하거나 YUV 스트림을 처리할 수 있는 포스트 프로세서를 사용하는 확장 프로그램에 기본 확장기를 구현합니다.

Camera2 스트림 구성을 맞춤설정하고 필요에 따라 캡처 요청을 전송해야 하는 확장 프로그램에 고급 확장기를 구현합니다.

다음 표를 참고하여 비교해 보세요.

	기본 확장기	고급 확장기
스트림 구성	고정 미리보기: `PRIVATE` 또는 `YUV_420_888`(프로세서가 있는 경우) 스틸 캡처: `JPEG` 또는 `YUV_420_888`(프로세서가 있는 경우)	OEM이 맞춤설정할 수 있음
캡처 요청 전송	Camera2/X만 캡처 요청을 보낼 수 있습니다. 매개변수를 이러한 요청으로 설정할 수 있습니다. 이미지 캡처를 위한 프로세서가 제공되면 Camera2/X는 여러 캡처 요청을 보내고 모든 이미지와 캡처 결과를 프로세서에 전송할 수 있습니다.	camera2 캡처 요청을 실행하고 결과와 이미지를 가져올 수 있는 `RequestProcessorImpl` 인스턴스가 제공됩니다. Camera2/X는 `SessionProcessorImpl`에서 `startRepeating` 및 `startCapture`를 호출하여 OEM에 미리보기 반복 요청을 시작하고 스틸 캡처 시퀀스를 각각 시작하도록 알립니다.
카메라 파이프라인의 후크	`onPresetSession`은 세션 매개변수를 제공합니다. `onEnableSession`은 `CameraCaptureSession`이 구성된 직후 단일 요청을 전송합니다. `onDisableSession`은 `CameraCaptureSession`이 닫히기 전에 단일 요청을 전송합니다.	`initSession`은 캡처 세션을 만들기 위해 맞춤설정된 camera2 세션 구성을 초기화하고 반환합니다. `onCaptureSessionStart`는 `CameraCaptureSession`이 구성된 직후 호출됩니다. `onCaptureSessionEnd`는 `CameraCaptureSession`이 닫히기 전에 호출됩니다.
적합한 경우	카메라 HAL 또는 YUV 이미지를 처리하는 프로세서에 구현된 확장 프로그램	Camera2 기반 확장 프로그램의 구현을 포함합니다. RAW 스트림과 같은 맞춤설정된 스트림 구성이 필요합니다. 양방향 캡처 시퀀스가 필요합니다.
지원되는 API 버전	Camera2 확장 프로그램: Android 13 이상 CameraX 확장 프로그램: `camera-extensions` 1.1.0 이상	Camera2 확장 프로그램: Android 12L 이상 CameraX 확장 프로그램: `camera-extensions` 1.2.0-alpha03 이상

앱 흐름

다음 표에는 세 가지 유형의 앱 흐름과 이에 상응하는 카메라 확장 프로그램 API 호출이 나와 있습니다. Camera2/X는 이러한 API를 제공하지만 공급업체 라이브러리를 올바르게 구현하여 이러한 흐름을 지원해야 합니다. 이 내용은 이후 섹션에서 자세히 설명합니다.

Camera2 확장 프로그램 CameraX 확장 프로그램

쿼리 확장 프로그램 사용 가능 여부 CameraExtensionCharacteristics .getSupportedExtensions ExtensionsManager. isExtensionAvailable

	Camera2 확장 프로그램	CameraX 확장 프로그램
쿼리 확장 프로그램 사용 가능 여부	`CameraExtensionCharacteristics .getSupportedExtensions`	`ExtensionsManager. isExtensionAvailable`
쿼리 정보	`CameraExtensionCharacteristics. getExtensionSupportedSizes` `CameraExtensionCharacteristics. getEstimatedCaptureLatencyRangeMillis` `CameraExtensionCharacteristics. getAvailableCaptureRequestKeys` `CameraExtensionCharacteristics. getAvailableCaptureResultKeys`	`ExtensionsManager. getEstimatedCaptureLatencyRange` CameraX는 라이브러리 내 나머지 정보를 처리합니다.
확장 프로그램이 사용 설정된 미리보기 및 스틸 캡처	`CameraDevice. createExtensionSession` `cameraExtensionsSession. setRepeatingRequest` `cameraExtensionsSession. capture`	`val cameraSelector = ExtensionsManager. getExtensionEnabledCameraSelector` `bindToLifecycle(lifecycleOwner, cameraSelector, preview, ...)`

쿼리 정보

CameraExtensionCharacteristics.
   getExtensionSupportedSizes

CameraExtensionCharacteristics.
getEstimatedCaptureLatencyRangeMillis

CameraExtensionCharacteristics.
getAvailableCaptureRequestKeys

CameraExtensionCharacteristics.
getAvailableCaptureResultKeys

ExtensionsManager.
   getEstimatedCaptureLatencyRange

CameraX는 라이브러리 내 나머지 정보를 처리합니다.

확장 프로그램이 사용 설정된 미리보기 및 스틸 캡처

CameraDevice.
   createExtensionSession

cameraExtensionsSession. setRepeatingRequest

cameraExtensionsSession. capture

val cameraSelector = ExtensionsManager.
   getExtensionEnabledCameraSelector

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

기본 확장기

기본 확장기 인터페이스는 카메라 파이프라인의 여러 위치에 후크를 제공합니다. 각 확장 프로그램 유형에는 OEM이 구현해야 하는 상응하는 확장기 클래스가 있습니다.

다음 표에는 OEM이 각 확장 프로그램에 구현해야 하는 확장기 클래스가 나열되어 있습니다.

	구현할 확장기 클래스
야간	`NightPreviewExtenderImpl.java` `NightImageCaptureExtenderImpl.java`
HDR	`HdrPreviewExtenderImpl.java HdrImageCaptureExtenderImpl.java`
자동	`AutoPreviewExtenderImpl.java AutoImageCaptureExtenderImpl.java`
빛망울 효과	`BokehPreviewExtenderImpl.java BokehImageCaptureExtenderImpl.java`
얼굴 보정	`BeautyPreviewExtenderImpl.java BeautyImageCaptureExtenderImpl.java`

다음 예에서는 PreviewExtenderImpl 및 ImageCaptureExtenderImpl을 자리표시자로 사용합니다. 구현 중인 실제 파일의 이름으로 이를 바꿉니다.

기본 확장기에는 다음 기능이 있습니다.

CameraCaptureSession(onPresetSession)을 구성할 때 세션 매개변수를 삽입합니다.
캡처 세션 시작 및 닫기 이벤트를 알려주고 반환된 매개변수(onEnableSession, onDisableSession)를 사용하여 HAL에 알리는 단일 요청을 전송합니다.
요청에 관한 캡처 매개변수(PreviewExtenderImpl.getCaptureStage, ImageCaptureExtenderImpl.getCaptureStages)를 삽입합니다.
YUV_420_888 스트림을 처리할 수 있는 미리보기 및 스틸 캡처용 프로세서를 추가합니다.

Camera2/X가 extensions-interface를 호출하여 위에 설명한 앱 흐름 세 개를 달성하는 방법을 살펴보겠습니다.

앱 흐름 1: 확장 프로그램 사용 가능 여부 확인

BasicExtenderAppFlow1

그림 3. 기본 확장기의 앱 흐름 1

이 흐름에서 Camera2/X는 init()를 호출하지 않고 PreviewExtenderImpl 및 ImageCaptureExtenderImpl의 isExtensionAvailable() 메서드를 직접 호출합니다. 두 확장기 클래스는 모두 true를 반환하여 확장 프로그램을 사용 설정해야 합니다.

이는 일반적으로 확장 프로그램을 사용 설정하기 전에 지정된 확장 프로그램 유형이 특정 카메라 ID에서 지원되는지 확인하는 첫 번째 단계입니다. 일부 확장 프로그램은 특정 카메라 ID에서만 지원되기 때문입니다.

앱 흐름 2: 쿼리 정보

BasicExtenderAppFlow2

그림 4. 기본 확장기의 앱 흐름 2

확장 프로그램을 사용할 수 있는지 확인한 후에는 앱이 확장 프로그램을 사용 설정하기 전에 다음 정보를 쿼리해야 합니다.

스틸 캡처 지연 시간 범위: ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange는 앱이 현재 시나리오의 확장 프로그램을 사용 설정하는 것이 적절한지 평가할 수 있도록 캡처 지연 시간 범위를 반환합니다.
지원되는 미리보기 및 캡처 표면 크기: ImageCaptureExtenderImpl.getSupportedResolutions 및 PreviewExtenderImpl.getSupportedResolutions는 이미지 형식 목록과 표면 형식 및 크기에 지원되는 크기를 반환합니다.
지원되는 요청 및 결과 키: Camera2/X는 다음 메서드를 호출하여 지원되는 캡처 요청 키와 결과 키를 구현에서 검색합니다.
- ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys
- ImageCaptureExtenderImpl.getAvailableCapturetResultKeys

Camera2/X는 자세한 정보를 쿼리하기 전에 항상 이러한 확장기 클래스에서 먼저 init()를 호출합니다.

앱 흐름 3: 확장 프로그램이 사용 설정된 미리보기/스틸 캡처(HAL 구현)

BasicExtenderAppFlow3

그림 5. 기본 확장기의 앱 흐름 3

위 다이어그램은 프로세서 없이 확장 프로그램을 사용하여 미리보기와 스틸 캡처를 사용 설정하는 기본 흐름을 보여줍니다. 즉, 카메라 HAL에서 확장 프로그램을 처리합니다.

이 흐름에서 Camera2/X는 먼저 init()를 호출하고 onInit를 호출하므로 지정된 확장 프로그램으로 카메라 세션이 곧 시작한다고 알립니다. onInit()에서 복잡한 초기화를 실행할 수 있습니다.

CameraCaptureSession을 구성할 때 Camera2/X는 onPresetSession을 호출하여 세션 매개변수를 가져옵니다. 캡처 세션이 성공적으로 구성되면 Camera2/X는 캡처 매개변수가 포함된 CaptureStageImpl 인스턴스를 반환하는 onEnableSession을 호출합니다. Camera2/X는 이러한 캡처 매개변수와 함께 단일 요청을 즉시 전송하여 HAL에 알립니다. 마찬가지로 캡처 세션이 종료되기 전에 Camera2/X는 onDisableSession을 호출하고 반환된 캡처 매개변수와 함께 단일 요청을 전송합니다.

Camera2/X에 의해 트리거되는 반복 요청에는 PreviewExtenderImpl.getCaptureStage()에서 반환한 요청 매개변수가 포함됩니다. 또한 스틸 캡처 요청에는 ImageCaptureExtenderImpl.getCaptureStages()에서 반환한 매개변수가 포함됩니다.

마지막으로 Camera2/X는 카메라 세션이 완료된 후 onDeInit()를 호출합니다. onDeinit()에서 리소스를 해제할 수 있습니다.

미리보기 프로세서

카메라 HAL 외에도 프로세서에서 확장 프로그램을 구현할 수도 있습니다.

PreviewExtenderImpl.getProcessorType을 구현하여 아래에 설명된 대로 프로세서 유형을 지정합니다.

PROCESSOR_TYPE_NONE: 프로세서 없음. 이미지가 카메라 HAL에서 처리됩니다.
PROCESSOR_TYPE_REQUEST_UPDATE_ONLY: 이 프로세서 유형을 사용하면 최신 TotalCaptureResult를 기반으로 하는 새로운 캡처 요청 매개변수로 반복 요청을 업데이트할 수 있습니다.

PreviewExtenderImpl.getProcessor는 TotalCaptureResult 인스턴스를 처리하고 CaptureStageImpl 인스턴스를 반환하여 반복 요청을 업데이트하는 RequestUpdateProcessorImpl 인스턴스를 반환해야 합니다. PreviewExtenderImpl.getCaptureStage()는 또한 처리 결과를 반영하고 최신 CaptureStageImpl을 반환해야 합니다.
PROCESSOR_TYPE_IMAGE_PROCESSOR: 이 유형을 사용하면 YUV_420_888 이미지를 처리하고 PRIVATE 표면에 출력을 쓰는 프로세서를 구현할 수 있습니다.

PreviewExtenderImpl.getProcessor에서 PreviewImageProcessorImpl 인스턴스를 구현하고 반환해야 합니다. 프로세서는 YUV_420_888 입력 이미지를 처리합니다. 미리보기의 PRIVATE 형식으로 출력을 써야 합니다. Camera2/X는 PRIVATE 대신 YUV_420_888 표면을 사용하여 미리보기용 CameraCaptureSession을 구성합니다.

흐름에 관한 다음 그림을 참고하세요.

PreviewProcessor

그림 6. PreviewImageProcessorImpl을 사용한 미리보기 흐름

PreviewImageProcessorImpl 인터페이스는 ProcessImpl을 확장하며 세 가지 중요한 메서드를 포함하고 있습니다.

onOutputSurface(Surface surface, int imageFormat)은 프로세서의 출력 표면을 설정합니다. PreviewImageProcessorImpl의 경우 imageFormat은 PixelFormat.RGBA_8888과 같은 픽셀 형식입니다.
onResolutionUpdate(Size size)는 입력 이미지의 크기를 설정합니다.
onImageFormatUpdate(int imageFormat)은 입력 이미지의 이미지 형식을 설정합니다. 현재는 YUV_420_888만 가능합니다.

이미지 캡처 프로세서

스틸 캡처의 경우 ImageCaptureExtenderImpl.getCaptureProcessor를 사용하여 CaptureProcessorImpl 인스턴스를 반환해 프로세서를 구현할 수 있습니다. 프로세서는 캡처된 YUV_420_888 이미지 및 TotalCaptureResult 인스턴스의 목록을 처리하고 YUV_420_888 표면에 출력을 씁니다.

스틸 캡처 요청을 전송하기 전에 미리보기가 사용 설정되어 실행 중이라고 가정해도 됩니다.

아래 다이어그램의 흐름을 참고하세요.

CaptureProcessor

그림 7. CaptureProcessorImpl을 사용한 스틸 캡처 흐름

Camera2/X는 스틸 캡처에 YUV_420_888 형식 표면을 사용하여 캡처 세션을 구성합니다. Camera2/X는 다음을 호출하여 CaptureProcessorImpl을 준비합니다.
- YUV_420_888로 CaptureProcessorImpl.onImageFormatUpdate() 호출
- 입력 이미지 크기로 CaptureProcessorImpl.onResolutionUpdate() 호출
- 출력 YUV_420_888 표면으로 CaptureProcessorImpl.onOutputSurface() 호출
ImageCaptureExtenderImpl.getCaptureStages는 CaptureStageImpl의 목록을 반환하며 여기서 각 요소는 Camera2/X에 의해 전송된 캡처 매개변수가 있는 CaptureRequest 인스턴스에 매핑됩니다. 예를 들어 CaptureStageImpl 인스턴스 세 개가 있는 목록이 반환되면 Camera2/X는 captureBurst API를 사용하여 이에 상응하는 캡처 매개변수와 함께 세 개의 캡처 요청을 전송합니다.

참고: getCaptureStages()는 getCaptureProcessor()에서 인스턴스를 반환할 때만 CaptureStageImpl 인스턴스를 두 개 이상 반환할 수 있습니다.
수신된 이미지 및 TotalCaptureResult 인스턴스는 함께 번들로 묶여 처리를 위해 CaptureProcessorImpl로 전송됩니다.
CaptureProcessorImpl은 결과 이미지(YUV_420_888 형식)를 onOutputSurface() 호출에서 지정한 출력 표면에 씁니다. 필요한 경우 Camera2/X는 이를 JPEG 이미지로 변환합니다.

캡처 요청 키 및 결과 지원

카메라 미리보기와 캡처 외에도 앱은 확대/축소, 플래시 매개변수를 설정하거나 탭하여 초점 맞추기를 트리거할 수 있습니다. 이러한 매개변수는 확장 프로그램 구현과 호환되지 않을 수 있습니다.

구현에서 지원하는 매개변수를 노출할 수 있도록 다음 메서드를 extensions-interface 1.3.0에 추가했습니다.

ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys()는 구현에서 지원하는 캡처 요청 키를 반환합니다.
ImageCaptureExtenderImpl.getAvailableCaptureResultKeys()는 캡처 결과에 포함된 캡처 결과 키를 반환합니다.

카메라 HAL이 확장 프로그램을 처리하는 경우 Camera2/X는 CameraCaptureSession.CaptureCallback에서 캡처 결과를 검색합니다. 하지만 프로세서가 구현되면 Camera2/X는 ProcessResultImpl에서 캡처 결과를 검색하며 이는 PreviewImageProcessorImpl 및 CaptureProcessorImpl의 process() 메서드에 전달됩니다. 개발자는 ProcessResultImpl을 통해 Camera2/X에 캡처 결과를 보고해야 합니다.

예를 들어 아래의 CaptureProcessorImpl 인터페이스 정의를 참고하세요. extensions-interface 1.3.0 이상에서는 두 번째 process() 호출이 호출됩니다.

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

확대/축소, 탭하여 초점 맞추기, 플래시, 노출 보정과 같은 일반적인 카메라 작업의 경우 캡처 요청 및 캡처 결과 모두에 다음 키를 지원하는 것이 좋습니다.

확대/축소
- CaptureRequest#CONTROL_ZOOM_RATIO
- CaptureRequest#SCALER_CROP_REGION
탭하여 초점 맞추기
- CaptureRequest#CONTROL_AF_MODE
- CaptureRequest#CONTROL_AF_TRIGGER
- CaptureRequest#CONTROL_AF_REGIONS
- CaptureRequest#CONTROL_AE_REGIONS
- CaptureRequest#CONTROL_AWB_REGIONS
플래시
- CaptureRequest#CONTROL_AE_MODE
- CaptureRequest#CONTROL_AE_PRECAPTURE_TRIGGER
- CaptureRequest#FLASH_MODE
노출 보정
- CaptureRequest#CONTROL_AE_EXPOSURE_COMPENSATION

1.2.0 이하 버전을 구현하는 기본 확장기의 경우 CameraX Extensions API는 위의 모든 키를 명시적으로 지원합니다. extensions-interface 1.3.0의 경우 CameraX와 Camera2가 모두 반환된 목록을 준수하고 목록에 포함된 키만 지원합니다. 예를 들어 1.3.0 구현에서 CaptureRequest#CONTROL_ZOOM_RATIO 및 CaptureRequest#SCALER_CROP_REGION만 반환하기로 하면 확대/축소만 앱에 지원되고 탭하여 초점 맞추기, 플래시, 노출 보정은 허용되지 않는 것을 의미합니다.

고급 확장기

고급 확장기는 Camera2 API를 기반으로 한 공급업체 구현 유형입니다. 이 확장기 유형이 extensions-interface 1.2.0에 추가되었습니다. 기기 제조업체에 따라 확장 프로그램은 앱 레이어에 구현될 수 있으며 다음 요소에 따라 달라집니다.

맞춤 스트림 구성: RAW 스트림과 같은 맞춤 스트림을 구성하거나 다양한 물리적 카메라 ID의 여러 스트림이 있습니다.
Camera2 요청 전송 기능: 이전 요청 결과에 기반하여 매개변수와 함께 캡처 요청을 전송할 수 있는 복잡한 상호작용 로직을 지원합니다.

고급 확장기를 사용하면 래퍼 또는 중간 레이어가 제공되므로 스트림 구성을 맞춤설정하고 요청 시 캡처 요청을 전송할 수 있습니다.

구현할 파일

고급 확장기 구현으로 전환하려면 ExtensionVersionImpl의 isAdvancedExtenderImplemented() 메서드가 true를 반환해야 합니다. 각 확장 프로그램 유형의 경우 OEM은 상응하는 확장기 클래스를 구현해야 합니다. 고급 확장기 구현 파일은 advanced 패키지에 있습니다.

	구현할 확장기 클래스
야간	`advanced/NightAdvancedExtenderImpl.java`
HDR	`advanced/HdrAdvancedExtenderImpl.java`
자동	`advanced/AutoAdvancedExtenderImpl.java`
빛망울 효과	`advanced/BokehAdvancedExtenderImpl.java`
얼굴 보정	`advanced/BeautyAdvancedExtenderImpl.java`

다음 예에서는 AdvancedExtenderImpl을 자리표시자로 사용합니다. 구현 중인 확장 프로그램의 확장기 파일 이름으로 이를 바꿉니다.

Camera2/X가 extensions-interface를 호출하여 3가지 앱 흐름을 달성하는 방법을 살펴보겠습니다.

앱 흐름 1: 확장 프로그램 사용 가능 여부 확인

AdvancedAppFlow1

그림 8. 고급 확장기의 앱 흐름 1

먼저 앱에서는 지정된 확장 프로그램이 지원되는지 확인합니다.

앱 흐름 2: 쿼리 정보

AdvancedAppFlow2

그림 9. 고급 확장기의 앱 흐름 2

AdvancedExtenderImpl.init()를 호출하면 앱에서는 AdvancedExtenderImpl에 관한 다음 정보를 쿼리할 수 있습니다.

예상 스틸 캡처 지연 시간: AdvancedExtenderImpl.getEstimatedCaptureLatencyRange()는 앱이 현재 시나리오의 확장 프로그램을 사용 설정하는 것이 적절한지 평가할 수 있도록 캡처 지연 시간 범위를 반환합니다.
미리보기 및 스틸 캡처에 지원되는 해상도:
- AdvancedExtenderImpl.getSupportedPreviewOutputResolutions()는 미리보기 표면 형식 및 크기에 지원되는 크기 목록으로 이미지 형식의 맵을 반환합니다. OEM은 최소한 PRIVATE 형식을 지원해야 합니다.
- AdvancedExtenderImpl.getSupportedCaptureOutputResolutions()는 스틸 캡처 표면에 지원되는 형식과 크기를 반환합니다. OEM은 JPEG 및 YUV_420_888 형식 출력을 모두 지원해야 합니다.
- AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions()는 이미지 분석을 위해 추가 YUV_420_888 스트림의 지원되는 크기를 반환합니다. 이미지 분석 YUV 표면이 지원되지 않으면 getSupportedYuvAnalysisResolutions()는 null 또는 빈 목록을 반환해야 합니다.
사용 가능한 캡처 요청 키/결과(extensions-interface 1.3.0에 추가됨): Camera2/X는 다음 메서드를 호출하여 지원되는 캡처 요청 키와 결과 키를 구현에서 가져옵니다.
- AdvancedExtenderImpl.getAvailableCaptureRequestKeys
- AdvancedExtenderImpl.getAvailableCaptureResultKeys

자세한 내용은 캡처 요청 키 및 결과 지원을 참고하세요.

앱 흐름 3: 확장 프로그램이 사용 설정된 미리보기/스틸 캡처

AdvancedAppFlow3

그림 10. 고급 확장기의 앱 흐름 3

위 다이어그램은 고급 확장기 유형의 미리보기와 스틸 캡처를 시작하는 기본 흐름을 보여줍니다. 각 단계를 살펴보겠습니다.

SessionProcessorImpl 인스턴스

핵심 고급 확장기 구현은 SessionProcessorImpl에 있으며, 맞춤설정된 세션 구성을 제공하고 캡처 요청을 전송하여 미리보기 및 스틸 캡처 요청을 초기화합니다. AdvancedExtenderImpl.createSessionProcessor()를 호출하면 SessionProcessorImpl 인스턴스가 반환됩니다.

참고: 카메라 세션에서는 SessionProcessorImpl 인스턴스를 여러 번 사용할 수 있습니다. 따라서 구현은 SessionProcessorImpl 인스턴스 하나에 여러 initSession() 및 deInitSession() 호출을 지원할 수 있어야 합니다.
initSession

SessionProcessorImpl.initSession()은 확장 프로그램의 세션을 초기화합니다. 여기에서 리소스를 할당하고 CameraCaptureSession을 준비하기 위한 세션 구성을 반환합니다.

입력 매개변수의 경우 Camera2/X는 미리보기, 스틸 캡처, 선택적 YUV 이미지 분석을 위한 출력 표면 구성을 지정합니다. 이 출력 표면 구성(OutputSurfaceImpl)에는 AdvancedExtenderImpl의 다음 메서드로 가져온 표면과 크기, 이미지 형식이 포함됩니다.
- getSupportedPreviewOutputResolutions()
- getSupportedCaptureOutputResolutions()
- getSupportedYuvAnalysisResolutions()
Camera2OutputConfigImpl 인스턴스 목록과 CameraCaptureSession 구성에 사용되는 세션 매개변수로 구성된 Camera2SessionConfigImpl 인스턴스를 반환해야 합니다. Camera2/X가 전달한 출력 표면에 올바른 카메라 이미지를 출력해야 합니다. 출력을 사용 설정하는 옵션은 다음과 같습니다.
- 카메라 HAL에서 처리: SurfaceOutputConfigImpl 구현을 사용하여 CameraCaptureSession에 출력 표면을 직접 추가할 수 있습니다. 이렇게 하면 카메라 파이프라인에 제공된 출력 표면이 구성되어 카메라 HAL에서 이미지를 처리할 수 있습니다.
- 중간 ImageReader 표면(RAW, YUV 등) 처리: ImageReaderOutputConfigImpl 인스턴스를 사용하여 중간 ImageReader 표면을 CameraCaptureSession에 추가합니다.
  
  중간 이미지를 처리하고 결과 이미지를 출력 표면에 써야 합니다.
참고: Camera2/X는 ImageReader 인스턴스를 만들고 관리합니다. ImageProcessorImpl 인스턴스를 설정하여 이미지를 가져올 수 있습니다.
- Camera2 표면 공유 사용: Camera2OutputConfigImpl 인스턴스를 다른 Camera2OutputConfigImpl 인스턴스의 getSurfaceSharingOutputConfigs() 메서드에 추가하여 다른 표면과의 표면 공유를 사용합니다. 표면 형식과 크기는 동일해야 합니다.
SurfaceOutputConfigImpl 및 ImageReaderOutputConfigImpl을 비롯하여 모든 Camera2OutputConfigImpl에는 고유 ID(getId())가 있어야 합니다. 이 ID는 타겟 표면을 지정하고 ImageReaderOutputConfigImpl에서 이미지를 가져오는 데 사용합니다.
onCaptureSessionStart 및 RequestProcessorImpl

CameraCaptureSession이 시작되고 카메라 프레임워크에서 onConfigured()를 호출하면 Camera2/X는 Camera2 요청 래퍼 RequestProcessImpl을 사용하여 SessionProcessorImpl.onCaptureSessionStart()를 호출합니다. Camera2/X는 RequestProcessImpl을 구현하므로 이를 통해 캡처 요청을 실행하고, ImageReaderOutputConfigImpl이 사용되는 경우 이미지를 검색할 수 있습니다.

RequestProcessImpl API는 요청을 실행하는 측면에서 Camera2 CameraCaptureSession API와 유사합니다. 차이점은 다음과 같습니다.
- 타겟 표면은 Camera2OutputConfigImpl 인스턴스의 ID로 지정됩니다.
- ImageReader의 이미지를 가져오는 기능입니다.
지정된 Camera2OutputConfigImpl ID로 RequestProcessorImpl.setImageProcessor()를 호출하여 이미지를 수신할 ImageProcessorImpl 인스턴스를 등록할 수 있습니다.

RequestProcessImpl 인스턴스는 Camera2/X가 SessionProcessorImpl.onCaptureSessionEnd()를 호출하면 무효화됩니다.
미리보기 시작 및 사진 찍기

고급 확장기 구현에서는 RequestProcessorImpl 인터페이스를 통해 캡처 요청을 보낼 수 있습니다. Camera2/X는 SessionProcessorImpl#startRepeating 및 SessionProcessorImpl#startCapture를 각각 호출하여 미리보기의 반복 요청이나 스틸 캡처 시퀀스를 시작하라고 알립니다. 이러한 미리보기 및 스틸 캡처 요청을 충족하려면 캡처 요청을 보내야 합니다.

또한 Camera2/X는 SessionProcessorImpl#setParameters를 통해 캡처 요청 매개변수를 설정합니다. 반복 및 단일 요청에서 모두 이러한 요청 매개변수(매개변수가 지원되는 경우)를 설정해야 합니다.

최소한 CaptureRequest.JPEG_ORIENTATION 및 CaptureRequest.JPEG_QUALITY를 지원해야 합니다. extensions-interface 1.3.0은 다음 메서드로 노출되는 요청 및 결과 키를 지원합니다.
- AdvancedExtenderImpl.getAvailableCaptureRequestKeys()
- AdvancedExtenderImpl.getAvailableCaptureResultKeys()
개발자가 getAvailableCaptureRequestKeys 목록에서 키를 설정할 때 매개변수를 사용 설정하고 캡처 결과에 getAvailableCaptureResultKeys 목록의 키가 포함되어 있는지 확인해야 합니다.
startTrigger

SessionProcessorImpl.startTrigger()를 호출하면 CaptureRequest.CONTROL_AF_TRIGGER 및 CaptureRequest.CONTROL_AE_PRECAPTURE_TRIGGER와 같은 트리거가 시작됩니다. AdvancedExtenderImpl.getAvailableCaptureRequestKeys()에서 광고되지 않은 캡처 요청 키는 모두 무시해도 됩니다.

startTrigger()는 extensions-interface 1.3.0부터 지원합니다. 이를 통해 앱에서 확장 프로그램을 사용하여 탭하여 초점 맞추기와 플래시를 구현할 수 있습니다.
정리

캡처 세션을 마치면 SessionProcessorImpl.onCaptureSessionEnd()가 CameraCaptureSession을 닫기 전에 호출됩니다. 캡처 세션이 닫힌 후에는 deInitSession()이 정리를 실행합니다.

미리보기, 스틸 캡처, 이미지 분석 지원

미리보기 및 스틸 캡처 사용 사례에 모두 확장 프로그램을 적용해야 합니다. 하지만 지연 시간이 너무 길어서 미리보기를 원활하게 표시할 수 없는 경우에는 스틸 캡처에만 확장 프로그램을 적용할 수 있습니다.

기본 확장기 유형의 경우 미리보기에 확장 프로그램을 사용 설정하는 것과 관계없이 지정된 확장 프로그램에 ImageCaptureExtenderImpl 및 PreviewExtenderImpl을 모두 구현해야 합니다. 앱은 또한 YUV 스트림을 사용하여 QR 코드나 텍스트 찾기와 같은 이미지 콘텐츠를 분석하는 때가 많습니다. 이 사용 사례를 더 효과적으로 지원하려면 미리보기, 스틸 캡처, CameraCaptureSession 구성을 위한 YUV_420_888 스트림의 스트림 조합을 지원해야 합니다. 즉, 프로세서를 구현한다면 YUV_420_888 스트림 3개의 스트림 조합을 지원해야 합니다.

고급 확장기의 경우 Camera2/X는 출력 표면 3개를 SessionProcessorImpl.initSession() 호출에 전달합니다. 이러한 출력 표면은 각각 미리보기, 스틸 캡처, 이미지 분석용입니다. 미리보기 및 스틸 캡처 출력 표면에 유효한 출력이 표시되는지 확인해야 합니다. 하지만 이미지 분석 출력 표면의 경우 null이 아닐 때만 작동하는지 확인합니다. 구현에서 이미지 분석 스트림을 지원할 수 없는 경우 AdvancedExtenderImpl.getSupportedYuvAnalysisResolutions()에서 빈 목록을 반환할 수 있습니다. 이렇게 하면 이미지 분석 출력 표면이 SessionProcessorImpl.initSession()에서 항상 null이 됩니다.

동영상 캡처 지원

현재 카메라 확장 프로그램 아키텍처는 미리보기 및 스틸 캡처 사용 사례만 지원합니다. 동영상을 녹화하기 위해 MediaCodec 또는 MediaRecorder 표면에서 확장 프로그램을 사용 설정하는 기능은 지원되지 않습니다. 하지만 앱에서 미리보기 출력을 기록할 수는 있습니다.

MediaCodec 및 MediaRecorder 표면 지원은 조사 중입니다.

확장 프로그램별 메타데이터

Android 14 및 이후 버전에서 확장 프로그램별 메타데이터를 사용하면 카메라 확장 프로그램 클라이언트가 확장 프로그램별 캡처 요청 설정 및 결과를 설정하고 수신할 수 있습니다. 특히 카메라 확장 프로그램 클라이언트는 EXTENSION_STRENGTH 캡처 요청 매개변수를 사용하여 확장 프로그램 강도를 제어하고 EXTENSION_CURRENT_TYPE 캡처 결과를 사용하여 사용 설정된 확장 프로그램 유형을 나타낼 수 있습니다.

캡처 결과

EXTENSION_STRENGTH 캡처 요청 매개변수는 확장 프로그램 후처리 효과의 강도를 제어합니다. 이 매개변수가 클라이언트에서 명시적으로 설정되지 않은 경우 해당 캡처 결과에는 기본 강도 값이 포함됩니다. 이 매개변수는 다음 확장 프로그램 유형에 다음과 같이 적용될 수 있습니다.

BOKEH: 흐린 정도를 제어합니다.
HDR 및 NIGHT: 통합된 이미지의 양과 최종 이미지의 밝기를 제어합니다.
FACE_RETOUCH: 미용 개선 및 피부 보정 정도를 제어합니다.

지원되는 EXTENSION_STRENGTH 매개변수 범위는 0~100이며 0은 확장 프로그램 처리나 간단한 패스 스루가 없음을 나타내고 100은 최대 확장 프로그램 강도의 처리 효과를 나타냅니다.

EXTENSION_STRENGTH 지원을 추가하려면 확장 프로그램 라이브러리 인터페이스 버전 1.3.0에서 도입된 공급업체별 매개변수 API를 사용하세요. 자세한 내용은 getAvailableCaptureRequestKeys()를 참고하세요.

캡처 결과

EXTENSION_CURRENT_TYPE 캡처 결과를 통해 확장 프로그램 구현에서 클라이언트에 활성 확장 프로그램 유형을 알릴 수 있습니다.

AUTO 유형을 사용하는 확장 프로그램은 장면 조건에 따라 확장 프로그램 유형(예: HDR, NIGHT) 간에 동적으로 전환하므로 카메라 확장 프로그램 앱은 EXTENSION_CURRENT_TYPE을 사용하여 AUTO 확장 프로그램에서 선택된 현재 확장 프로그램에 관한 정보를 표시할 수 있습니다.

실시간 스틸 캡처 지연 시간 추정치

Android 14 및 이후 버전의 경우 카메라 확장 프로그램 클라이언트는 getRealtimeStillCaptureLatency()를 사용하여 장면과 환경 조건에 따라 실시간 스틸 캡처 지연 시간 추정치를 쿼리할 수 있습니다. 이 메서드는 정적 getEstimatedCaptureLatencyRangeMillis() 메서드보다 더 정확한 추정치를 제공합니다. 지연 시간 추정치에 따라 앱은 확장 프로그램 처리를 건너뛰거나 사용자에게 장기 실행 작업을 알리도록 표시할 수 있습니다.

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

실시간 스틸 캡처 지연 시간 추정치를 지원하려면 다음을 구현하세요.

기본 확장 프로그램: ImageCaptureExtenderImpl.getRealtimeCaptureLatency()
고급 확장 프로그램: SessionProcessorImpl.getRealtimeCaptureLatency

캡처 처리 진행 상황 콜백

Android 14 및 이후 버전의 경우 카메라 확장 프로그램 클라이언트는 장기 실행 스틸 캡처 처리 작업의 진행 상황에 관한 콜백을 수신할 수 있습니다. 앱은 현재 진행 상황을 사용자에게 표시하여 전반적인 사용자 환경을 개선할 수 있습니다.

앱은 다음 코드를 사용하여 이 기능을 통합할 수 있습니다.

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

캡처 처리 진행 상황 콜백을 지원하려면 확장 프로그램 공급업체 구현에서 현재 진행 상황 값으로 다음 콜백을 호출해야 합니다.

기본 확장 프로그램: ProcessResultImpl.onCaptureProcessProgressed()
고급 확장 프로그램: CaptureCallback.onCaptureProcessProgressed()

postview 스틸 캡처

Android 14 및 이후 버전의 경우 카메라 확장 프로그램은 setPostviewOutputConfiguration을 사용하여 postview(미리보기 이미지)를 제공할 수 있습니다. 사용자 환경을 개선하려면 앱은 확장 프로그램의 처리 지연 시간이 늘어날 때 postview 이미지를 자리표시자로 표시하고 최종 이미지를 사용할 수 있을 때 이미지를 교체하면 됩니다. 앱은 다음 참조 코드를 사용하여 postview 캡처 요청을 구성하고 발행할 수 있습니다.

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

postview 스틸 캡처를 지원하려면 공급업체 구현에서 다음을 구현해야 합니다.

기본 확장 프로그램: CaptureProcessorImpl.onPostviewOutputSurface 및 CaptureProcessorImpl.processWithPostview
고급 확장 프로그램: SessionProcessorImpl.startCaptureWithPostview

SurfaceView 출력 지원

Android 14 및 이후 버전의 경우 카메라 확장 프로그램 클라이언트는 반복 요청의 미리보기 출력을 위해 SurfaceView 인스턴스를 등록하여 전력 및 성능에 최적화된 미리보기 렌더링 경로를 사용할 수 있습니다.

SurfaceView 출력을 지원하려면 공급업체 확장 프로그램 구현에서 미리보기를 SurfaceView 인스턴스에 스트리밍하고 출력할 수 있어야 합니다. 이 기능이 지원되는지 확인하려면 SurfaceViewExtensionPreviewTest.java CTS 모듈을 실행하세요.

공급업체별 세션 유형

이 기능을 사용하면 공급업체 확장 프로그램 구현에서 기본값 대신 내부 카메라 캡처 세션에 설정될 공급업체별 세션 유형을 선택할 수 있습니다.

이 기능은 프레임워크와 공급업체 스택 내에서 완전히 작동하며 클라이언트/공개 표시 API에 영향을 미치지 않습니다.

공급업체별 세션 유형을 선택하려면 확장 프로그램 라이브러리를 위해 다음을 구현하세요. * 기본 확장 프로그램의 경우 ExtenderStateListener.onSessionType() * 고급 확장 프로그램의 경우 Camera2SessionConfigImpl.getSessionType()

확장 프로그램 인터페이스 버전 기록

다음 표는 카메라 확장 프로그램 인터페이스 버전 기록을 보여줍니다. 최신 버전으로 공급업체 라이브러리를 항상 구현해야 합니다.

버전	추가된 기능
1.0.0	버전 확인 `ExtensionVersionImpl` 기본 확장기 `PreviewExtenderImpl` `ImageCaptureExtenderImpl` `Processor` `PreviewImageProcessorImpl` `CaptureProcessorImpl` `RequestUpdateProcessorImpl`
1.1.0	라이브러리 초기화 `InitializerImpl` 지원되는 해상도 노출 `PreviewExtenderImpl.getSupportedResolutions` `ImageCaptureExtenderImpl.getSupportedResolutions`
1.2.0	AdvancedExtender `AdvancedExtenderImpl` `SessionProcessorImpl` 예상 캡처 지연 시간 가져오기 `ImageCaptureExtenderImpl.getEstimatedCaptureLatencyRange`
1.3.0	지원되는 캡처 요청 키/결과 키 노출 `ImageCaptureExtenderImpl.getAvailableCaptureRequestKeys` 및 `getAvailableCaptureResultKeys` `AdvancedExtenderImpl.getAvailableCaptureRequestKeys` 및 `getAvailableCaptureResultKeys` `PreviewImageProcessorImpl` 및 `CaptureProcessorImpl`에서 `ProcessResultImpl`을 사용하는 새 `process()` 호출 트리거 유형 요청 지원 `AdvancedExtenderImpl.startTrigger`
1.4.0	확장 프로그램별 메타데이터 동적 스틸 캡처 지연 시간 추정치 캡처 처리 진행 상황 콜백 postview 스틸 캡처 `SurfaceView` 출력 지원 공급업체별 세션 유형

참조 구현

다음 참조 OEM 공급업체 라이브러리 구현은 frameworks/ex에서 이용할 수 있습니다.

advancedSample: 고급 확장기의 기본 구현입니다.
sample: 기본 확장기의 기본 구현입니다.
service_based_sample: Service에서 카메라 확장 프로그램을 호스팅하는 방법을 보여주는 구현입니다. 이 구현에는 다음 구성요소가 포함됩니다.
- oem_library: Extensions-Interface를 구현하는 Camera2 및 CameraX Extensions API용 카메라 확장 프로그램 OEM 라이브러리입니다. 이는 Extensions-Interface에서 서비스로 호출을 전달하는 패스 스루의 역할을 합니다. 또한 이 라이브러리는 서비스와 통신할 수 있는 AIDL 파일과 래퍼 클래스를 제공합니다.
  
  고급 확장기는 기본적으로 사용 설정되어 있습니다. 기본 확장기를 사용 설정하려면 false를 반환하도록 ExtensionsVersionImpl#isAdvancedExtenderImplemented를 변경합니다.
- extensions_service: 확장 프로그램 서비스의 샘플 구현입니다. 여기에서 구현을 추가하세요. 서비스에 구현할 인터페이스는 Extensions-Interface와 유사합니다. 예를 들어 IAdvancedExtenderImpl.Stub를 구현하면 AdvancedExtenderImpl과 동일한 작업이 실행됩니다. Image 및 TotalCaptureResult를 분할 가능하게 만들려면 ImageWrapper와 TotalCaptureResultWrapper가 필요합니다.

기기에서 공급업체 라이브러리 설정

OEM 공급업체 라이브러리는 앱에 빌드되지 않습니다. 런타임에 Camera2/X에 의해 기기에서 로드됩니다. CameraX에서 <uses-library> 태그는 camera-extensions 라이브러리의 AndroidManifest.xml 파일에 정의된 androidx.camera.extensions.impl 라이브러리가 CameraX의 종속 항목이며 런타임에 로드되어야 한다고 선언합니다. Camera2에서 프레임워크는 <uses-library>가 런타임에 동일한 androidx.camera.extensions.impl 라이브러리를 로드한다고 선언하는 확장 프로그램 서비스를 로드합니다.

이렇게 하면 확장 프로그램을 사용하는 서드 파티 앱이 OEM 공급업체 라이브러리를 자동으로 로드할 수 있습니다. OEM 라이브러리가 선택사항으로 표시되어 있으므로 기기에 라이브러리가 없는 기기에서 앱을 실행할 수 있습니다. Camera2/X는 앱이 검색할 수 있도록 기기 제조업체에서 기기에 OEM 라이브러리를 배치한 경우 앱이 카메라 확장 프로그램을 사용하려고 할 때 이 동작을 자동으로 처리합니다.

기기에서 OEM 라이브러리를 설정하려면 다음 단계를 따르세요.

<uses-library> 태그에 필요한 권한 파일을 다음 형식을 사용하여 추가합니다. /etc/permissions/ANY_FILENAME.xml. 예: /etc/permissions/camera_extensions.xml. 이 디렉터리의 파일은 <uses-library>라는 라이브러리를 기기의 실제 파일 경로에 매핑합니다.
아래 예시를 사용하여 파일에 필요한 정보를 추가합니다.
- name은 CameraX가 검색하는 라이브러리이므로 androidx.camera.extensions.impl이어야 합니다.
- file은 확장 프로그램 구현을 포함하는 파일의 절대 경로입니다(예: /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>
```

Android 12 이상에서는 CameraX 확장 프로그램을 지원하는 기기에 ro.camerax.extensions.enabled 속성이 true로 설정되어 있어야 합니다. 이렇게 하면 기기에서 확장 프로그램을 지원하는지 쿼리할 수 있습니다. 다음 줄을 기기 makefile에 추가하면 됩니다.

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

유효성 검사

개발 단계에서 OEM 공급업체 라이브러리의 구현을 테스트하려면 다양한 공급업체 확장 프로그램을 통해 실행되는 androidx-main/camera/integration-tests/extensionstestapp/의 예시 앱을 사용합니다.

구현을 완료한 후에는 Camera 확장 프로그램 유효성 검사 도구를 사용하여 공급업체 라이브러리가 올바르게 구현되었는지 확인하는 자동 및 수동 테스트를 실행합니다.

확장 장면 모드와 카메라 확장 프로그램 비교

빛망울 효과 확장 프로그램의 경우 카메라 확장 프로그램을 사용하여 노출하는 것 외에도 CONTROL_EXTENDED_SCENE_MODE 키를 통해 사용 설정된 확장 장면 모드를 사용하여 확장 프로그램을 노출할 수 있습니다. 구현에 관한 자세한 내용은 카메라 빛망울 효과를 참고하세요.

확장 장면 모드는 camera2 앱의 카메라 확장 프로그램에 비해 제한사항이 적습니다. 예를 들어, 유연한 스트림 조합과 캡처 요청 매개변수를 지원하는 일반 CameraCaptureSession 인스턴스에서 확장 장면 모드를 사용 설정할 수 있습니다. 반면 카메라 확장 프로그램은 고정된 스트림 유형 집합만 지원하며 캡처 요청 매개변수 지원은 제한적입니다.

확장 장면 모드의 단점은 카메라 HAL에서만 구현할 수 있다는 것입니다. 즉, 앱 개발자가 사용할 수 있는 모든 직교 컨트롤에서 작동하는지 확인해야 합니다.

앱은 특정 API를 사용하여 빛망울 효과를 사용 설정할 수 있으므로 확장 장면 모드와 카메라 확장 프로그램을 모두 사용하여 빛망울 효과를 노출하는 것이 좋습니다. 확장 장면 모드는 앱이 빛망울 효과 확장 프로그램을 사용할 수 있는 가장 유연한 방법이므로 이 방법을 먼저 사용하는 것이 좋습니다. 그런 다음 확장 장면 모드에 따라 카메라 확장 프로그램 인터페이스를 구현할 수 있습니다. 예를 들어, 이미지를 처리하려면 앱 레이어에서 실행되는 포스트 프로세서가 필요하므로 카메라 HAL에서 빛망울 효과를 구현하기 어려운 경우 카메라 확장 프로그램 인터페이스를 사용하여 빛망울 효과 확장 프로그램을 구현하는 것이 좋습니다.

자주 묻는 질문(FAQ)

API 수준에 제한사항이 있나요?

예. 이는 OEM 공급업체 라이브러리 구현에 필요한 Android API 기능 집합에 따라 다릅니다. 예를 들어 ExtenderStateListener.onPresetSession()은 SessionConfiguration.setSessionParameters() 호출을 사용하여 태그 기준 집합을 설정합니다. 이 호출은 API 수준 28 이상에서만 사용할 수 있습니다. 특정 인터페이스 메서드에 관한 자세한 내용은 API 참조 문서를 참고하세요.