ESP LVGL ADAPTER

esp_lvgl_adapter 为 ESP-IDF 工程提供统一的 LVGL 适配层,涵盖显示注册、防撕裂策略、LVGL 线程安全访问,以及文件系统/图片解码/FreeType 字体的可选集成。兼容 LVGL v8 与 v9。

功能

统一的显示注册接口: 支持 MIPI DSI / RGB / QSPI / SPI / I2C / I80 等多种显示接口
防撕裂策略: 提供多种防撕裂模式
线程安全: 提供 lock/unlock API,保证多线程环境下的安全访问
可选模块 (通过 Kconfig 开关控制):
- 文件系统桥接 (esp_lv_fs)
- 图片解码 (esp_lv_decoder)
- FreeType 矢量字体
- FPS 统计、Dummy Draw(不实际输出到显示器)
多屏支持: 可同时管理多个显示设备

添加到工程

通过组件服务添加

idf.py add-dependency "espressif/esp_lvgl_adapter"

在 `idf_component.yml` 中声明

dependencies:
  espressif/esp_lvgl_adapter: "*"

系统要求

ESP-IDF: >= 5.5
LVGL: 8.x 或 9.x(自动适配版本)
可选依赖: 根据启用的功能需要满足相应的组件依赖

快速开始

以下是一个最小化的使用示例,展示如何初始化适配器并注册显示设备:

#include "esp_lv_adapter.h"  // 包含显示与输入适配接口

void app_main(void)
{
    // 步骤 0: 使用 esp_lcd API 创建面板和面板 IO(此处省略具体实现)
    esp_lcd_panel_handle_t panel = /* ... */;
    esp_lcd_panel_io_handle_t panel_io = /* ... 或 NULL */;

    // 步骤 1: 初始化适配器
    esp_lv_adapter_config_t cfg = ESP_LV_ADAPTER_DEFAULT_CONFIG();
    ESP_ERROR_CHECK(esp_lv_adapter_init(&cfg));

    // 步骤 2: 注册显示设备(根据接口类型选择相应的默认配置宏)
    esp_lv_adapter_display_config_t disp_cfg = ESP_LV_ADAPTER_DISPLAY_RGB_DEFAULT_CONFIG(
        panel,           // LCD 面板句柄
        panel_io,        // LCD 面板 IO 句柄(某些接口可为 NULL)
        800,             // 水平分辨率
        480,             // 垂直分辨率
        ESP_LV_ADAPTER_ROTATE_0 // 旋转角度
    );
    lv_display_t *disp = esp_lv_adapter_register_display(&disp_cfg);
    assert(disp != NULL);

    // 步骤 3: (可选) 注册输入设备
    // 使用 esp_lcd_touch API 创建触摸句柄(此处省略具体实现)
    // esp_lcd_touch_handle_t touch_handle = /* ... */;
    // esp_lv_adapter_touch_config_t touch_cfg = ESP_LV_ADAPTER_TOUCH_DEFAULT_CONFIG(disp, touch_handle);
    // lv_indev_t *touch = esp_lv_adapter_register_touch(&touch_cfg);
    // assert(touch != NULL);

    // 步骤 4: 启动适配器任务
    ESP_ERROR_CHECK(esp_lv_adapter_start());

    // 步骤 5: 使用 LVGL API 绘制界面(需要先加锁)
    if (esp_lv_adapter_lock(-1) == ESP_OK) {
        lv_obj_t *label = lv_label_create(lv_scr_act());
        lv_label_set_text(label, "Hello LVGL!");
        lv_obj_center(label);
        esp_lv_adapter_unlock();
    }
}

使用说明

决策流程

在开始使用前,请按以下流程做出决策:

选择接口类型: 确定使用的显示接口(MIPI DSI / RGB / QSPI / SPI / I2C / I80)
选择默认配置宏: 根据接口类型选择对应的 ESP_LV_ADAPTER_DISPLAY_XXX_DEFAULT_CONFIG 宏
选择合适的防撕裂模式 (仅 RGB/MIPI DSI 接口支持):
- 计算所需的帧缓冲数量 (num_fbs)
- 将 num_fbs 传入 esp_lcd 面板配置
调节缓冲大小: 根据内存与吞吐需求调整 buffer_height

