4. HAL3 核心数据结构：驱动 Camera 管道的四大支柱

Android Camera HAL3 的设计核心在于一套精确定义的数据结构，它们构成了 Framework 与 HAL 之间通信的“契约”。理解 camera3_device_t、camera3_stream_t、camera3_capture_request_t 和 camera3_callback_ops_t 这四大结构体，是掌握 HAL3 架构的基石。本章将逐一剖析它们的职责、关键字段与协作关系。

4.1 camera3_device_t：HAL 设备句柄

camera3_device_t 是 Framework 与具体 Camera HAL 设备交互的入口点。它本质上是一个抽象的设备句柄，封装了所有操作该 Camera 设备的方法指针（函数指针）。

其中 ops 字段指向的 camera3_device_ops_t 包含了 initialize()、configure_streams()、process_capture_request()、flush() 等关键方法。Framework 通过调用这些方法，驱动 HAL 完成初始化、流配置和捕获请求处理。

// camera3_device_t 定义 (简化)
typedef struct camera3_device {
    hw_device_t common;
    camera3_device_ops_t *ops;
    void *priv;
} camera3_device_t;

// camera3_device_ops_t 关键方法
typedef struct camera3_device_ops {
    int (*initialize)(const struct camera3_device *, const camera3_callback_ops_t *);
    int (*configure_streams)(const struct camera3_device *, camera3_stream_configuration_t *);
    int (*process_capture_request)(const struct camera3_device *, camera3_capture_request_t *);
    void (*dump)(const struct camera3_device *, int fd);
    int (*flush)(const struct camera3_device *);
    // ... 其他方法
} camera3_device_ops_t;

4.2 camera3_stream_t：数据流管道定义

camera3_stream_t 描述了一条从 Camera HAL 到 Framework 的单一图像数据流。它定义了图像的格式、分辨率、使用方向以及最大缓冲区数量。在 configure_streams() 阶段，Framework 会向 HAL 传递一个 camera3_stream_t 数组，HAL 需要根据硬件能力确认或调整这些流的参数。

4.3 camera3_capture_request_t：单次捕获的指令集

每一次拍照或预览帧请求，都对应一个 camera3_capture_request_t 结构体。它包含了本次捕获所需的所有元数据、目标输出流缓冲区以及可选的输入缓冲区（用于 reprocessing）。

// camera3_capture_request_t 定义 (简化)
typedef struct camera3_capture_request {
    uint32_t frame_number;          // 帧序号，单调递增
    const camera3_stream_buffer_t *input_buffer; // 输入缓冲区 (reprocessing 时使用)
    uint32_t num_output_buffers;    // 输出缓冲区数量
    const camera3_stream_buffer_t *output_buffers; // 输出缓冲区数组
    const camera_metadata_t *settings; // 捕获参数 (AE/AWB/AF 等)
} camera3_capture_request_t;

4.4 camera3_callback_ops_t：异步结果回传通道

HAL 在处理完一个捕获请求后，不能直接返回结果，而是通过 camera3_callback_ops_t 结构体中定义的回调函数，异步地将结果元数据、捕获的缓冲区以及通知事件（如快门、错误）传递给 Framework。这个结构体由 Framework 在 initialize() 时传入 HAL。

// camera3_callback_ops_t 定义 (简化)
typedef struct camera3_callback_ops {
    void (*process_capture_result)(const struct camera3_callback_ops *,
                                    const camera3_capture_result_t *result);
    void (*notify)(const struct camera3_callback_ops *,
                   const camera3_notify_msg_t *msg);
} camera3_callback_ops_t;

• process_capture_result：回传捕获结果，包括最终元数据、输出缓冲区句柄以及部分结果标志（partial result）。
• notify：回传异步通知，如 CAMERA3_MSG_SHUTTER（快门事件）、CAMERA3_MSG_ERROR（错误事件）。

4.5 四大结构体协作关系图

下面的 SVG 图展示了从 Framework 下发请求到 HAL 回传结果的完整数据流，以及四大结构体在其中扮演的角色。

4.6 关键流程总结

1. 初始化阶段： Framework 调用 camera3_device_t->ops->initialize()，传入 camera3_callback_ops_t 指针，HAL 保存该指针用于后续回调。
2. 流配置阶段： Framework 调用 configure_streams()，传入 camera3_stream_configuration_t（包含 camera3_stream_t 数组），HAL 验证并设置 max_buffers 等参数。
3. 请求阶段： Framework 构造 camera3_capture_request_t，填充帧序号、settings 和 output_buffers，调用 process_capture_request() 提交给 HAL。
4. 处理与回调阶段： HAL 处理请求（如驱动 Sensor 曝光、ISP 处理），完成后通过 camera3_callback_ops_t->process_capture_result() 返回结果，通过 notify() 返回快门事件或错误。