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

using flush_fn = lv_display_flush_cb_t: Callback for lvgl to flush segments of pixel data from the pixel buffers to the display.

typedef void (*rotation_fn)(const DisplayRotation &rotation): Callback for lvgl event handler to reconfigure the display hardware.

Public Functions

inline explicit Display(const AllocatingConfig &config)

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

Parameters: config – Display configuration including buffer size and flush callback.

inline explicit Display(const NonAllocatingConfig &config)

Initialize LVGL then start the update task.

Parameters: config – Display configuration including pointers to display buffer memory, the pixel buffer size and flush callback.

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 pause(): Pause the display update task, to prevent LVGL from writing to the display.

inline void resume(): Resume the display update task, to allow LVGL to write to the display.

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 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 AllocatingConfig

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

Public Members

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

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

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

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

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

gpio_num_t backlight_pin: GPIO pin for the backlight.

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

Task::BaseConfig task_config {.name = "Display",.stack_size_bytes = 4096,.priority = 20,.core_id = 0}: Task configuration.

std::chrono::duration<float> update_period{0.01}: How frequently to run the update function.

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

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

bool software_rotation_enabled{true}: Enable LVGL software display rotation, incurs additional overhead.

Logger::Verbosity log_level = {Logger::Verbosity::WARN}: Verbosity for the Display logger_.

struct NonAllocatingConfig

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

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

Pixel *vram1: Pointer to display buffer 2 (if double buffered), that lvgl will use.

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

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

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

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

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

gpio_num_t backlight_pin: GPIO pin for the backlight.

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

Task::BaseConfig task_config {.name = "Display",.stack_size_bytes = 4096,.priority = 20,.core_id = 0}: Task configuration.

std::chrono::duration<float> update_period{0.01}: How frequently to run the update function.

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

bool software_rotation_enabled{true}: Enable LVGL software display rotation, incurs additional overhead.

Logger::Verbosity log_level = {Logger::Verbosity::WARN}: Verbosity for the Display logger_.