ESP LV Present

[中文]

esp_lv_present is the LVGL 9 flush binding for esp_display_present. The application owns the esp_lcd panel and the presenter; this component only attaches an LVGL display to that presenter.

It is not a second display stack. display stays in esp_display_present; this name marks the LVGL side of that presenter.

Requirements

ESP-IDF >= 6.0
LVGL 9.x only (not LVGL 8)
An esp_display_presenter_t created by the application

Relationship

LVGL 9 widgets
      │
esp_lv_present           (this component, LVGL 9 only)
      │
esp_display_present      (buffers, TE, rotation, panel submit)
      │
esp_lcd panel

vs `esp_lvgl_adapter`

esp_lvgl_adapter is a full LVGL port (v8 and v9): display registration, worker task, lock, touch/encoder, and optional FS / decoder / FreeType. Use it when the UI does not go through esp_display_present.

esp_lv_present only installs the LVGL 9 flush path on an existing presenter. The start-task must pump lv_timer_handler(). Do not drive the same panel with both components at once.

Pair with the presenter

Initialize the panel (for example with hw_init).
Create a presenter (ESP_DISPLAY_PRESENT_MODE_AUTO is usually enough).
Call esp_lv_present_start() from the task that will pump LVGL.
Before handing the presenter to another producer: quiesce, then esp_lv_present_stop(). The presenter is not deleted.

dependencies:
  espressif/esp_lv_present: "^0.1.0"

#include "esp_lv_present.h"

lv_display_t *display = NULL;
ESP_ERROR_CHECK(esp_lv_present_start(presenter, &display));

More Details

See the component README:

Examples: examples/display/gui/lvgl_present_benchmark, examples/display/gui/gsp_lvgl_present_handoff. Test app: components/display/tools/esp_lv_present/test_apps.

API Reference

Header File

components/display/tools/esp_lv_present/include/esp_lv_present.h

Functions

esp_err_t esp_lv_present_start(esp_display_presenter_t *presenter, lv_display_t **ret_disp)

Create an LVGL display on presenter and install the flush path.

Rebinds the presenter producer to the calling task. Initializes LVGL and an esp_timer tick on the first successful call. Supports PARTITION, DIRECT, and FULL contracts.

Parameters

presenter – [in] Presenter already created by the application.
ret_disp – [out] Created LVGL display handle.

Returns

ESP_OK: Success
ESP_ERR_INVALID_ARG: presenter or ret_disp is NULL
ESP_ERR_INVALID_STATE: Binding already started
ESP_ERR_NOT_SUPPORTED: Unsupported contract, pixel format, or buffer layout
ESP_ERR_NO_MEM: Failed to create the LVGL display

esp_err_t esp_lv_present_stop(void)

Tear down the LVGL display bound by esp_lv_present_start().

Cancels any in-flight presenter frame first. The presenter itself is not deleted; borrowed draw buffers remain owned by the presenter.