显示注册与防撕裂

接口类型与默认配置宏

根据您的显示接口选择对应的配置宏:

接口类型	默认配置宏	默认防撕裂模式
MIPI DSI	`ESP_LV_ADAPTER_DISPLAY_MIPI_DEFAULT_CONFIG(...)`	`ESP_LV_ADAPTER_TEAR_AVOID_MODE_DEFAULT_MIPI_DSI`
RGB	`ESP_LV_ADAPTER_DISPLAY_RGB_DEFAULT_CONFIG(...)`	`ESP_LV_ADAPTER_TEAR_AVOID_MODE_DEFAULT_RGB`
SPI/I2C/I80/QSPI (带 PSRAM)	`ESP_LV_ADAPTER_DISPLAY_SPI_WITH_PSRAM_DEFAULT_CONFIG(...)`	`ESP_LV_ADAPTER_TEAR_AVOID_MODE_DEFAULT` (即 `NONE`)
SPI/I2C/I80/QSPI (无 PSRAM)	`ESP_LV_ADAPTER_DISPLAY_SPI_WITHOUT_PSRAM_DEFAULT_CONFIG(...)`	`ESP_LV_ADAPTER_TEAR_AVOID_MODE_DEFAULT` (即 `NONE`)

备注

仅 MIPI DSI 和 RGB 支持防撕裂模式
SPI/I2C/I80/QSPI 等接口在适配器中统称为 “OTHER” 接口,仅支持 NONE 模式

计算帧缓冲数量

在 RGB/MIPI DSI 初始化前,需要计算所需的帧缓冲数量:

uint8_t num_fbs = esp_lv_adapter_get_required_frame_buffer_count(
    ESP_LV_ADAPTER_TEAR_AVOID_MODE_DEFAULT_RGB,  // 防撕裂模式
    ESP_LV_ADAPTER_ROTATE_0                // 旋转角度
);
// 将 num_fbs 传入 esp_lcd 面板配置

帧缓冲数量规则:

90°/270° 旋转或三缓冲模式: 需要 3 个帧缓冲
双缓冲模式: 需要 2 个帧缓冲
单缓冲模式: 需要 1 个帧缓冲

防撕裂模式选择(RGB/MIPI DSI)

根据您的应用场景选择合适的防撕裂模式:

防撕裂模式	适用场景	帧缓冲数	内存占用
`TRIPLE_PARTIAL`	旋转(90°/270°), 高分辨率流畅 UI	3	高
`TRIPLE_FULL`	整屏/大区域刷新, 内存充足	3	高
`DOUBLE_FULL`	大区域刷新, 内存较紧	2	中
`DOUBLE_DIRECT`	小区域更新, 控件/局部变化	2	中
`NONE`	静态 UI, 超低内存	1	低

警告

RGB/MIPI DSI 在 TEAR_AVOID_MODE_NONE 下 不支持旋转 (任何非 0 旋转会被拒绝)
OTHER (SPI/I2C/I80/QSPI) 接口仅支持 NONE 模式; 如需旋转,请在 LCD 初始化阶段配置面板方向(交换 XY/镜像),并相应调整触摸坐标映射

内存估算

整帧显存大小 ≈ 水平分辨率 × 垂直分辨率 × 每像素字节数

示例 (RGB565 格式,2 字节/像素):

800×480 分辨率: ≈ 750 KB
三缓冲: ≈ 2.2 MB
结论: 通常需要 PSRAM 支持

缓冲调优

默认 `buffer_height` 值

不同接口的 buffer_height 默认值:

接口类型	默认 `buffer_height`	说明
MIPI DSI	50	中等条带高度
RGB	50	中等条带高度
OTHER + PSRAM	`ver_res` (整屏高度)	整屏高度分区,吞吐更高
OTHER 无 PSRAM	10	小条带以节省 RAM

调优建议

提高 buffer_height:
- ✅ 提升吞吐量(减少 flush 次数、增大条带)
- ❌ 增加 RAM 占用
降低 buffer_height:
- ✅ 节省 RAM
- ❌ 增加 flush 次数,可能降低性能

线程安全

LVGL API 不是线程安全的,多线程访问时必须使用适配器锁:

