ストリーム構成

Android は、カメラ クライアントが特定のユースケースに最適なカメラ ストリームを選択し、特定のストリームの組み合わせがカメラデバイスによってサポートされるようにする機能を搭載しています。ストリーム構成はカメラデバイス内で構成された単一のカメラ ストリームのことを指し、ストリームの組み合わせはカメラデバイス内で構成された 1 つ以上のストリームのセットを指します。これらの機能の詳細については、推奨されるストリーム構成と機能の組み合わせをクエリするための API をご覧ください。

リファレンス実装

推奨されるストリーム構成とストリームの組み合わせをクエリするための API に関して、ベンダー向けリファレンス実装が用意されています。この実装は、QCamera3HWI.cpp にあります。

カメラベンダーは、特定のユースケースに対する推奨ストリーム構成をカメラ クライアントにアドバタイズできます。StreamConfigurationMap のサブセットであるこの推奨ストリーム構成は、カメラ クライアントが最適な構成を選択する際に有用です。

StreamConfigurationMap は、完全なストリーム構成情報をカメラ クライアントに提供しますが、どのストリームを選択するかで効率、電力、パフォーマンスにどう影響するかといった情報は提供されません。カメラ クライアントは、あらゆるストリーム構成から自由に選択することが可能ですが、多くの場合、クライアントが使用するカメラ構成が最適ではない、アプリによる検索処理に時間がかかる、といった結果につながります。

たとえば、処理済みの YUV 形式のいくつかは必須であり、サポートされている必要がありますが、形式によってはカメラデバイスでネイティブ サポートされていない場合もあります。このため、形式変換の処理パスが追加され、効率が低下してしまいます。サイズと対応するアスペクト比でも同じような影響が発生する可能性があり、電力とパフォーマンスの点で特定のディメンションが有利となる場合もあります。

推奨ストリーム構成マップは、StreamConfigurationMap ほど網羅的である必要はありません。提案するストリーム構成マップは、実装セクションの要件を満たす必要があります。また、StreamConfigurationMap にある使用可能な形式、サイズ、またはその他の値を含めることができます。StreamConfigurationMap にない隠しフォーマット、サイズ、その他の値は、推奨ストリーム構成マップに含めることはできません。

推奨ストリーム構成によっては、すべてのテストは変更されず緩和もされません。

カメラ実装によって提供される推奨ストリーム構成はオプションであり、カメラ クライアントは無視することもできます。

実装

この機能を実装する手順は次のとおりです。

メタデータ エントリ

この機能を有効にするには、Camera HAL が次の静的メタデータ エントリを入力する必要があります。

  • android.scaler.availableRecommendedStreamConfigurations: 特定のユースケースで使用するストリーム構成の推奨サブセット宣言では、提案するユースケースを [1 << PREVIEW | 1 << RECORD..] の形式で示すビットマップが使用されます。ユースケースでは、標準的な（形式、幅、高さ、入力）タプルを拡張して、エントリを追加できます。存在しない公開ユースケースまたは [PUBLIC_END, VENDOR_START] 範囲内のその他のビットセットは禁止されています。

    この情報は、availableRecommendedStreamConfigurations メタデータタグに保存されています。

    次の例は、4K と 1080p のみをサポートするカメラデバイスの推奨ストリーム構成の配列を示しています。録画ではどちらの解像度も推奨されますが、プレビューでは 1080p のみが提案されます。

    [3840, 2160, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED,
ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT,
(1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT),
1920, 1080, HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED,
ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS_OUTPUT,
(1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_PREVIEW |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_RECORD |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_SNAPSHOT |
1 << ANDROID_SCALER_AVAILABLE_RECOMMENDED_STREAM_CONFIGURATIONS_VIDEO_SNAPSHOT)]

  • android.depth.availableRecommendedDepthStreamConfigurations（デバイスでサポートされている場合にのみ使用可能）: このカメラデバイスに提案される推奨深度データ空間ストリーム構成。上記のメタデータ エントリと同様に、ユースケース ビットマップを追加して提案するユースケースを示します。

    この情報は、availableRecommendedInputOutputFormatsMap メタデータタグに保存されています。

  • android.scaler.availableRecommendedInputOutputFormatsMap（デバイスでサポートされている場合にのみ使用可能）: 入力ストリームから対応する出力形式への、このカメラデバイスに提案される推奨画像形式のマッピング。

    この情報は、availableRecommendedDepthStreamConfigurations メタデータタグに保存されています。

カメラ クライアントは RecommendedStreamConfigurationMap API を通じてこの情報を取得できます。

必須ユースケース

次のユースケースに対して推奨ストリーム構成を提供する必要があります。推奨ストリーム構成はユースケースの要件を満たす必要があります。

