3. Camera HAL 关键数据结构详解

在 Camera HAL 开发与调试中，理解核心数据结构是定位问题的基石。本章深入剖析 camera_metadata、camera3_stream_t、camera3_capture_request_t 和 camera3_capture_result_t 四个关键结构体，涵盖其设计意图、字段含义、生命周期及调试要点。

3.1 camera_metadata：控制与元数据的通用容器

camera_metadata 是 Android Camera 框架中用于传递控制参数和结果元数据的核心数据结构。它采用序列化的键值对存储方式，支持高效的查找与更新。

3.1.1 数据结构布局

// camera_metadata 内部布局（简化示意）
typedef struct camera_metadata {
    size_t          size;           // 总大小
    uint32_t        version;        // 版本号
    uint32_t        flags;          // 标志位
    size_t          entry_count;    // 当前条目数
    size_t          entry_capacity; // 最大条目容量
    size_t          data_count;     // 当前数据项数
    size_t          data_capacity;  // 最大数据容量
    uint8_t*        entries;        // 条目数组起始地址
    uint8_t*        data;           // 数据缓冲区起始地址
} camera_metadata_t;

3.1.2 常用操作与调试接口

3.2 camera3_stream_t：图像数据流的管道定义

camera3_stream_t 定义了从 HAL 到框架的图像数据流属性。每个流对应一个特定的消费者（如预览 Surface、拍照 JPEG 编码器、视频编码器）。

3.2.1 关键字段解析

typedef struct camera3_stream {
    int      stream_type;    // CAMERA3_STREAM_OUTPUT / INPUT / BIDIRECTIONAL
    uint32_t width;          // 图像宽度（像素）
    uint32_t height;         // 图像高度（像素）
    int      format;         // 像素格式（HAL_PIXEL_FORMAT_xxx）
    uint32_t usage;          // 消费者使用标志（GRALLOC_USAGE_xxx）
    uint32_t max_buffers;    // HAL 可同时持有的最大 buffer 数
    void*    priv;           // HAL 私有数据指针
    int      rotation;       // 输出旋转角度
    int      physical_camera_id; // 多摄场景下的物理 camera ID
} camera3_stream_t;

3.2.2 流配置与调试要点

3.3 camera3_capture_request_t：一次捕获的完整指令

该结构体封装了 HAL 执行一次图像捕获所需的所有信息：目标流、输入 buffer、控制参数和设置。

3.3.1 结构体定义

typedef struct camera3_capture_request {
    uint32_t                frame_number;   // 帧序号，单调递增
    const camera_metadata_t* settings;      // 本次捕获的控制参数
    size_t                  num_output_buffers; // 输出 buffer 数量
    const camera3_stream_buffer_t* output_buffers; // 输出 buffer 数组
    const camera3_stream_buffer_t* input_buffer;   // 输入 buffer（ZSL/ reprocess 时使用）
} camera3_capture_request_t;

3.3.2 请求生命周期与调试

1. 创建： CameraService 根据应用请求构建 request，填充 settings 和 output_buffers。
2. 下发： 通过 process_capture_request 传递给 HAL。
3. 处理： HAL 解析 settings，驱动 sensor 曝光，ISP 处理，填充 output_buffers。
4. 返回： HAL 通过 process_capture_result 返回结果。

3.4 camera3_capture_result_t：捕获结果的完整汇报

HAL 通过该结构体将处理完成的帧结果返回给框架，包含 metadata、输出 buffer 和错误信息。

3.4.1 结构体定义

typedef struct camera3_capture_result {
    uint32_t                frame_number;       // 对应请求的帧序号
    const camera_metadata_t* result;            // 结果 metadata（AE/AWB/传感器参数等）
    size_t                  num_output_buffers; // 返回的输出 buffer 数量
    const camera3_stream_buffer_t* output_buffers; // 输出 buffer 数组
    uint32_t                partial_result;     // 部分结果序号（用于分阶段返回）
} camera3_capture_result_t;

3.4.2 部分结果机制

HAL 可以分多次返回同一个 frame_number 的结果，通过 partial_result 字段标识阶段：

3.5 数据结构关系总览

下图展示了四个关键数据结构在一次完整 capture 流程中的交互关系：

3.6 调试实战：常见问题与数据结构关联