if (esp_lv_adapter_lock(-1) == ESP_OK) {
    lv_obj_t *btn = lv_btn_create(lv_scr_act());
    lv_obj_set_size(btn, 100, 50);
    esp_lv_adapter_unlock();
}

输入设备

触摸屏

适配器提供了触摸设备注册的默认配置宏 ESP_LV_ADAPTER_TOUCH_DEFAULT_CONFIG,简化配置过程:

// 使用默认配置宏注册触摸设备
esp_lv_adapter_touch_config_t touch_cfg = ESP_LV_ADAPTER_TOUCH_DEFAULT_CONFIG(disp, touch_handle);
lv_indev_t *touch = esp_lv_adapter_register_touch(&touch_cfg);
assert(touch != NULL);

参数说明:

disp: 关联的 LVGL 显示设备
touch_handle: 通过 esp_lcd_touch API 创建的触摸句柄
默认缩放比例: x = 1.0, y = 1.0

旋钮/编码器

需要启用 Kconfig 选项 ESP_LV_ADAPTER_ENABLE_KNOB。详见 esp_lv_adapter_input.h。

按键导航

需要启用 Kconfig 选项 ESP_LV_ADAPTER_ENABLE_BUTTON。详见 esp_lv_adapter_input.h。

文件系统桥接(可选)

启用 ESP_LV_ADAPTER_ENABLE_FS 后,可将 esp_mmap_assets 生成的资源分区挂载为 LVGL 文件系统:

#include "esp_lv_fs.h"
#include "esp_mmap_assets.h"

// 1. 创建 mmap 资源句柄
mmap_assets_handle_t assets;
const mmap_assets_config_t mmap_cfg = {
    .partition_label = "assets_A",
    .max_files = MMAP_DRIVE_A_FILES,
    .checksum  = MMAP_DRIVE_A_CHECKSUM,
    .flags = { .mmap_enable = true },
};
ESP_ERROR_CHECK(mmap_assets_new(&mmap_cfg, &assets));

// 2. 挂载为 LVGL 文件系统
esp_lv_fs_handle_t fs_handle;
const fs_cfg_t fs_cfg = {
    .fs_letter = 'A',           // 盘符(A 到 Z)
    .fs_assets = assets,
    .fs_nums = MMAP_DRIVE_A_FILES,
};
ESP_ERROR_CHECK(esp_lv_adapter_fs_mount(&fs_cfg, &fs_handle));

// 3. 在 LVGL 中使用文件路径,如 "A:image.png"
lv_obj_t *img = lv_img_create(lv_scr_act());
lv_img_set_src(img, "A:my_image.png");

依赖组件 esp_lv_fs 和 esp_mmap_assets 。

图片解码(可选)

启用 ESP_LV_ADAPTER_ENABLE_DECODER 后,适配器会集成 esp_lv_decoder,支持直接使用 LVGL 图片控件加载各种格式的图片:

// 使用 LVGL 图片控件加载图片
lv_obj_t *img = lv_img_create(lv_scr_act());
lv_img_set_src(img, "I:red_png.png");  // I: 为图片解码器的盘符

支持的格式:

标准格式: JPG、PNG、QOI
分片格式: SJPG、SPNG、SQOI(针对嵌入式优化)
硬件加速: JPEG、PJPG(如果芯片支持)

详细说明请参考 esp_lv_decoder 。

FreeType 字体(可选)

启用 ESP_LV_ADAPTER_ENABLE_FREETYPE 并在 LVGL 中开启 FreeType 后,可以从文件或内存加载矢量字体:

#include "esp_lv_adapter.h"

// 从文件加载字体
esp_lv_adapter_ft_font_handle_t fh;
esp_lv_adapter_ft_font_config_t cfg = {
    .name = "F:my_font.ttf",         // 字体文件路径(注意:mmap 资源格式,冒号后不带斜杠)
    .size = 30,                      // 字号
    .style = ESP_LV_ADAPTER_FT_FONT_STYLE_NORMAL,
};
ESP_ERROR_CHECK(esp_lv_adapter_ft_font_init(&cfg, &fh));
const lv_font_t *font30 = esp_lv_adapter_ft_font_get(fh);

// 使用字体
lv_obj_set_style_text_font(label, font30, 0);

堆栈配置:

