4、Stream 配置数据结构：camera3_stream_t 与 camera3_stream_configuration_t 详解

在 Camera HAL3 多路 Stream 并行捕获中，camera3_stream_t 和 camera3_stream_configuration_t 是连接 Framework 与 HAL 的核心数据结构。Framework 通过 configure_streams() 调用将配置下发，HAL 据此分配硬件管道、ISP 带宽和内存缓冲区。理解这两个结构体的每个字段，是正确实现多路并行捕获的前提。

4.1 camera3_stream_t：单个 Stream 的属性定义

每个 Stream 代表一条从 Sensor 到内存的数据通路。其结构体定义如下：

typedef struct camera3_stream {
    uint32_t      stream_type;       // CAMERA3_STREAM_OUTPUT / INPUT / BIDIRECTIONAL
    uint32_t      width;             // 图像宽度（像素）
    uint32_t      height;            // 图像高度（像素）
    int32_t       format;            // 像素格式（如 HAL_PIXEL_FORMAT_YCbCr_420_888）
    uint32_t      rotation;          // 旋转角度（0 / 90 / 180 / 270）
    int32_t       usage;             // 缓冲区使用标志（GRALLOC_USAGE_*）
    uint32_t      max_buffers;       // HAL 请求的最大缓冲区数
    void         *priv;              // HAL 私有数据指针
    uint32_t      data_space;        // 色彩空间（HAL_DATASPACE_*）
    int32_t       rotation_override; // 旋转覆盖（Android 12+）
    uint32_t     *physical_camera_id;// 物理 Camera ID 数组（多摄）
    int32_t       num_physical_cameras;// 物理 Camera 数量
    int32_t       timestamp_source;  // 时间戳来源（TANSPARENT / REALTIME）
} camera3_stream_t;

4.2 camera3_stream_configuration_t：Stream 集合与操作模式

该结构体将多个 Stream 打包，并携带全局配置参数：

typedef struct camera3_stream_configuration {
    uint32_t              num_streams;          // Stream 数量
    camera3_stream_t    **streams;              // Stream 指针数组
    uint32_t              operation_mode;       // CAMERA3_STREAM_CONFIGURATION_*
    const camera_metadata_t *session_parameters;// 会话级参数（如 HDR 模式）
    uint32_t              stream_config_counter;// 配置计数器（用于去重）
} camera3_stream_configuration_t;

4.3 多路并行配置的约束关系

下表总结了多路 Stream 并行时各字段的典型约束：

4.4 多路 Stream 配置流程图

以下 SVG 展示了 Framework 下发配置后，HAL 内部对 camera3_stream_configuration_t 的解析与验证流程：

4.5 多路并行配置实战要点

1. Stream 数量上限：通常 HAL 支持 4~6 个并行 Stream。超过时需降级或拒绝配置。
2. 分辨率组合：所有 Stream 的宽高必须 ≤ Sensor 最大输出分辨率。例如 48MP Sensor 不能同时输出 48MP 预览 + 48MP 拍照。
3. 格式兼容性：JPEG 流通常需要额外的 YUV 中间流，HAL 需在内部创建隐藏 Stream。
4. max_buffers 计算：建议按“帧率 × 流水线深度”估算。30fps 预览 + 30fps 录像，每个 Stream 至少 4 个 buffer。
5. operation_mode 选择：多路并行时优先使用 CAMERA3_STREAM_CONFIGURATION_CONSTRAINED_HIGH_SPEED 以获取更高帧率。

4.6 数据结构关系图

以下 SVG 展示了 camera3_stream_configuration_t 与 camera3_stream_t 之间的层级关系：

4.7 常见问题与避坑指南