📚 课程目录第1章 Metadata概述

1. Metadata概述：什么是Camera Metadata、Metadata在HAL中的角色、Metadata与Android Camera框架的关系

1.1 什么是Camera Metadata

Camera Metadata是Android Camera框架中用于描述相机设备状态、控制相机行为、传递图像数据属性的结构化数据集合。它采用键值对（Key-Value）的形式，每个Metadata项由一个唯一的整数标识符（Tag）和对应的数据值组成。

Metadata覆盖了相机系统的全部可配置参数和状态信息，包括但不限于：

传感器信息：感光度范围、曝光时间范围、帧率
镜头参数：光圈值、焦距、对焦距离
图像格式：输出分辨率、像素格式、色彩空间
3A算法状态：自动对焦（AF）、自动曝光（AE）、自动白平衡（AWB）
图像处理效果：降噪强度、锐化程度、HDR模式
统计信息：人脸检测结果、场景检测结果

关键概念：Camera Metadata是Android相机系统的"神经中枢"，它承载了从应用层到底层硬件之间的所有控制指令和状态反馈。

Metadata的数据结构定义在 system/media/camera/docs 目录下的文档中，并通过 camera_metadata.h 头文件实现。每个Metadata项包含以下字段：

字段	说明	示例
Tag	唯一标识符，用于索引Metadata项	`ANDROID_SENSOR_EXPOSURE_TIME`
Type	数据类型（BYTE、INT32、FLOAT、INT64、DOUBLE、RATIONAL）	`TYPE_INT64`
Count	数据元素个数	`1`
Value	实际数据值	`33333333`（纳秒）

1.2 Metadata在HAL中的角色

在Camera HAL（Hardware Abstraction Layer）中，Metadata扮演着双向数据通道的角色：

下行通道（应用→HAL）：应用层通过CaptureRequest携带Metadata，向HAL下发拍摄参数和控制指令。
上行通道（HAL→应用）：HAL通过CaptureResult携带Metadata，向应用层返回实际使用的参数和传感器状态。

HAL层对Metadata的处理遵循以下核心原则：

完整性校验：HAL必须验证所有输入Metadata的合法性，对非法参数返回错误或使用默认值。
状态同步：HAL需要将硬件实际状态（如实际曝光时间、实际帧率）写入输出Metadata。
性能优化：HAL可以基于Metadata中的参数进行硬件加速处理，如ISP管线配置。

最佳实践：HAL实现中，Metadata的生成应尽量在硬件事件回调中完成，确保状态信息的实时性和准确性。延迟生成Metadata会导致应用层获取到过时的相机状态。

以下SVG图展示了Metadata在HAL中的双向流转路径：

1.3 Metadata与Android Camera框架的关系

Android Camera框架采用分层架构，Metadata贯穿整个框架的各个层级：

框架层级	组件	Metadata角色	关键类/接口
应用层	Camera App	构造CaptureRequest，解析CaptureResult	`CameraCaptureSession`
框架层	CameraService	Metadata路由、权限校验、格式转换	`CameraMetadataNative`
HAL层	Camera HAL	Metadata解析、硬件控制、状态生成	`camera3_capture_request`
内核层	V4L2 / ISP驱动	硬件寄存器读写、中断处理	`ioctl` 调用

Metadata在框架中的生命周期包含以下关键阶段：

静态信息获取：应用层通过 CameraCharacteristics 获取相机设备的静态Metadata（如支持的分辨率列表、传感器尺寸）。
请求构造：应用层创建 CaptureRequest，填充控制类Metadata（如曝光时间、对焦模式）。
框架转发：CameraService将CaptureRequest转换为HAL可识别的 camera3_capture_request_t 结构体。
HAL处理：HAL解析Metadata，配置硬件寄存器，触发图像采集。
结果生成：HAL将硬件实际状态封装为 CaptureResult，包含结果类Metadata。
应用回调：框架层将CaptureResult回调给应用层，应用层解析Metadata获取拍摄结果。

常见陷阱：应用层设置的Metadata参数并不总是被硬件精确执行。例如，设置曝光时间为100ms，但硬件可能因为帧率限制实际只执行了33ms。因此，应用层必须通过CaptureResult中的实际值来确认硬件执行结果，而不是依赖请求值。

以下SVG图展示了Metadata在Android Camera框架各层级间的流转关系：

1.4 Metadata的分类体系

根据用途和生命周期，Camera Metadata可分为以下三大类：

分类	前缀	特点	典型示例
静态Metadata	`ANDROID_INFO_*`	设备初始化时固定不变，只读	`ANDROID_INFO_SUPPORTED_HARDWARE_LEVEL`
控制Metadata	`ANDROID_CONTROL_*`	应用层下发，控制拍摄行为	`ANDROID_CONTROL_AE_TARGET_FPS_RANGE`
结果Metadata	`ANDROID_STATISTICS_*`	HAL返回，反映实际状态	`ANDROID_STATISTICS_FACE_RECTANGLES`

核心要点：理解Metadata的分类体系是掌握Camera HAL开发的基础。静态Metadata决定了设备能力边界，控制Metadata是应用与HAL交互的主要手段，结果Metadata是验证硬件执行正确性的唯一依据。

在HAL开发中，Metadata的生成与消费遵循以下数据流模式：

// 伪代码：HAL层Metadata处理流程
void process_capture_request(camera3_capture_request_t *request) {
    // 1. 解析输入Metadata（消费）
    camera_metadata_ro_entry_t entry;
    find_camera_metadata_ro_entry(request->settings,
        ANDROID_SENSOR_EXPOSURE_TIME, &entry);
    int64_t exposure_time = entry.data.i64[0];

    // 2. 配置硬件
    sensor_set_exposure(exposure_time);

    // 3. 生成输出Metadata（生产）
    camera_metadata_t *result_metadata = allocate_camera_metadata();
    int64_t actual_exposure = sensor_get_actual_exposure();
    camera_metadata_entry_t result_entry;
    add_camera_metadata_entry(result_metadata,
        ANDROID_SENSOR_EXPOSURE_TIME, &actual_exposure, 1);

    // 4. 返回结果
    return_result(request->frame_number, result_metadata);
}

通过以上分析可以看出，Metadata是Android Camera框架中连接应用层与硬件层的核心数据载体。掌握Metadata的生成与消费机制，是深入理解Camera HAL开发的关键前提。