LVGL 版本	必要配置	说明
v8	`CONFIG_ESP_MAIN_TASK_STACK_SIZE=32768`	字体初始化在调用线程执行
v9	`CONFIG_LV_DRAW_THREAD_STACK_SIZE=32768`	字体渲染在绘图线程执行

备注

LVGL v8: 不支持 LVGL 虚拟文件系统(lv_fs),需使用直接文件路径或内存缓冲区
LVGL v9: 支持虚拟文件系统路径(如 "F:font.ttf")

FPS 与 Dummy Draw

FPS 统计

需要启用 ESP_LV_ADAPTER_ENABLE_FPS_STATS。

// 启用 FPS 统计
ESP_ERROR_CHECK(esp_lv_adapter_fps_stats_enable(disp, true));

// 获取当前 FPS
uint32_t fps;
if (esp_lv_adapter_get_fps(disp, &fps) == ESP_OK) {
    printf("Current FPS: %lu\n", fps);
}

Dummy Draw

Dummy Draw 模式绕过 LVGL 渲染,直接控制显示:

ESP_ERROR_CHECK(esp_lv_adapter_set_dummy_draw(disp, true));
ESP_ERROR_CHECK(esp_lv_adapter_dummy_draw_blit(disp, 0, 0, 800, 480, framebuffer, true));
ESP_ERROR_CHECK(esp_lv_adapter_set_dummy_draw(disp, false));

立即刷新

强制进行同步刷新:

esp_lv_adapter_refresh_now(disp);

配置项 (Kconfig)

通过 idf.py menuconfig 可以配置以下选项:

配置项	说明
`ESP_LV_ADAPTER_ENABLE_FS`	启用文件系统桥接 (`esp_lv_fs`)
`ESP_LV_ADAPTER_ENABLE_DECODER`	启用图片解码 (`esp_lv_decoder`)
`ESP_LV_ADAPTER_ENABLE_FREETYPE`	启用 FreeType 矢量字体支持
`ESP_LV_ADAPTER_ENABLE_FPS_STATS`	启用 FPS 统计功能
`ESP_LV_ADAPTER_ENABLE_BUTTON`	启用按键导航输入
`ESP_LV_ADAPTER_ENABLE_KNOB`	启用旋钮/编码器输入

限制与注意事项

接口与防撕裂支持

接口类型	支持的防撕裂模式
RGB / MIPI DSI	`NONE`, `DOUBLE_FULL`, `TRIPLE_FULL`, `DOUBLE_DIRECT`, `TRIPLE_PARTIAL`
OTHER (SPI/I2C/I80/QSPI)	仅 `NONE`

旋转限制

RGB/MIPI DSI:
- 在 TEAR_AVOID_MODE_NONE 下 不支持旋转 (任何非 0 旋转会被拒绝)
OTHER (SPI/I2C/I80/QSPI):
- 适配器不对 90°/270° 进行旋转处理
- 如需旋转,请在 LCD 初始化阶段配置面板方向(交换 XY/镜像)
- 同时需要相应调整触摸坐标映射

缓冲与渲染模式

模式映射:
- DOUBLE_FULL / TRIPLE_FULL → FULL 渲染模式
- DOUBLE_DIRECT → DIRECT 渲染模式
- 其余(含 TRIPLE_PARTIAL) → PARTIAL 渲染模式
LVGL 绘制缓冲数量:
- TRIPLE_PARTIAL: 1 块
- TRIPLE_FULL / DOUBLE_*: 2 块
- FULL/DIRECT 模式默认: 2 块
- 其他: 1 块
OTHER + NONE:
- 不申请面板帧缓冲
- 仅使用 LVGL 绘制缓冲的条带方式发送数据

PPA/DMA2D 加速

启用 PPA 加速时,建议设置 LV_DRAW_SW_DRAW_UNIT_CNT == 1
旋转操作优先使用 PPA; 否则使用 CPU 拷贝路径(带缓存局部性的块拷贝)
效果与预期:
- PPA 可显著降低 CPU 占用
- 通常不会带来明显的 FPS 提升

反初始化

关闭 UI 时的推荐资源释放顺序:

// 1. 注销输入设备
esp_lv_adapter_unregister_touch(touch);
// esp_lv_adapter_unregister_encoder(encoder);
// esp_lv_adapter_unregister_navigation_buttons(buttons);

