Google은 흑인 공동체를 위한 인종 간 평등을 진전시키기 위해 노력하고 있습니다. Google에서 어떤 노력을 하고 있는지 확인하세요.

CameraX 공급업체 확장 프로그램

기기 제조업체는 CameraX OEM 공급업체 라이브러리를 구현하여 CameraX 확장 프로그램 인터페이스를 통해 타사 개발자에게 기기별 효과를 노출할 수 있습니다. CameraX는 런타임에 로드되는 공급업체 구현 클래스의 CameraX 확장 프로그램 인터페이스를 정의합니다. 이 페이지에서는 OEM 공급업체 라이브러리를 구현하고 기기에서 사용 설정하는 방법을 설명합니다.

공급업체 라이브러리를 구현하기 전에 CameraX Jetpack 지원 라이브러리의 작동 방식을 이해해야 합니다. CameraX에 관한 자세한 내용은 CameraX 개요를 참고하세요. 공급업체 확장 프로그램에 관한 자세한 내용은 공급업체 확장 프로그램을 참고하세요.

아키텍처

아키텍처

그림 1. 공급업체 확장 프로그램 아키텍처 다이어그램

이 다이어그램은 CameraX 공급업체 확장 프로그램의 아키텍처를 설명합니다. 서드 파티 앱은 CameraX 확장 프로그램 라이브러리(camera-extensions)에서 빌드되며 카메라 확장 프로그램 공개 API(camera-extensions API)를 사용할 수 있습니다. camera-extensions API는 CameraX가 정의하고 camera-extensions 라이브러리의 새 버전이 출시되면 업데이트됩니다. camera-extensions 공개 API와 camera-extensions 라이브러리의 버전 관리는 동일합니다.

서드 파티 앱은 Android 12부터 Camera2 확장 프로그램 API에서 빌드될 수 있습니다. 지원되는 확장 프로그램 모드를 사용 설정하려면 CameraDevice#createExtensionSession()을 사용하여 앱에서 카메라 캡처 세션(CameraExtensionSession)을 만들면 됩니다.

CameraX가 정의한 확장 프로그램 인터페이스(extensions-interface)에서는 CameraX camera-extensions 라이브러리와 Camera2 확장 프로그램 API 모두가 OEM 공급업체 라이브러리(camera-extensions-stub)와 통신할 수 있습니다. 따라서 CameraX OEM 공급업체 라이브러리를 구현하는 기기는 Camera2 확장 프로그램 API도 지원합니다.

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

이러한 구현 안내에서는 빛망울 효과(세로 모드) 공급업체 확장 프로그램을 예시로 사용하지만 HDR, 얼굴 보정, 야간 모드 확장 프로그램과 같은 다른 확장 프로그램에도 이 내용을 적용할 수 있습니다. 이렇게 하려면 빛망울 효과 확장 프로그램에 사용한 코드를 복사하여 붙여넣고 확장 프로그램의 이름을 원하는 확장 프로그램 이름으로 바꿉니다(예: BokehImageCaptureExtenderImplHdrImageCaptureExtenderImpl로 대체).

모든 효과의 구현을 제공할 필요는 없습니다. 공급업체 구현이 없는 효과는 CameraX 구현으로 기본 설정됩니다. 효과를 사용할 수 없는 경우 기본 구현은 효과를 사용 설정하지 않으며 효과를 사용할 수 없다고 타사 개발자에게 보고합니다.

버전 확인

CameraX는 OEM 라이브러리를 로드할 때 확장 프로그램 인터페이스 버전과 호환되는 버전(이 문서에서는 extension-version이라고 함)이 OEM 라이브러리에 포함되어 있는지 확인합니다. 버전 호환성을 확인하기 위해 CameraX는 주 버전과 부 버전(예: 1.0)만을 확인하며, 인터페이스 변경이 아닌 버그 수정에만 사용되는 패치 버전은 확인하지 않습니다. 이 문서에서는 특정 API의 필수 extension-version을 설명합니다. 지정된 extension-version이 없는 API는 extension-version 1.0과 호환됩니다.

버전을 확인하기 위해 CameraX는 ExtensionVersionImpl 인터페이스를 쿼리합니다. 그런 다음 CameraX는 OEM 라이브러리에서 보고된 버전을 사용하여 호출 가능한 기능을 확인합니다.

초기화

CameraX는 OEM 라이브러리에서 구현한 확장 프로그램 인터페이스 버전을 확인했을 때 초기화 프로세스를 시작합니다. InitializerImpl.init 메서드는 앱이 확장 프로그램을 사용하려고 한다는 것을 OEM 라이브러리에 신호로 보냅니다. OnExtensionsInitializedCallback이 성공 상태 코드와 함께 호출될 때까지 OEM 라이브러리의 다른 호출은 실행되지 않습니다(버전 확인 제외).

이 메서드는 extension-version 버전 1.1에서 구현되어야 합니다. 자세한 내용은 InitializerImpl의 소스를 참고하세요.

ExtendStateListener 인터페이스

