串流設定

Android 提供多項功能，讓相機用戶端可為特定用途選擇最佳相機串流，並確保相機裝置支援特定串流組合。「串流設定」是指在相機裝置中設定的單一相機串流，「串流組合」則是指在相機裝置中設定的一或多組串流。如要進一步瞭解這些功能，請參閱建議的串流設定和用於查詢功能組合的 API。

參考實作

供應商端參考實作項目包含建議的設定串流，以及用於查詢串流組合功能的 API。您可以在 QCamera3HWI.cpp 中找到這項實作

相機供應商可以向相機用戶宣傳特定用途的建議串流設定。這些建議的串流設定是 StreamConfigurationMap 的子集，可協助攝影機用戶端選擇最佳設定。

雖然 StreamConfigurationMap 會向相機用戶端提供完整的串流設定資訊，但不會提供任何資訊，說明選擇某個串流會對效率、電力或效能造成什麼影響。相機用戶端可以從所有可能的串流設定中自由選擇，但在許多情況下，這會導致用戶端使用次佳的相機設定，而應用程式則進行耗時的全面搜尋。

舉例來說，雖然系統需要並支援某些經過處理的 YUV 格式，但相機裝置可能不支援這些格式。這會導致格式轉換作業需要額外處理，並降低效率。大小和對應的顯示比例也會有類似的影響，因此在電力和效能方面，特定尺寸會是較佳的選擇。

與 StreamConfigurationMap 相比，建議的串流設定對應項目不必完整。建議的設定對應項目必須遵循「實作」一節中的規定，且可納入 StreamConfigurationMap 中任何可用的格式、大小或其他值。隱藏的格式、大小或其他值 (不在 StreamConfigurationMap 中) 無法納入建議的串流設定對應項目。

所有測試都保持不變，不會根據建議的串流設定放寬。

攝影機實作項目提供的建議串流設定為選用，攝影機用戶端可以忽略這些設定。

實作

請按照下列步驟實作這項功能。

中繼資料項目

如要啟用這項功能，相機 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 影片快照必須包含至少與錄影解析度上限相同的串流設定，且只能使用 BLOB + DATASPACE_JFIF 格式/資料空間組合 (JPEG)。這些設定不應導致預覽畫面出現異常，且應能以 30 fps 的速度執行。
SNAPSHOT 快照串流設定必須至少包含一個大小接近 android.sensor.info.activeArraySize 的 BLOB + DATASPACE_JFIF 格式/資料空間組合 (JPEG)。考量到顯示比例、對齊和其他供應商特定限制，建議的最大尺寸區域不得小於感應器陣列大小區域的 97%。
ZSL (如有支援) 如果攝影機裝置支援，建議輸入串流設定必須與其他經過處理或延遲的輸出格式一併宣傳。
RAW (如有支援) 如果相機裝置支援，建議的原始串流設定必須只包含以 RAW 為基礎的輸出格式。

其他使用情況

您可以針對特定實作用途，提供其他建議的設定串流。

驗證

如要測試您實作建議的設定串流，請執行下列 CTS 和 VTS 測試：

用於查詢地圖項目組合的 API

自 Android 15 起，Android 平台會提供 API 來查詢功能組合。這個 API 可讓相機用戶端查詢裝置是否支援指定的功能組合。這個 API 是必要的，因為 camera2 API 會模擬 4K、60fps、HDR 影片、UltraHDR、超廣角變焦和防震功能等不同功能，做為直角控制項。

需求條件

如要支援 API 查詢功能組合，相機 HAL 必須實作 ICameraDevice 介面的第 3 版。詳情請參閱「實作」一節。

支援 API 時，預覽畫面穩定功能必須與其他功能呈直角。也就是說，對於支援預覽防震功能的相機裝置，在預覽防震功能開啟或關閉時，特定組合的 isStreamCombinationWithSettingsSupported 回傳值必須相同。這可縮小功能組合查詢的搜尋空間。

此外，如果是媒體效能等級 15，主要後置鏡頭必須支援預覽穩定功能，並提供 10 位元 HLG10 預覽功能，以便預覽 1080p 和 720p 預覽畫面，以及最大大小的 JPEG 檔案。如要進一步瞭解這些規定，請參閱第 2.2.7.2 節。CDD 的「攝影機」。

實作

如要支援 API 查詢地圖項目組合，請在 ICameraDevice 3 版中實作下列地圖項目組合查詢 API：

如果 ICameraDevice 介面版本低於 3，HAL 應實作 isStreamCombinationSupported 方法。

如要進一步瞭解 API 查詢的功能組合，請參閱 system/media/camera/docs/metadata_definitions.xml 中的 sessionConfigurationQueryVersion 說明文件。

如需這項功能的參考實作方式，請參閱 hardware/google/camera/devices/EmulatedCamera/hwl/。

公用 API

應用程式可以使用下列公用 API，查詢裝置支援的功能組合：

驗證

如要驗證您實作這項功能的結果，請使用下列 VTS、CTS 和 Camera ITS (CTS 驗證工具) 測試：

VTS

CTS

攝影機 ITS