📚 课程目录第4章显示驱动核心

显示驱动核心：lv_disp_drv_init、flush_cb 与双缓冲机制

各位同学，今天我们来啃一块硬骨头——显示驱动的核心三件套。说实话，很多做 LVGL 移植的朋友，卡就卡在这一块。初始化没搞对，屏幕不亮；flush_cb 写错了，画面撕裂；缓冲没配好，内存爆了。我当年第一次调 STM32F429 的 LTDC 驱动，整整花了三天才把第一个像素点刷出来……嗯，今天咱们就把这些坑一个一个填平。

1. lv_disp_drv_init：驱动对象的“出生证明”

在 LVGL 里，每个显示设备都对应一个 lv_disp_drv_t 结构体。这个结构体就像一张“出生证明”，记录了显示器的所有关键信息。初始化它，就是给这张证明填上正确的数据。

核心要点：lv_disp_drv_init() 只做一件事——把所有字段设为默认值。真正的配置工作，得我们自己来。

// 典型初始化流程
lv_disp_drv_t disp_drv;
lv_disp_drv_init(&disp_drv);          // 1. 先初始化默认值

disp_drv.hor_res = 480;               // 2. 水平分辨率
disp_drv.ver_res = 272;               // 3. 垂直分辨率
disp_drv.flush_cb = my_flush_cb;      // 4. 注册刷新回调
disp_drv.draw_buf = &draw_buf;        // 5. 绑定绘制缓冲区

lv_disp_drv_register(&disp_drv);      // 6. 注册到 LVGL 内核

这里有个细节我特别想强调：分辨率必须和你的物理屏幕完全一致。我在项目中遇到过有人把 800x480 的屏幕配成 480x272，结果画面只显示左上角一小块，排查了半天才发现是这里写错了。

字段	说明	常见坑点
hor_res / ver_res	物理分辨率	不要和 framebuffer 尺寸混淆
flush_cb	刷新回调函数指针	必须非 NULL，否则屏幕不更新
draw_buf	绘制缓冲区指针	必须提前初始化，否则崩溃
user_data	用户自定义数据	可以用来传递 LCD 句柄

2. flush_cb 回调：真正的“搬运工”

flush_cb 是 LVGL 和硬件之间的桥梁。LVGL 在内存里画好了一帧画面的一部分，然后通过这个回调告诉你：“嘿，把这部分数据送到屏幕上去！”

说白了，这就是一个内存搬运函数。但搬运也有搬运的讲究。

static void my_flush_cb(lv_disp_drv_t *disp_drv,
                        const lv_area_t *area,
                        lv_color_t *color_p)
{
    // 1. 计算要刷新的区域大小
    int32_t x1 = area->x1;
    int32_t x2 = area->x2;
    int32_t y1 = area->y1;
    int32_t y2 = area->y2;
    uint32_t w = x2 - x1 + 1;
    uint32_t h = y2 - y1 + 1;

    // 2. 调用底层 LCD 驱动，把 color_p 的数据刷到屏幕
    lcd_draw_bitmap(x1, y1, w, h, (uint16_t *)color_p);

    // 3. 通知 LVGL 刷新完成（非常重要！）
    lv_disp_flush_ready(disp_drv);
}

警告：忘记调用 lv_disp_flush_ready() 是新手最常见的错误。不调用这个函数，LVGL 会认为刷新还没完成，整个渲染管线就会卡死。我曾经调试一个客户的项目，屏幕死活不更新，最后发现就是少了这一行。

flush_cb 的执行频率非常高——每次 LVGL 渲染完一个脏矩形区域就会调用一次。所以这个函数必须高效。我个人的习惯是：

不要在 flush_cb 里做复杂的计算
不要用 printf 打印调试信息（会严重拖慢速度）
如果 LCD 控制器支持 DMA，尽量用 DMA 传输

3. Framebuffer：显存的那点事

Framebuffer，说白了就是一块内存区域，用来存放一帧画面的像素数据。LVGL 把 UI 元素渲染到这个缓冲区里，然后 flush_cb 把它送到屏幕。

framebuffer 的大小怎么算？很简单：

framebuffer_size = 水平分辨率 × 垂直分辨率 × 每个像素的字节数

