4、波形文件解析：LUT结构、温度补偿、灰度级映射与波形时长参数

波形文件（Waveform File）是墨水屏驱动的“固件灵魂”，它决定了像素从一种光学状态转换到另一种光学状态所需的电压序列与时间序列。波形文件的核心是查找表（LUT，Lookup Table），驱动芯片通过查表获得每一帧的驱动电压与持续时间。本章深入解析LUT的内部结构、温度补偿机制、灰度级映射关系以及波形时长参数，帮助开发者精准调优全局刷新流程中的双缓冲时序。

4.1 LUT结构：从逻辑地址到物理波形

LUT本质上是一个多维数组，其索引由当前灰度级（Current Gray Level）、目标灰度级（Target Gray Level）以及温度区间（Temperature Range）共同决定。每个表项存储一组波形阶段（Phase）描述符，每个阶段包含电压极性、持续时间以及帧数。

4.2 温度补偿：电泳速度的温度依赖性

墨水屏的电泳粒子迁移率随温度变化显著。低温下粒子运动缓慢，需要更长的驱动时间或更高的电压；高温下粒子运动过快，需要缩短驱动时间以避免过冲。温度补偿机制通过多组LUT或LUT内的温度缩放因子实现。

4.3 灰度级映射：从像素值到LUT索引

墨水屏的灰度级通常为4级（2bit）、8级（3bit）或16级（4bit）。驱动芯片内部维护一个灰度映射表（Gray Mapping Table），将像素的二进制灰度值转换为LUT索引。映射表的设计直接影响显示均匀性和残影抑制效果。

// 灰度映射表示例：4级灰度（2bit）到LUT索引的重新映射
// 原始线性映射: [0, 1, 2, 3]
// 优化后映射（基于Gamma 1.8校正）: [0, 2, 3, 1]
// 注意：索引顺序根据面板实测调整，目的是让中间灰度更均匀

const uint8_t gray_mapping[4] = {0, 2, 3, 1};

// 在全局刷新流程中，使用映射后的索引查LUT
uint8_t lut_index = gray_mapping[pixel_value & 0x03];
waveform_phase_t *phase = &lut_table[lut_index][temperature_zone];

4.4 波形时长参数：帧周期与总刷新时间

波形时长参数决定了全局刷新一次完整流程的耗时。关键参数包括：

• 帧周期（Frame Period）：驱动芯片输出一帧数据的时间，通常为10ms~30ms，由行扫描频率和面板尺寸决定。
• 阶段时长（Phase Duration）：每个波形阶段持续的基本时间单位，通常为帧周期的整数倍。
• 总帧数（Total Frame Count）：所有阶段重复帧数的累加和。
• 总刷新时间（Total Refresh Time） = 总帧数 × 帧周期。

// 波形时长参数计算示例
// 假设帧周期 = 20ms，LUT包含4个阶段

typedef struct {
    uint8_t voltage;      // 0:0V, 1:+15V, 2:-15V
    uint8_t duration_ms;  // 阶段时长（毫秒）
    uint8_t repeat;       // 重复次数
} phase_t;

phase_t phases[4] = {
    {1, 20, 3},   // +15V, 20ms, 重复3次 → 3帧
    {2, 10, 1},   // -15V, 10ms, 重复1次 → 1帧
    {1, 30, 2},   // +15V, 30ms, 重复2次 → 3帧（30ms/20ms=1.5，向上取整为2帧？实际按帧对齐）
    {0, 40, 1}    // 0V,   40ms, 重复1次 → 2帧
};

// 注意：duration_ms 必须对齐帧周期，实际驱动中 duration_ms 是帧周期的整数倍
// 修正为帧对齐版本：
phase_t phases_aligned[4] = {
    {1, 20, 3},   // 3帧 × 20ms = 60ms
    {2, 20, 1},   // 1帧 × 20ms = 20ms
    {1, 20, 3},   // 3帧 × 20ms = 60ms（30ms对齐到2帧？此处按3帧实现更长的驱动）
    {0, 20, 2}    // 2帧 × 20ms = 40ms
};
// 总帧数 = 3 + 1 + 3 + 2 = 9帧
// 总刷新时间 = 9 × 20ms = 180ms

4.5 波形文件解析实战：从二进制到可读配置

实际波形文件通常以二进制格式存储，包含文件头、LUT数据块、温度补偿表、灰度映射表以及校验和。解析流程如下：

1. 读取文件头：验证魔数（Magic Number）和版本号，获取LUT组数、灰度级数、温度区间数。
2. 解析温度补偿表：读取每个温度区间的缩放因子或独立LUT偏移地址。
3. 解析灰度映射表：读取从像素灰度到LUT索引的映射数组。
4. 解析LUT数据块：遍历所有灰度对和温度区间，提取每个表项的Phase Count、Voltage、Duration、Frame Repeat。
5. 计算总帧数：对每个LUT表项，累加所有Phase的Frame Repeat，得到该转换所需的总帧数。
6. 生成可读配置：将解析结果输出为C头文件或JSON格式，供驱动代码直接包含。

// 波形文件解析核心结构（C语言示例）
typedef struct {
    uint8_t  magic[4];           // 魔数，如 "WAVF"
    uint8_t  version;            // 版本号
    uint8_t  gray_levels;        // 灰度级数（4/8/16）
    uint8_t  temp_zones;         // 温度区间数（通常8）
    uint16_t lut_entry_count;    // LUT表项总数
    uint32_t data_offset;        // LUT数据块偏移
    uint32_t checksum;           // 校验和
} waveform_header_t;

typedef struct {
    uint8_t phase_count;         // 阶段数量
    uint8_t voltage[16];         // 每个阶段的电压
    uint8_t duration[16];        // 每个阶段的时长（帧周期倍数）
    uint8_t repeat[16];          // 每个阶段的重复次数
    uint16_t total_frames;       // 预计算的总帧数
} lut_entry_t;

// 解析单个LUT表项并计算总帧数
void parse_lut_entry(const uint8_t *data, lut_entry_t *entry) {
    entry->phase_count = data[0] & 0x0F;
    entry->total_frames = 0;
    for (int i = 0; i < entry->phase_count; i++) {
        entry->voltage[i]  = (data[1 + i*3] >> 6) & 0x03;
        entry->duration[i] = data[1 + i*3] & 0x3F;
        entry->repeat[i]   = data[2 + i*3] & 0x0F;
        entry->total_frames += entry->repeat[i];
    }
}

通过本章的学习，开发者应能够独立解析任意墨水屏波形文件，理解LUT结构与温度补偿、灰度映射、波形时长之间的耦合关系，并能够将解析结果应用于双缓冲机制的帧数