// 2. 注销显示设备
esp_lv_adapter_unregister_display(disp);

// 3. 卸载文件系统(如果使用)
esp_lv_adapter_fs_unmount(fs_handle);
// 释放 mmap 资源
mmap_assets_del(assets);

// 4. 反初始化适配器
// 注意:如果启用了 FreeType,字体资源会自动清理
esp_lv_adapter_deinit();

兼容性

ESP-IDF: >= 5.5
LVGL: >= 8, < 10(支持 v8 和 v9)

ESP-IDF 补丁说明

PPA 卡死问题修复(ESP32-P4)

如果您在 ESP32-P4 上使用 ESP_LV_ADAPTER_TEAR_AVOID_MODE_TRIPLE_PARTIAL 模式并启用屏幕旋转时遇到画面卡死问题,需要应用以下补丁:

适用版本: ESP-IDF release/v5.5 (commit 62beeae461bd3692c2028f96a93c84f11291e155)

补丁文件: 0001-bugfix-lcd-Fixed-PPA-freeze.patch

应用方法:

在 ESP-IDF 仓库根目录下执行:

cd $IDF_PATH
git apply /path/to/esp_lvgl_adapter/0001-bugfix-lcd-Fixed-PPA-freeze.patch

问题说明:

该补丁修复了 ESP32-P4 在 ESP_LV_ADAPTER_TEAR_AVOID_MODE_TRIPLE_PARTIAL 模式下使能旋转时,PPA 硬件加速导致画面卡死的问题
仅影响同时满足以下条件的场景:
- 使用 ESP32-P4 芯片
- 使用 TRIPLE_PARTIAL 防撕裂模式
- 启用了屏幕旋转(90°/270°)
其他配置组合或芯片不需要此补丁

验证补丁是否已应用:

检查 components/esp_driver_ppa/src/ppa_srm.c 文件中是否包含以下代码:

PPA.sr_byte_order.sr_macro_bk_ro_bypass = 1;

术语表

术语	说明
面板帧缓冲	由显示面板驱动持有的硬件帧缓冲区
LVGL 绘制缓冲	LVGL 用于渲染条带或整帧后再刷新到面板的 RAM 区域
分区刷新	仅更新屏幕的部分区域(脏区域)而非整屏刷新
直写(Direct)	LVGL 直接渲染到面板帧缓冲,减少内存拷贝; 适合小区域刷新
PPA	Pixel Processing Accelerator(像素处理加速器),用于硬件加速旋转/缩放/内存拷贝等操作
防撕裂	通过多缓冲等技术避免屏幕更新时出现撕裂现象

应用示例

示例	说明
`lvgl_common_demo`	统一的 LVGL 演示,支持多种接口
`lvgl_multi_screen`	多显示器管理示例
`lvgl_decode_image`	图片解码功能演示
`lvgl_freetype_font`	FreeType 字体加载与使用
`lvgl_dummy_draw`	Dummy Draw 切换

常见问题

FreeType 崩溃或显示异常

解决方法:

确认 LVGL 配置中已启用 FreeType(CONFIG_LV_USE_FREETYPE=y)
LVGL v8: 设置 CONFIG_ESP_MAIN_TASK_STACK_SIZE=32768
LVGL v9: 设置 CONFIG_LV_DRAW_THREAD_STACK_SIZE=32768

屏幕撕裂或闪烁

可能原因:

防撕裂模式选择不当
帧缓冲数量不正确
旋转配置不当

解决方法:

根据应用场景选择合适的防撕裂模式
使用 esp_lv_adapter_get_required_frame_buffer_count() 计算正确的帧缓冲数

图片解码或文件系统不可用

可能原因:

Kconfig 选项未启用
组件依赖缺失
资源分区未正确烧录

解决方法:

检查相应的 Kconfig 开关
确认 esp_mmap_assets 等依赖组件已添加
验证资源分区是否正确打包并烧录到 Flash

LVGL API 调用崩溃

可能原因:

在多线程环境中未加锁访问 LVGL API

解决方法:

// 所有 LVGL API 调用都必须加锁保护
if (esp_lv_adapter_lock(-1) == ESP_OK) {
    // LVGL API 调用
    esp_lv_adapter_unlock();
}

