StreamConfigurationMap 實現邏輯與解析過程詳解：相機流能力的聲明、匹配與驗證機制全景

關鍵詞：
StreamConfigurationMap、CameraCharacteristics、OutputFormat、InputFormat、Size 配置、幀率范圍、流兼容性、配置失敗調試

摘要：
StreamConfigurationMap 是 Android 相機框架中的關鍵數據結構之一，承載了 HAL 層報告的所有可支持流組合，包括輸出格式、輸入重處理格式、尺寸列表、最低幀率等信息。在開發中，無論是構建 ImageReader、配置 CaptureSession，還是校驗目標尺寸是否支持，均離不開對其的正確解析與使用。本文將基于 AOSP 最新版本源碼與平臺實踐，系統拆解 StreamConfigurationMap 的構建路徑、接口實現、內部數據組織與典型問題處理策略，幫助開發者深入理解背后的匹配邏輯與流能力限制。

---

目錄

一、系統定位：StreamConfigurationMap 的作用與關聯模塊概覽
二、能力聲明入口：HAL 如何填充 stream 配置能力并傳遞給 framework
三、構建路徑追蹤：從 HAL Metadata 到 Java 層 Map 對象的封裝過程
四、關鍵接口詳解：getOutputSizes / getInputFormats / getValidOutputFormatsForInput 行為分析
五、內部數據結構解析：Size 配置 × Format 映射 × Dynamic Range 支持方式
六、典型問題場景分析：尺寸不支持、流類型沖突、format 配置失敗案例
七、性能與兼容性建議：構建 Session 前的能力預判與流選型策略
八、工程調試技巧：如何通過 dumpsys + HAL log + camera-profile.xml 還原 stream 匹配流程

---

一、系統定位：StreamConfigurationMap 的作用與關聯模塊概覽

在 Android Camera 框架中，StreamConfigurationMap 是 CameraCharacteristics 返回結構的一部分，主要承載與流配置能力相關的聲明信息，其本質是 HAL 層通過 metadata 報告的一組支持的輸入/輸出格式、尺寸、幀率范圍與重處理能力的集合，它是 Camera 流設計與 Session 創建過程的核心決策依據。

整個框架中與 StreamConfigurationMap 直接關聯的關鍵組件包括：

1. CameraMetadata（native 層）

   • 定義并填充 ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS、ANDROID_SCALER_AVAILABLE_MIN_FRAME_DURATIONS 等字段。

2. CameraCharacteristics（Java 層）

   • 從 HAL metadata 映射到 Java 對象，由 CameraManager#getCameraCharacteristics() 返回。

3. CameraDevice / CaptureSession 配置流程

   • 應用層通過 getOutputSizes() 等接口判斷目標流是否受支持，并據此創建 ImageReader、SurfaceTexture 等輸出對象，作為 Session 配置輸入。

4. StreamConfigurationMap（Java 封裝類）

   • 封裝各類接口能力，包括：

     • getOutputSizes(int format)
     • getOutputMinFrameDuration()
     • isOutputSupportedFor(Class<?> klass)
     • getValidOutputFormatsForInput() 等

5. CameraCaptureSession 設備協商路徑

   • session 構建前，CameraFramework 會根據 StreamConfigurationMap 中的內容對輸入流和輸出流組合進行合法性校驗，非法配置會直接拋出 IllegalArgumentException。

總結來說，StreamConfigurationMap 處于 framework 與 HAL 能力協商的關鍵中間層，是連接App × Framework × HAL的標準能力橋梁，其合理性直接決定了拍照、錄像、預覽、AI流等功能是否能夠順利啟用。

---

二、能力聲明入口：HAL 如何填充 stream 配置能力并傳遞給 framework

HAL 通過向系統上報靜態 metadata 的方式，向上層暴露 Camera 的流配置能力。其核心字段包括：

1. ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS

該字段是最關鍵的配置列表，格式如下：

typedef struct camera3_stream_configuration {int32_t format;         // 輸出或輸入格式，如 YUV_420_888、JPEG、RAW_SENSORuint32_t width;         // 分辨率寬度uint32_t height;        // 分辨率高度uint32_t isInput;       // 0 表示輸出，1 表示輸入（如 reprocessing）
} camera3_stream_configuration_t;

HAL 層會在 get_camera_metadata() 時，將上述配置封裝成一組 CameraMetadataEntry 條目，以靜態 metadata 形式報告。

舉例：

const int32_t available_stream_config[] = {HAL_PIXEL_FORMAT_YCbCr_420_888, 1920, 1080, 0,HAL_PIXEL_FORMAT_YCbCr_420_888, 1280, 720, 0,HAL_PIXEL_FORMAT_BLOB,          4032, 3024, 0,HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED