Google は、黒人コミュニティに対する人種平等の促進に取り組んでいます。取り組みを見る

CameraX ベンダー拡張機能

デバイス メーカーは、CameraX OEM ベンダー ライブラリを実装することで、CameraX 拡張機能インターフェースを介してデバイス固有の効果をサードパーティ デベロッパーに公開できます。CameraX は、ランタイム時に読み込まれるベンダー実装クラス用の CameraX 拡張機能インターフェースを定義します。このページでは、OEM ベンダー ライブラリを実装してデバイスで有効にする方法について説明します。

ベンダー ライブラリを実装するには、CameraX Jetpack サポート ライブラリの仕組みを理解している必要があります。CameraX の詳細については、CameraX の概要をご覧ください。ベンダー拡張機能の詳細については、ベンダー拡張機能をご覧ください。

アーキテクチャ

アーキテクチャ

図 1:ベンダー拡張機能のアーキテクチャ図

この図は、CameraX ベンダー拡張機能のアーキテクチャを示しています。サードパーティ アプリは CameraX 拡張機能ライブラリ(camera-extensions)に対してビルドすることができ、カメラ拡張機能公開 APIcamera-extensions API)を使用します。camera-extensions API は CameraX によって定義され、camera-extensions ライブラリの新しいバージョンがリリースされると更新されます。camera-extensions 公開 API と camera-extensions ライブラリのバージョニングは同じです。

Android 12 以降、サードパーティ アプリは Camera2 extensions API に対してビルドできます。サポートされている拡張モードを有効にするために、CameraDevice#createExtensionSession() を使用してカメラのキャプチャ セッション(CameraExtensionSession)をアプリで作成できます。

CameraX によって定義される拡張機能インターフェース(extensions-interface)により、CameraX camera-extensions ライブラリと Camera2 extensions API の両方が OEM ベンダー ライブラリ(camera-extensions-stub)と通信できます。 つまり、CameraX OEM ベンダー ライブラリを実装するデバイスは、Camera2 extensions 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 でソースをご覧ください。

ExtenderStateListener インターフェース

CameraX はパイプライン内のさまざまな場所へのフックを提供し、関連する SessionParameters および CaptureRequest の値を OEM ライブラリが設定できるようにします。OEM ライブラリがこれらの値を指定の回数に設定できるようにするには、ExtenderStateListener インターフェースを実装します。このインターフェースは任意のエクステンダー(プレビュー、画像キャプチャ、ボケ表現、HDR エクステンダーなど)の一部として実装する必要があります。

画像キャプチャ

画像キャプチャの拡張機能をサポートするには、対応する ImageCaptureExtender インターフェース(BokehImageCaptureExtenderImpl または HdrImageCaptureExtenderImpl など)を実装します。

ImageCaptureExtenderImpl には、画像キャプチャに関連する拡張機能に必要なインターフェースが含まれています。

後処理をアプリレイヤで行うためには、CaptureProcessorImpl インターフェースを実装する必要があります。拡張機能インターフェースのバージョンが 1.1 の場合、YUV_420_888 入力画像形式のみサポートが必要です。カメラ HAL で処理を実行する場合は、CaptureProcessor インターフェースは必要ありません。

次の図は、画像キャプチャ プロセスのフローを示しています。

画像キャプチャ プロセスのフロー

図 2.画像キャプチャのフロー図

例: BokehImageCaptureExtendererImpl

画像キャプチャのボケ表現拡張機能をサポートするには、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. プレビューのフロー図

例: BokehPreviewExtendererImpl

プレビューでボケ表現をサポートするには、androidx.camera.extensions.impl パッケージに BokehPreviewExtenderImpl クラスを実装します。

リファレンス実装

リファレンス OEM ベンダー ライブラリの実装については、camera-testlib-extensions をご覧ください。この実装は、実際に効果を実装することなくパススルーを実行します。

ベンダー ライブラリをデバイスに設定する

OEM のベンダー ライブラリはアプリに組み込まれるのではなく、ランタイム時に CameraX によってデバイスから読み込まれます。<uses-library> タグは、AndroidManifest.xml ファイルで定義されている androidx.camera.extensions.impl ライブラリが CameraX の依存関係であり実行時に読み込まれる必要があることを宣言します。これにより、ベンダー拡張機能を使用するサードパーティ アプリは OEM ベンダー ライブラリの読み込みを自動的に試行できます。OEM ライブラリはオプションとしてマークされているため、デバイス上にライブラリを持たないデバイスでもアプリを実行できます。

デバイス メーカーがデバイスに OEM ライブラリを配置してアプリで検出できるようにしている場合、CameraX は、アプリがベンダー拡張機能を使用しようとしたときに、この動作を自動的に処理します。

デバイスに OEM ライブラリを設定する手順は次のとおりです。

  1. /etc/permissions/ANY_FILENAME.xml の形式を使用して、<uses-library> タグで必要となる権限ファイルを追加します。たとえば /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 に設定する必要があります。これにより、デバイスが拡張機能をサポートしているかどうかを照会できます。これを行うには、デバイスの make ファイルに次の行を追加します。

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

検証

開発段階の際に OEM ベンダー ライブラリの実装をテストするには、androidx-main/camera/integration-tests/extensionstestapp/ のサンプルアプリを使用します。このサンプルアプリでさまざまなベンダー拡張機能が実行されます。

実装を完了したら、CameraX ベンダー拡張機能検証ツールを使用して、自動テストや手動テストを実行し、ベンダー ライブラリが正しく実装されていることを確認します。

よくある質問(FAQ)

API レベルに制限はありますか?

はい。API レベルは、OEM ベンダー ライブラリの実装に必要な Android API 機能セットによって異なります。たとえば、ExtenderStateListener.onPresetSession() では、SessionConfiguration.setSessionParameters() 呼び出しを使用してタグのベースライン セットを設定します。この呼び出しは API レベル 28 以上でのみ使用できます。特定のインターフェース メソッドの詳細については、API リファレンス ドキュメントをご覧ください。