2. 核心数据结构：camera3_device_t、camera3_callback_ops_t、camera3_stream_t 结构体详解

在 Camera HAL3 框架中，camera3_device_t、camera3_callback_ops_t 和 camera3_stream_t 是构成 HAL 层与 Framework 通信的三大核心数据结构。它们分别定义了 HAL 设备接口、回调操作集和流配置描述。理解这三个结构体是掌握 CaptureRequest 处理流程的基础。

2.1 camera3_device_t：HAL 设备抽象

camera3_device_t 是 HAL3 设备在 Framework 侧的抽象表示。它继承自 hw_device_t，并扩展了 HAL3 特有的操作函数指针。Framework 通过该结构体调用 HAL 层的初始化、配置流、提交请求等核心接口。

typedef struct camera3_device {
    hw_device_t common;                     // 继承自 hw_device_t，包含版本号、模块句柄等
    camera3_device_ops_t *ops;              // 操作函数指针集，HAL 必须实现
    void *priv;                             // HAL 私有数据指针，Framework 不直接使用
} camera3_device_t;

下表列出了 camera3_device_ops_t 中最重要的几个函数指针及其职责：

2.2 camera3_callback_ops_t：异步事件通知通道

camera3_callback_ops_t 是 Framework 提供给 HAL 的回调函数集合。HAL 在处理请求的过程中，通过该结构体中的函数指针将结果帧、错误信息、缓冲区状态等异步事件通知给 Framework。该结构体在 initialize() 调用时由 Framework 传入。

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;

两个回调函数的职责对比如下：

2.3 camera3_stream_t：流配置描述

camera3_stream_t 描述了一个 Camera 数据流的配置信息，包括图像格式、分辨率、使用方向、最大缓冲区数等。在 configure_streams() 调用中，Framework 传入一个 camera3_stream_t 数组，HAL 需要根据这些配置分配硬件资源并设置 usage、max_buffers 和 priv 字段。

typedef struct camera3_stream {
    int stream_type;                // CAMERA3_STREAM_OUTPUT / INPUT / BIDIRECTIONAL
    uint32_t width;                 // 图像宽度（像素）
    uint32_t height;                // 图像高度（像素）
    int format;                     // 像素格式，如 HAL_PIXEL_FORMAT_YCbCr_420_888
    uint32_t usage;                 // 缓冲区使用标志，由 HAL 填充
    uint32_t max_buffers;           // HAL 请求的最大缓冲区数
    void *priv;                     // HAL 私有数据
    android_dataspace_t data_space; // 数据空间（颜色空间等）
    int rotation;                   // 输出旋转角度
    int reserved[6];                // 保留字段
} camera3_stream_t;

下表列出了 stream_type 的三种取值及其典型用途：

2.4 三者协作关系总结

在 CaptureRequest 的完整生命周期中，三个结构体按照以下顺序协作：

1. 设备打开： Framework 通过 HAL 模块获取 camera3_device_t 实例。
2. 初始化： Framework 调用 ops->initialize()，传入 camera3_callback_ops_t 回调接口。
3. 流配置： Framework 调用 ops->configure_streams()，传入 camera3_stream_t 数组，HAL 填充 usage、max_buffers 等字段。
4. 请求处理： Framework 调用 ops->process_capture_request()，HAL 处理完成后通过 camera3_callback_ops_t 返回结果。
5. 错误处理： 发生异常时，HAL 通过 notify() 回调上报错误信息。