GUI Frameworks

Driving a display is only the first step. You also need a graphics library to draw an interface. Graphics libraries are largely independent of the display controller: they only need a driver function that can write a block of pixel data to the panel. The display type does, however, affect which libraries are practical. Monochrome, full-color, and e-paper displays each have different requirements. This page compares the graphics libraries commonly used with ESP32 boards and explains when to use each one.

1. Graphics Software Layers

Most graphics stacks can be divided into three layers:

1. Widget and application layer: Ready-made buttons, labels, charts, layouts, animations, and event handling. Only a complete GUI framework such as LVGL provides this layer.
2. Rendering engine: Draws pixels, lines, rectangles, text, and bitmaps while managing an in-memory draw buffer. This is the core of every graphics library.
3. Hardware abstraction layer (HAL): Connects the graphics software to the display and input hardware through display-flush and input-reading functions.

The preceding pages demonstrate two forms of this architecture:

• Graphics libraries such as Arduino_GFX and u8g2 include drivers for common display controllers. Select the appropriate constructor and use the drawing API directly.
• GUI frameworks such as LVGL do not include hardware drivers. Register a display-flush function, usually implemented with Arduino_GFX or esp_lcd, and a touch-reading function as described in Touch Input. See Section 12 of the Arduino tutorial for the complete LVGL architecture.

2. Graphics Library Comparison

Library	Role	Target displays	Widgets	Input / touch	Memory use
LVGL	Complete GUI framework	Primarily full-color; monochrome is possible	Extensive: buttons, lists, charts, animations	Provides an input-event framework; adapt the touch controller separately	Medium to high: draw buffer plus framework overhead
u8g2	Monochrome graphics library	OLED, RLCD, monochrome LCD	None	None	Low: 1-bpp buffer
Arduino_GFX	Full-color graphics library	SPI, QSPI, I80, and RGB displays	None	None	Low; direct rendering without a framebuffer is supported
LovyanGFX	Full-color graphics library	SPI, I80, and RGB displays	None	Integrates several common touch controllers	Low to medium
TFT_eSPI	Full-color graphics library	SPI displays; parallel interfaces on selected platforms	None	Built-in XPT2046 support	Low to medium
GxEPD2	E-paper driver library	SPI e-paper panels	None	None	Low to medium; can buffer a limited number of rows, with higher requirements for multicolor panels

Keep the following points in mind:

• Drawing APIs are similar across graphics libraries. Arduino_GFX, LovyanGFX, and TFT_eSPI use familiar calls such as fillScreen, drawRect, and setCursor. Once you know one library, the others are easier to learn.
• This tutorial uses Arduino_GFX for full-color examples. It supports a broad range of buses and display controllers, and many Waveshare development-board examples already use it.
• LVGL does not operate on its own. It renders widgets and interfaces, while a registered callback transfers the resulting pixel data with a graphics library or esp_lcd.
• LVGL v8 and v9 contain incompatible API changes. Use the version provided with the development board's examples, and do not mix major versions. Code exported by tools such as SquareLine Studio must target the same LVGL major version as the project.

3. Choosing a Library

Choose a library based on the display type and interface requirements:

1. Monochrome OLED or RLCD → u8g2. Its 1-bpp buffer matches the panel's native format, it includes an extensive font collection, and it uses little memory. See the OLED and RLCD examples.
2. E-paper → the Waveshare driver library or GxEPD2. Full and partial refresh operations require an e-paper-specific driver. See E-paper. LVGL can technically be ported to e-paper, but its interaction model does not align well with refresh times measured in seconds, so it is rarely a practical choice.
3. Full-color display with readouts or status pages but no complex interaction → draw directly with Arduino_GFX. This avoids the overhead of a GUI framework. See the LCD example.
4. Full-color interactive interface with buttons, lists, animation, or touch → LVGL. Its widget and event systems replace a large amount of application-specific UI code. Tools such as SquareLine Studio provide a visual interface designer. LVGL requires an additional draw buffer, although it does not have to cover the entire screen. For a high-resolution display, verify the available PSRAM using the calculation in AMOLED.

If you are still unsure, begin with Arduino_GFX for a full-color display or u8g2 for a monochrome display. You can add LVGL later without discarding the underlying display-driver code.

4. Further Reading

• Arduino Tutorial Section 12: Developing an LVGL Graphical Interface: LVGL architecture, porting, and the complete development workflow.
• OLED: u8g2 constructors, buffer modes, and a working example.
• Waveshare development-board product pages: The official example package for a board with a display usually includes both graphics-library and LVGL examples and is the best hardware-specific starting point.