举个例子，480x272 的屏幕，颜色格式是 RGB565（每个像素 2 字节）：

480 × 272 × 2 = 261,120 字节 ≈ 255 KB

看起来不大？但如果你用 ARGB8888（每个像素 4 字节），同样的分辨率就要 522 KB。在资源受限的 MCU 上，这可不是个小数目。

经验之谈：我建议在项目初期就确定好颜色格式。RGB565 是性能和画质的平衡点，大多数嵌入式场景够用了。除非你要显示照片级图片，否则没必要上 ARGB8888。

4. 双缓冲机制：告别撕裂

单缓冲的问题很明显：LVGL 在往 framebuffer 里画新一帧的时候，flush_cb 可能正在把旧数据往屏幕上送。这就导致屏幕上一半是旧画面，一半是新画面——这就是“撕裂”。

双缓冲怎么解决？很简单：准备两个缓冲区。

后台缓冲区（Back Buffer）：LVGL 在这里绘制新画面
前台缓冲区（Front Buffer）：当前正在显示的画面

绘制完成后，交换两个缓冲区的角色。这个过程叫“缓冲区交换”或“翻转”。

// 双缓冲初始化示例
#define HOR_RES 480
#define VER_RES 272
#define COLOR_DEPTH 2  // RGB565

static lv_color_t buf_1[HOR_RES * VER_RES];
static lv_color_t buf_2[HOR_RES * VER_RES];

lv_disp_draw_buf_t draw_buf;
lv_disp_draw_buf_init(&draw_buf, buf_1, buf_2, HOR_RES * VER_RES);

注意看 lv_disp_draw_buf_init 的第三个参数——传了两个缓冲区指针。LVGL 内部会自动管理这两个缓冲区的切换。

双缓冲的核心优势：LVGL 可以在后台缓冲区里随意绘制，不影响前台显示。绘制完成后，一次 flush_cb 调用就能把完整的一帧送到屏幕。撕裂？不存在的。

5. 三种缓冲模式的对比

LVGL 支持三种缓冲模式，我整理了一张表，方便大家对比：

模式	缓冲区数量	内存占用	性能	适用场景
单缓冲（全屏）	1 个全屏缓冲区	高	中等	内存充足，对撕裂不敏感
双缓冲（全屏）	2 个全屏缓冲区	很高	高	内存充足，要求无撕裂
分段缓冲	1 个部分缓冲区	低	较低	内存紧张，能接受性能折衷

你想想看，如果你的 MCU 只有 512 KB RAM，用双缓冲全屏 RGB565 就要吃掉 510 KB，剩下 2 KB 连个像样的 UI 都跑不起来。这时候就得用分段缓冲——只分配几行像素的缓冲区，LVGL 分多次渲染完整帧。

6. 整体流程：一张图说清楚

下面这张 SVG 图展示了从 LVGL 渲染到屏幕显示的全流程。我画的时候特意把关键路径标红了，大家重点关注。

7. 避坑指南：我踩过的那些雷

最后，分享几个我实际项目中遇到的坑，希望能帮大家省点时间：

缓冲区对齐问题：有些 LCD 控制器要求缓冲区地址 4 字节对齐。我遇到过用 malloc 分配缓冲区，地址没对齐，屏幕显示花屏。解决方案是用 lv_mem_alloc 或者自己实现对齐分配。
flush_cb 被频繁调用：如果 UI 上有大量小控件在不停变化，flush_cb 可能被每秒调用几十次。这时候要考虑合并脏矩形，或者降低刷新率。
中断与 DMA 的同步：如果用 DMA 传输像素数据，一定要处理好 DMA 完成中断和 flush_cb 的同步。我曾经在 DMA 还没传输完就调用了 lv_disp_flush_ready，结果画面出现残影。

我的调试小技巧：在 flush_cb 里加一个 GPIO 翻转，用示波器看这个 GPIO 的波形。波形密集程度直接反映了刷新频率，比任何软件打印都直观。

好了，显示驱动的核心内容就这些。说白了就是三件事：初始化配参数、回调搬数据、缓冲防撕裂。把这三点吃透了，LVGL 的显示驱动你就掌握了八成。剩下的两成，是在实际项目中慢慢积累的——每个 LCD 控制器都有自己的小脾气，遇到了再说。