API 参考

Header File

components/display/tools/esp_lvgl_adapter/include/esp_lv_adapter.h

Functions

esp_err_t esp_lv_adapter_init(const esp_lv_adapter_config_t *config)

Initialize the LVGL adapter.

This function initializes the LVGL library and creates necessary resources. Must be called before any other LVGL adapter functions.

参数

config – [in] Pointer to LVGL adapter configuration

返回

ESP_OK: Success
ESP_ERR_INVALID_STATE: Adapter already initialized
ESP_ERR_INVALID_ARG: Invalid configuration parameter
ESP_ERR_NO_MEM: Memory allocation failed

esp_err_t esp_lv_adapter_start(void)

Start the LVGL adapter task.

Creates and starts the LVGL task for handling timer events.

返回

ESP_OK: Success
ESP_ERR_INVALID_STATE: Adapter not initialized
ESP_ERR_NO_MEM: Task creation failed

esp_err_t esp_lv_adapter_deinit(void)

Deinitialize the LVGL adapter.

Stops the LVGL task and releases all resources.

返回

ESP_OK: Success

bool esp_lv_adapter_is_initialized(void)

Check if the LVGL adapter is initialized.

返回

true: Adapter is initialized
false: Adapter is not initialized

esp_err_t esp_lv_adapter_lock(int32_t timeout_ms)

Acquire the LVGL adapter lock.

Must be called before accessing LVGL objects from user code.

参数

timeout_ms – [in] Timeout in milliseconds, use -1 for infinite wait

返回

ESP_OK: Lock acquired successfully
ESP_ERR_INVALID_STATE: Adapter not initialized
ESP_ERR_TIMEOUT: Failed to acquire lock within timeout

void esp_lv_adapter_unlock(void): Release the LVGL adapter lock.

esp_err_t esp_lv_adapter_refresh_now(lv_display_t *disp)

Force LVGL to refresh the display immediately.

This function triggers an immediate refresh of the LVGL display, forcing all dirty areas to be redrawn without waiting for the next timer period. Useful when you need to update the display synchronously.

参数

disp – [in] Pointer to LVGL display object (NULL for default display)

返回

ESP_OK: Success
ESP_ERR_INVALID_STATE: Adapter not initialized

esp_err_t esp_lv_adapter_set_dummy_draw(lv_display_t *disp, bool enable)

Enable or disable dummy draw mode for a display.

In dummy draw mode, LVGL rendering is bypassed and the application takes direct control of the display. Use esp_lv_adapter_dummy_draw_blit() to update the screen.

备注

Manages locking internally. Disabling triggers a full screen refresh.

参数

disp – [in] Pointer to LVGL display object
enable – [in] true to enable dummy draw, false to disable

返回

ESP_OK: Success
ESP_ERR_INVALID_STATE: Adapter not initialized
ESP_ERR_INVALID_ARG: Invalid display pointer

bool esp_lv_adapter_get_dummy_draw_enabled(lv_display_t *disp)

Get the current dummy draw mode state for a display.

This function retrieves whether dummy draw mode is currently enabled. In dummy draw mode, LVGL rendering is bypassed and the application has direct control over the framebuffer.

参数

disp – [in] Pointer to LVGL display object

返回

true: Dummy draw mode is enabled
false: Dummy draw mode is disabled (or adapter not initialized/invalid display)

esp_err_t esp_lv_adapter_set_dummy_draw_callbacks(lv_display_t *disp, const esp_lv_adapter_dummy_draw_callbacks_t *cbs, void *user_ctx)

Register dummy draw callbacks for a display.

Callbacks allow applications to hook into dummy draw transitions and VSYNC notifications (useful for self-refresh flows). Registering new callbacks replaces any previously registered ones. Pass NULL to remove callbacks.

参数

disp – Display handle
cbs – Pointer to callback collection (NULL to clear)
user_ctx – User context pointer passed back to callbacks

返回

ESP_OK: Success
ESP_ERR_INVALID_STATE: Adapter not initialized
ESP_ERR_INVALID_ARG: Invalid display handle

esp_err_t esp_lv_adapter_dummy_draw_blit(lv_display_t *disp, int x_start, int y_start, int x_end, int y_end, const void *frame_buffer, bool wait)

