4. HAL3 核心数据结构详解

Android Camera HAL3 接口围绕四个核心数据结构构建了完整的相机管道：设备描述、数据流、请求提交与结果返回。理解这些结构是掌握多摄切换与 Pipeline 资源管理的基础。本章逐一拆解其字段含义、生命周期与协作关系。

4.1 camera3_device_t：HAL 设备句柄

camera3_device_t 是 Camera HAL 设备在框架层的抽象表示，每个逻辑 Camera（包括多摄中的主摄、广角、长焦）都对应一个独立的 camera3_device_t 实例。它由 open() 调用创建，由 close() 销毁。

typedef struct camera3_device {
    // HAL 设备版本号，必须为 HARDWARE_DEVICE_API_VERSION(3, x)
    hw_device_t common;

    // 设备私有数据指针，HAL 实现方使用
    void *priv;

    // 操作函数集：初始化、配置流、提交请求等
    camera3_device_ops_t *ops;

    // 预留字段
    void *reserved[2];
} camera3_device_t;

4.2 camera3_stream_t：数据流描述

camera3_stream_t 描述一条从 Camera 传感器到内存缓冲区的数据通道。在多摄场景中，每个物理 Camera 可以同时拥有多个流（预览流、拍照流、视频流），而逻辑 Camera 则通过 camera3_stream_configuration_t 聚合所有物理流的配置。

typedef struct camera3_stream {
    // 流类型：CAMERA3_STREAM_OUTPUT / INPUT / BIDIRECTIONAL
    int stream_type;

    // 图像宽度、高度（像素）
    uint32_t width;
    uint32_t height;

    // 图像格式：HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED / YCbCr_420_888 / BLOB 等
    int format;

    // 使用标记：GRALLOC_USAGE_HW_TEXTURE / GRALLOC_USAGE_HW_CAMERA_WRITE 等
    uint32_t usage;

    // 最大缓冲数（HAL 可修改）
    uint32_t max_buffers;

    // 私有指针：HAL 用于关联 Pipeline 内部状态
    void *priv;

    // 数据空间（颜色空间、动态范围等）
    android_dataspace_t data_space;

    // 旋转角度
    int rotation;

    // 物理 Camera ID（多摄时标识该流属于哪个物理 Camera）
    const char *physical_camera_id;

    // 预留字段
    void *reserved[6];
} camera3_stream_t;

4.3 camera3_capture_request_t：捕获请求

每次拍照、预览帧或视频帧的采集都由一个 camera3_capture_request_t 发起。它包含了帧号、目标流、控制参数以及物理 Camera 的元数据。在多摄同步场景中，一个请求可以同时包含多个物理 Camera 的设置。

typedef struct camera3_capture_request {
    // 帧号，单调递增，用于追踪请求与结果的对应关系
    uint32_t frame_number;

    // 请求关联的 output stream 指针数组
    const camera3_stream_t *const *output_buffers;

    // output_buffers 数组长度
    uint32_t num_output_buffers;

    // 输入 stream（用于 reprocess 场景）
    const camera3_stream_t *input_buffer;

    // 请求元数据（settings），包含 3A 参数、AE/AWB 模式、裁剪区域等
    const camera_metadata_t *settings;

    // 物理 Camera settings 数组（Android 9+），用于多摄独立控制
    uint32_t num_physcam_settings;
    const camera_metadata_t *const *physcam_settings;

    // 物理 Camera ID 数组，与 physcam_settings 一一对应
    const char *const *physcam_id;

    // 预留字段
    void *reserved[4];
} camera3_capture_request_t;

4.4 camera3_capture_result_t：捕获结果

HAL 通过 camera3_capture_result_t 将处理后的帧数据、元数据和状态返回给框架。每个 frame_number 对应一个最终结果，但 HAL 可以分多次返回 partial result（例如先返回 metadata，再返回 buffer）。

typedef struct camera3_capture_result {
    // 对应请求的帧号
    uint32_t frame_number;

    // 结果元数据（最终 3A 状态、传感器时间戳、统计信息等）
    const camera_metadata_t *result;

    // 输出 buffer 数组（已填充数据的 buffer）
    uint32_t num_output_buffers;
    const camera3_stream_buffer_t *output_buffers;

    // 输入 buffer（reprocess 场景）
    const camera3_stream_buffer_t *input_buffer;

    // partial result 序号：1 表示第一个 partial，递增到 num_partial_results
    uint32_t partial_result;

    // 物理 Camera 结果元数据（Android 9+）
    uint32_t num_physcam_metadata;
    const camera_metadata_t *const *physcam_metadata;
    const char *const *physcam_ids;

    // 预留字段
    void *reserved[6];
} camera3_capture_result_t;

4.5 四元组协作流程总结

四个核心数据结构在 Camera HAL3 中的协作遵循以下时序：

1. 设备初始化：框架调用 open() 获得 camera3_device_t，然后调用 ops->initialize() 传入回调接口。
2. 流配置：框架构造 camera3_stream_t 数组，通过 ops->configure_streams() 传递给 HAL。HAL 根据 physical_camera_id 分配 Pipeline 资源。
3. 请求提交：框架填充 camera3_capture_request_t，设置 frame_number、settings、output_buffers 和 physcam_settings，调用 ops->process_capture_request()。
4. 结果返回：HAL 通过回调函数返回 camera3_capture_result_t，包含处理后的 buffer 和元数据。框架根据 frame_number 匹配请求与结果。