ユースケース 要件
PREVIEW プレビューには、YUV_420_888 と IMPLEMENTATION_DEFINED のような出力形式を持つ非ストール形式の処理済みストリーム構成以外は含めることができません。
RECORD 動画の録画には、アドバタイズされたサポート対象のメディア プロファイルと一致するストリーム構成を IMPLEMENTATION_DEFINED 形式で含める必要があります。
VIDEO_SNAPSHOT 動画スナップ ショットには、少なくとも最高の RECORD 解像度と同じ解像度を持ち、BLOB + DATASPACE_JFIF 形式/データベースの組み合わせ（JPEG）のみを持つストリーム構成を含める必要があります。この構成を使用することで、プレビューでの不具合を防ぎ、30 fps でプレビューを実行できるようになります。
SNAPSHOT スナップショット ストリーム構成には、BLOB + DATASPACE_JFIF 形式/データベースの組み合わせ（JPEG）を持つ android.sensor.info.activeArraySize に近いサイズの構成を 1 つ以上含める必要があります。アスペクト比、アライメント、その他のベンダー固有の制約を考慮して、提案する最大サイズ領域はセンサー配列サイズ領域の 97% 以上にする必要があります。
ZSL（サポートされている場合） カメラデバイスでサポートされている場合、推奨入力ストリーム構成は他の処理済みまたはストール出力形式と一緒の場合にのみアドバタイズする必要があります。
RAW（サポートされている場合） カメラデバイスでサポートされている場合、推奨 Raw ストリーム構成は RAW ベース出力形式のみを含める必要があります。

その他のユースケース

各実装に固有のユースケースに応じて、推奨構成ストリームを追加できます。

検証

推奨構成ストリームの実装をテストするには、次の CTS および VTS テストを実行します。

機能の組み合わせをクエリするための API

Android 15 以降の Android プラットフォームには、機能の組み合わせをクエリするための API が用意されています。この API を使用すると、指定した機能の組み合わせがデバイスでサポートされているかどうかをカメラ クライアントからクエリできます。この API が必要になるのは、Camera2 API でさまざまな機能（4k、60fps、HDR 動画、UltraHDR、ウルトラワイド ズーム、手ぶれ補正など）が直交制御としてモデル化されているためです。

要件

この API をサポートして機能の組み合わせをクエリできるようにするには、カメラ HAL に ICameraDevice インターフェースのバージョン 3 を実装する必要があります。詳細については、実装をご覧ください。

この API をサポートする場合は、プレビューの手ぶれ補正が他の機能と直交している必要があります。つまり、プレビューの手ぶれ補正をサポートするカメラデバイスでは、プレビューの手ぶれ補正がオンでもオフでも、特定の組み合わせの isStreamCombinationWithSettingsSupported の値を同じにしなければならないということです。これにより、機能の組み合わせをクエリする際の検索空間を小さくすることができます。

また、メディア パフォーマンス クラス 15 の場合は、プライマリ背面カメラが 1080p および 720p のプレビューと最大サイズの JPEG で 10 ビット HLG10 プレビューによるプレビューの手ぶれ補正をサポートしている必要があります。これらの要件について詳しくは、CDD の 2.2.7.2. カメラをご覧ください。

実装

機能の組み合わせをクエリするための API をサポートするには、ICameraDevice のバージョン 3 に機能の組み合わせのクエリに使用する以下の API を実装します。

  • constructDefaultRequestSettings: 指定された CaptureRequest タイプのデフォルト設定を作成します。HAL では、ICameraDeviceSession::constructDefaultRequestSettings の実装を使用できます。

  • isStreamCombinationWithSettingsSupported: セッション パラメータと追加の CaptureRequest キーで指定したカメラ ストリームの組み合わせが、デバイスでサポートされるかどうかをチェックします。機能の組み合わせがサポートされる場合は true、サポートされない場合は false を返す必要があります。HAL では、isStreamCombinationSupported の実装と、sessionParams で CaptureRequest の設定が渡されたかどうかをチェックするための追加サポートを使用できます。

  • getSessionCharacteristics: サポートされるストリームの組み合わせをセッション パラメータとして取り、セッション固有の特性を返します。

  • INFO_SESSION_CONFIGURATION_QUERY_VERSION: よく使用するすべてのセッション構成の一覧を表示します。これらの構成は、コンプライアンス テストによって検証されます。

ICameraDevice インターフェースのバージョンがバージョン 3 より低い場合は、HAL に isStreamCombinationSupported メソッドを実装する必要があります。

API による機能の組み合わせのクエリについて詳しくは、system/media/camera/docs/metadata_definitions.xml の sessionConfigurationQueryVersion に関するドキュメントをご覧ください。

この機能のリファレンス実装については、hardware/google/camera/devices/EmulatedCamera/hwl/ をご覧ください。

公開 API

アプリでは、以下の公開 API を使用して、デバイスでサポートされる機能の組み合わせをクエリできます。

  • CameraDevice.CameraDeviceSetup: CameraDevice インスタンスなしで機能の組み合わせをクエリするのに使用できる CameraDevice の限定表現です。

  • getCameraDeviceSetup: isCameraDeviceSetupSupported で true が返された場合に、指定したカメラ ID の CameraDeviceSetup オブジェクトを取得します。

  • INFO_SESSION_CONFIGURATION_QUERY_VERSION: この値が VANILLA_ICE_CREAM 以上であれば、機能の組み合わせのクエリがサポートされます。

  • OutputConfiguration: カメラ出力を記述するクラスです。低レイテンシーの機能の組み合わせをクエリすることを目的として遅延サーフェスを格納できます。

  • SessionConfiguration: ストリームの組み合わせやセッション パラメータを含めたセッション構成を記述するユーティリティ クラスです。機能の組み合わせのクエリに使用できます。

検証

この機能の実装を検証するには、以下に示す VTS、CTS、カメラ ITS（CTS 検証ツール）テストを使用します。

VTS

CTS

カメラ ITS