Display

The display component is responsible for managing the memory associated the display buffer / video RAM (vram) and is also responsible for managing the high-priority lvgl update task which sends data to the display.

API Reference

Header File

components/display/include/display.hpp

Classes

template<typename Pixel> class Display : public espp::BaseComponent 

Wrapper class around LVGL display buffer and display driver.

Optionally allocates and owns the memory associated with the pixel display buffers. Initializes the LVGL subsystem then starts and maintains a task which runs the high priority lv_tick_inc() function every update period (default = 10 ms).

For more information, see https://docs.lvgl.io/9.1/porting/display.html#display-interface

Template Parameters: Pixel – The pixel format to be used for the display. This allows the class to be used with displays of different color depths and formats.

Public Types

typedef std::function<void(lv_display_t *disp, const lv_area_t *area, uint8_t *color_map)> flush_fn

Callback for lvgl to flush segments of pixel data from the pixel buffers to the display.

Param disp: The display to flush data to.
Param area: The area of the display to flush data to.
Param color_map: The color data to flush to the display.

typedef std::function<void(const DisplayRotation &rotation)> rotation_fn

Callback for lvgl event handler to reconfigure the display hardware.

Param rotation: The new rotation setting for the display.

typedef std::function<void(float brightness)> set_brightness_fn

Callback for setting the display brightness.

Param brightness: Brightness value between 0.0 and 1.0.

typedef std::function<float()> get_brightness_fn

Callback for getting the display brightness.

Return: float Brightness value between 0.0 and 1.0.

Public Functions

inline explicit Display(const LvglConfig &lvgl_conf, const LcdConfig &lcd_config, const StaticMemoryConfig &mem_conf, const Logger::Verbosity log_level = Logger::Verbosity::WARN)

Initialize LVGL then start the update task.

Parameters

lvgl_conf – LVGL Configuration, including display size, flush callback and optional rotation callback.
lcd_config – LCD specific configuration.
mem_conf – Static memory configuration.
log_level – The verbosity level for the Display logger_.

inline explicit Display(const LvglConfig &lvgl_conf, const LcdConfig &lcd_config, const DynamicMemoryConfig &mem_conf, const Logger::Verbosity log_level = Logger::Verbosity::WARN)

Allocate the display buffers, initialize LVGL then start the update task.

Parameters

lvgl_conf – LVGL Configuration, including display size, flush callback and optional rotation callback.
lcd_config – LCD specific configuration.
mem_conf – Dynamic memory configuration.
log_level – The verbosity level for the Display logger_.

inline explicit Display(const LvglConfig &lvgl_conf, const OledConfig &oled_config, const StaticMemoryConfig &mem_conf, const Logger::Verbosity log_level = Logger::Verbosity::WARN)

Initialize LVGL then start the update task.

Parameters

lvgl_conf – LVGL Configuration, including display size, flush callback and optional rotation callback.
oled_config – OLED specific configuration.
mem_conf – Static memory configuration.
log_level – The verbosity level for the Display logger_.

inline explicit Display(const LvglConfig &lvgl_conf, const OledConfig &oled_config, const DynamicMemoryConfig &mem_conf, const Logger::Verbosity log_level = Logger::Verbosity::WARN)

Allocate the display buffers, initialize LVGL then start the update task.

Parameters

lvgl_conf – LVGL Configuration, including display size, flush callback and optional rotation callback.
oled_config – OLED specific configuration.
mem_conf – Dynamic memory configuration.
log_level – The verbosity level for the Display logger_.

inline ~Display(): Stops the upate task and frees the display buffer memory.

inline size_t width() const

Return the configured width of the display in pixels.

Returns: size_t width of the display.

inline size_t height() const

Return the configured height of the display in pixels.

Returns: size_t height of the display.

inline void set_brightness(float brightness)

Set the brightness of the display.

Parameters: brightness – Brightness value between 0.0 and 1.0.

inline float get_brightness() const

Get the brightness of the display.

Returns: float Brightness value between 0.0 and 1.0.

inline void force_refresh() const: Force a redraw / refresh of the display.

Note

This is mainly useful after you have called pause() on the display (to draw to it with something other than LVGL) and want to switch back to the LVGL gui. Normally you should not call this function.

inline Pixel *vram0()

Get pointer to main display buffer for custom writing.

Returns: uint16_t* Pointer to the main display buffer.

inline Pixel *vram1()

Get pointer to secondary display buffer for custom writing.

Returns: uint16_t* Pointer to the secondary display buffer.

inline size_t vram_size_px() const

Return the number of pixels that vram() can hold.

Returns: size_t Number of pixels that fit in the display buffer.

inline size_t vram_size_bytes() const

Return the number of bytes that vram() can hold.

Returns: size_t Number of bytes that fit in the display buffer.

inline void set_rotation(DisplayRotation rotation)

Set the rotation of the display.

Note

This function is called by the event handler when the display resolution changes, so that the display hardware can be reconfigured to match the new software rotation setting.

Parameters: rotation – The new rotation setting for the display.

inline void flush(lv_display_t *disp, const lv_area_t *area, uint8_t *color_map)

Flush the data to the display.

Warning

This function is called by the LVGL flush callback, so it is recommended to not call this function directly.

Parameters

disp – The display to flush data to.
area – The area of the display to flush data to.
color_map – The color data to flush to the display.

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns: A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters: tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns: The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters: level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters: level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns: The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters: rate_limit – The rate limit to use for the logger

struct DynamicMemoryConfig

Used if you want the Display to manage the allocation / lifecycle of the display buffer memory itself.

Public Members

size_t pixel_buffer_size: Size of the display buffer in pixels.

bool double_buffered{true}: Whether to use double buffered rendering (two display buffers) or not.

uint32_t allocation_flags{MALLOC_CAP_8BIT | MALLOC_CAP_DMA}: For configuring how the display buffer is allocated

struct LcdConfig

LCD specific configuration.

Public Members

gpio_num_t backlight_pin = {GPIO_NUM_NC}: GPIO pin for the backlight.

bool backlight_on_value{true}: Value to write to the backlight pin to turn the backlight on.

struct LvglConfig

Base component configuration for LVGL.

Public Members

size_t width: Width of th display, in pixels.

size_t height: Height of the display, in pixels.

flush_fn flush_callback: Function provided to LVGL for it to flush data to the display.

rotation_fn rotation_callback{nullptr}: Optional function used to configure display with new rotation setting.

DisplayRotation rotation = {DisplayRotation::LANDSCAPE}: Default / Initial rotation of the display.

struct OledConfig

OLED specific configuration.

Public Members

set_brightness_fn set_brightness_callback{nullptr}: Callback for setting the display brightness

get_brightness_fn get_brightness_callback = {nullptr}: Callback for getting the display brightness.

struct StaticMemoryConfig

Used if you want to manage allocation / lifecycle of the display buffer memory separately from this class. This structure allows you to configure the Display with up to two display buffers.

Public Members

size_t pixel_buffer_size: Size of the display buffer in pixels.

Pixel *vram0 = {nullptr}: Pointer to display buffer 1, that lvgl will use.

Pixel *vram1 = {nullptr}: Optional pointer to display buffer 2 (if double buffered), that lvgl will use.