Blit a framebuffer region to display in dummy draw mode.

Directly sends framebuffer to display hardware, bypassing LVGL.

参数

disp – [in] Pointer to LVGL display object
x_start – [in] Starting X coordinate (inclusive)
y_start – [in] Starting Y coordinate (inclusive)
x_end – [in] Ending X coordinate (exclusive)
y_end – [in] Ending Y coordinate (exclusive)
frame_buffer – [in] Pointer to framebuffer data
wait – [in] true to wait for completion, false to return immediately

返回

ESP_OK: Success
ESP_ERR_INVALID_STATE: Adapter not initialized or dummy draw not enabled
ESP_ERR_INVALID_ARG: Invalid parameters

Structures

struct esp_lv_adapter_config_t

LVGL adapter configuration structure.

Public Members

uint32_t task_stack_size: LVGL task stack size in bytes

uint32_t task_priority: LVGL task priority

int task_core_id: LVGL task core ID (-1 for no affinity)

uint32_t tick_period_ms: LVGL tick period in milliseconds

uint32_t task_min_delay_ms: Minimum LVGL task delay in milliseconds

uint32_t task_max_delay_ms: Maximum LVGL task delay in milliseconds

bool stack_in_psram: Allocate LVGL task stack in PSRAM when available

struct esp_lv_adapter_dummy_draw_callbacks_t

Dummy draw callback collection.

All callbacks are optional; set any member to NULL to omit it.

备注

The on_vsync callback is executed in interrupt context on most panels, so implementations must be ISR-safe.

Public Members

void (*on_enable)(lv_display_t *disp, void *user_ctx): Called when dummy draw mode is enabled

void (*on_disable)(lv_display_t *disp, void *user_ctx): Called when dummy draw mode is disabled

void (*on_color_trans_done)(lv_display_t *disp, bool in_isr, void *user_ctx): Called when color transfer is done

void (*on_vsync)(lv_display_t *disp, bool in_isr, void *user_ctx): Called on VSYNC signal (ISR context)

Macros

ESP_LV_ADAPTER_DEFAULT_STACK_SIZE

Default configuration values for LVGL adapter.

Default task stack size (8KB)

ESP_LV_ADAPTER_DEFAULT_TASK_PRIORITY: Default task priority

ESP_LV_ADAPTER_DEFAULT_TASK_CORE_ID: Default task core ID (-1 for no affinity)

ESP_LV_ADAPTER_DEFAULT_TICK_PERIOD_MS: Default tick period in milliseconds

ESP_LV_ADAPTER_DEFAULT_TASK_MIN_DELAY_MS: Default minimum task delay in milliseconds

ESP_LV_ADAPTER_DEFAULT_TASK_MAX_DELAY_MS: Default maximum task delay in milliseconds

ESP_LV_ADAPTER_DEFAULT_CONFIG(): Default configuration for LVGL adapter.

提供有关此文档的反馈

ESP LVGL ADAPTER

功能

添加到工程

通过组件服务添加

在 idf_component.yml 中声明

系统要求

快速开始

使用说明

推荐的 SDKCONFIG 配置

核心 LVGL 配置

多核优化(ESP32-S3/P4)

PSRAM 优化(如果可用)

决策流程

显示注册与防撕裂

接口类型与默认配置宏

计算帧缓冲数量

防撕裂模式选择(RGB/MIPI DSI)

内存估算

缓冲调优

默认 buffer_height 值

调优建议

线程安全

输入设备

触摸屏

旋钮/编码器

按键导航

文件系统桥接(可选)

图片解码(可选)

FreeType 字体(可选)

FPS 与 Dummy Draw

FPS 统计

Dummy Draw

立即刷新

配置项 (Kconfig)

限制与注意事项

接口与防撕裂支持

旋转限制

缓冲与渲染模式

PPA/DMA2D 加速

反初始化

兼容性

ESP-IDF 补丁说明

PPA 卡死问题修复(ESP32-P4)

术语表

应用示例

常见问题

FreeType 崩溃或显示异常

屏幕撕裂或闪烁

图片解码或文件系统不可用

LVGL API 调用崩溃

API 参考

Header File

Functions

Structures

Macros

在 `idf_component.yml` 中声明

默认 `buffer_height` 值