`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 直接关联的关键组件包括：

CameraMetadata（native 层）
- 定义并填充 ANDROID_SCALER_AVAILABLE_STREAM_CONFIGURATIONS、ANDROID_SCALER_AVAILABLE_MIN_FRAME_DURATIONS 等字段。
CameraCharacteristics（Java 层）
- 从 HAL metadata 映射到 Java 对象，由 CameraManager#getCameraCharacteristics() 返回。
CameraDevice / CaptureSession 配置流程
- 应用层通过 getOutputSizes() 等接口判断目标流是否受支持，并据此创建 ImageReader、SurfaceTexture 等输出对象，作为 Session 配置输入。
StreamConfigurationMap（Java 封装类）
- 封装各类接口能力，包括：
  - getOutputSizes(int format)
  - getOutputMinFrameDuration()
  - isOutputSupportedFor(Class<?> klass)
  - getValidOutputFormatsForInput() 等
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