3. Camera HAL3 核心数据结构详解

Camera HAL3 接口的设计围绕四个核心数据结构展开：camera3_device_t、camera3_callback_ops_t、camera3_stream_t 和 camera3_capture_request_t。这四个结构体构成了 HAL3 与 Camera Service 之间通信的契约基础，理解它们是开发稳定、高性能 Camera HAL 的必修课。

3.1 camera3_device_t：HAL 设备句柄

camera3_device_t 是 Camera Service 与 HAL 交互的入口点，代表一个物理或逻辑摄像头设备。它继承自 hw_device_t，并扩展了 HAL3 特有的操作函数指针。

typedef struct camera3_device {
    hw_device_t common;
    camera3_device_ops_t *ops;
    void *priv;
} camera3_device_t;

3.2 camera3_callback_ops_t：异步回调契约

当 Camera Service 调用 initialize() 时，会传入一个 camera3_callback_ops_t 结构体指针。HAL 通过这个结构体向 Service 异步通知事件、返回结果数据和发送信号。

typedef struct camera3_callback_ops {
    void (*process_capture_result)(const struct camera3_callback_ops *,
                                   const camera3_capture_result_t *);
    void (*notify)(const struct camera3_callback_ops *,
                   const camera3_notify_msg_t *);
    void (*process_capture_result_with_flags)(const struct camera3_callback_ops *,
                                              const camera3_capture_result_t *,
                                              uint32_t flags);
} camera3_callback_ops_t;

3.3 camera3_stream_t：数据流管道

camera3_stream_t 描述一条从 HAL 到 Consumer（如 SurfaceView、ImageReader、MediaCodec）的数据流。在 configure_streams() 中，Service 向 HAL 传递一个流数组，HAL 需要验证并配置这些流。

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;
    const camera_metadata_t *stream_configuration;
    const camera_metadata_t *stream_parameters;
    void *priv;
    int data_space;            // HAL_DATASPACE_xxx
    int rotation;              // CAMERA3_STREAM_ROTATION_xxx
    const char *physical_camera_id;
    uint64_t buffer_size;
    int vndk_version;
} camera3_stream_t;

3.4 camera3_capture_request_t：一次捕获的完整描述

每次拍照或预览帧的请求都由 camera3_capture_request_t 描述。Service 通过 process_capture_request() 将请求下发到 HAL，HAL 解析后驱动传感器曝光、ISP 处理并最终返回结果。

typedef struct camera3_capture_request {
    uint32_t frame_number;
    const camera_metadata_t *settings;
    camera3_stream_buffer_t *input_buffer;
    uint32_t num_input_buffers;
    camera3_stream_buffer_t *output_buffers;
    uint32_t num_output_buffers;
    const camera_metadata_t *physical_camera_settings;
    int32_t *physcam_id;
    uint32_t num_physcam_settings;
} camera3_capture_request_t;

3.5 四个核心结构体的协作关系

在实际的 Camera HAL 实现中，这四个结构体通过以下时序协作完成一次完整的拍照或预览流程：

1. 初始化阶段： Service 调用 open() 获取 camera3_device_t，然后调用 ops->initialize() 传入 camera3_callback_ops_t。
2. 流配置阶段： Service 调用 ops->configure_streams() 传入 camera3_stream_t 数组，HAL 验证并设置 max_buffers 和 priv。
3. 请求下发阶段： Service 构造 camera3_capture_request_t，调用 ops->process_capture_request() 下发。
4. 结果返回阶段： HAL 通过 callback_ops->notify() 发送 SHUTTER 事件，通过 callback_ops->process_capture_result() 返回填充好的 buffer 和 metadata。