CameraX는 OEM 라이브러리가 관련된 SessionParametersCaptureRequest 값을 설정할 수 있도록 파이프라인의 여러 위치에 후크를 제공합니다. OEM 라이브러리가 지정된 시간에 이러한 값을 설정하도록 허용하려면 ExtenderStateListener 인터페이스를 구현합니다. 미리보기, 이미지 캡처, 빛망울 효과 또는 HDR 확장기인지 여부에 관계없이 이 인터페이스는 모든 확장기의 일부로 구현되어야 합니다.

이미지 캡처

이미지 캡처의 확장 프로그램을 지원하려면 상응하는 ImageCaptureExtender 인터페이스를 구현합니다(예: BokehImageCaptureExtenderImpl 또는 HdrImageCaptureExtenderImpl).

ImageCaptureExtenderImpl에는 이미지 캡처와 관련된 확장 프로그램에 필요한 인터페이스가 포함됩니다.

앱 레이어에서 사후 처리를 완료하려면 CaptureProcessorImpl 인터페이스를 구현해야 합니다. 확장 프로그램 인터페이스 버전 1.1에서는 YUV_420_888 입력 이미지 형식만 지원되어야 합니다. 카메라 HAL에서 처리가 이루어지는 경우 CaptureProcessor 인터페이스가 필요하지 않습니다.

다음 다이어그램은 이미지 캡처 프로세스 흐름을 보여 줍니다.

이미지 캡처 프로세스 흐름

그림 2. 이미지 캡처 흐름 다이어그램

예: BokehImageCaptureExtenderImpl

이미지 캡처용 빛망울 효과 확장 프로그램을 지원하려면 androidx.camera.extensions.impl 패키지에서 BokehImageCaptureExtenderImpl 클래스를 구현합니다.

미리보기

미리보기의 확장 프로그램을 지원하려면 상응하는 PreviewExtender 인터페이스(예: BokehPreviewExtenderImpl 또는 HdrPreviewExtenderImpl)를 구현합니다. PreviewExtender 인터페이스에는 미리보기 관련 확장 프로그램에 필요한 인터페이스가 포함됩니다.

자세한 내용은 PreviewExtenderImpl의 소스를 참고하세요.

미리보기 확장 프로그램의 이미지 처리는 카메라 HAL 또는 앱 레이어에서 이루어질 수 있습니다. 이는 PreviewExtenderImpl에서 반환하는 ProcessorType 값에 따라 결정됩니다.

PROCESSOR_TYPE_REQUEST_UPDATE_ONLY 유형이 반환되면 CaptureRequest 키를 통해 HAL에서 처리가 이루어집니다. PROCESSOR_TYPE_IMAGE_PROCESSOR 유형이 반환되면 PreviewImageProcessorImpl 인터페이스를 통해 앱 레이어에서 처리가 이루어집니다. 이 인터페이스는 ImageTotalCaptureResult 쌍에서 작동합니다. 확장 프로그램 인터페이스 버전 1.1에서는 YUV_420_888 입력 이미지 형식만 지원되어야 합니다.

다음 다이어그램은 미리보기 공급업체 확장 프로그램의 프로세스 흐름을 보여 줍니다.

미리보기 흐름 다이어그램

그림 3. 미리보기 흐름 다이어그램

예: BokehPreviewExtenderImpl

미리보기용 빛망울 효과를 지원하려면 androidx.camera.extensions.impl 패키지에서 BokehPreviewExtenderImpl 클래스를 구현합니다.

참조 구현

OEM 공급업체 라이브러리의 참조 구현은 camera-testlib-extensions를 참고하세요. 이 구현은 실제로 효과를 구현하지 않고 패스 스루를 실행합니다.

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

OEM 공급업체 라이브러리는 앱에 빌드되지 않으며 대신 런타임에 CameraX에 의해 기기에서 로드됩니다. <uses-library> 태그는 AndroidManifest.xml 파일에 정의된 androidx.camera.extensions.impl 라이브러리가 CameraX의 종속 항목이며 런타임에 로드되어야 한다고 선언합니다. 이 태그를 사용하면 공급업체 확장 프로그램을 사용하는 타사 앱에서 자동으로 OEM 공급업체 라이브러리를 로드할 수 있습니다. OEM 라이브러리가 선택사항으로 표시되어 있으므로 기기에 라이브러리가 없는 기기에서 앱을 실행할 수 있습니다.

CameraX는 앱이 검색할 수 있도록 기기 제조업체에서 기기에 OEM 라이브러리를 배치한 경우 앱이 공급업체 확장 프로그램을 사용하려고 할 때 이 동작을 자동으로 처리합니다.

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

  1. <uses-library> 태그에 필요한 권한 파일을 다음 형식을 사용하여 추가합니다. /etc/permissions/ANY_FILENAME.xml. 예: /etc/permissions/camera_extensions.xml. 이 디렉터리의 파일은 <uses-library>라는 라이브러리를 기기의 실제 파일 경로에 매핑합니다.
  2. 아래 예시를 사용하여 파일에 필요한 정보를 추가합니다.

    • 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/의 예시 앱을 사용합니다.

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

자주 묻는 질문(FAQ)

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

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