Display interface¶

To set up a display an lv_disp_buf_t and an lv_disp_drv_t variable has to be initialized.

lv_disp_buf_t contains internal graphics buffer(s).
lv_disp_drv_t contains callback functions to interact with the display and manipulate drawing related things.

Display buffer¶

lv_disp_buf_t can be initialized like this:

    /*A static or global variable to store the buffers*/
    static lv_disp_buf_t disp_buf;

    /*Static or global buffer(s). The second buffer is optional*/
    static lv_color_t buf_1[MY_DISP_HOR_RES * 10];
    static lv_color_t buf_2[MY_DISP_HOR_RES * 10];

    /*Initialize `disp_buf` with the buffer(s) */
    lv_disp_buf_init(&disp_buf, buf_1, buf_2, MY_DISP_HOR_RES*10);

There are 3 possible configurations regarding the buffer size:

One buffer LittlevGL draws the content of the screen into a buffer and sends it to the display. The buffer can be smaller than the screen. In this case, the larger areas will be redrawn in multiple parts. If only small areas changes (e.g. button press) then only those areas will be refreshed.
Two non-screen-sized buffers having two buffers LittlevGL can draw into one buffer while the content of the other buffer is sent to display in the background. DMA or other hardware should be used to transfer the data to the display to let the CPU draw meanwhile. This way the rendering and refreshing of the display become parallel. Similarly to the One buffer, LittlevGL will draw the display’s content in chunks if the buffer is smaller than the area to refresh.
Two screen-sized buffers. In contrast to Two non-screen-sized buffers LittlevGL will always provide the whole screen’s content not only chunks. This way the driver can simply change the address of the frame buffer to the buffer received from LittlevGL. Therefore this method works the best when the MCU has an LCD/TFT interface and the frame buffer is just a location in the RAM.

Display driver¶

Once the buffer initialization is ready the display drivers need to be initialized. In the most simple case only the following two fields of lv_disp_drv_t needs to be set:

buffer pointer to an initialized lv_disp_buf_t variable.
flush_cb a callback function to copy a buffer’s content to a specific area of the display.

There are some optional data fields:

hor_res horizontal resolution of the display. (LV_HOR_RES_MAX by default from lv_conf.h).
ver_res vertical resolution of the display. (LV_VER_RES_MAX by default from lv_conf.h).
color_chroma_key a color which will be drawn as transparent on chrome keyed images. LV_COLOR_TRANSP by default from lv_conf.h).
user_data custom user data for the driver. Its type can be modified in lv_conf.h.
anti-aliasing use anti-aliasing (edge smoothing). LV_ANTIALIAS by default from lv_conf.h.
rotated if 1 swap hor_res and ver_res. LittlevGL draws in the same direction in both cases (in lines from top to bottom) so the driver also needs to be reconfigured to change the display’s fill direction.
screen_transp if 1 the screen can have transparent or opaque style. LV_COLOR_SCREEN_TRANSP needs to enabled in lv_conf.h.

To use a GPU the following callbacks can be used:

gpu_fill_cb fill an area in memory with colors.
gpu_blend_cb blend two memory buffers using opacity.

Note that, these functions need to draw to the memory (RAM) and not your display directly.

Some other optional callbacks to make easier and more optimal to work with monochrome, grayscale or other non-standard RGB displays:

rounder_cb round the coordinates of areas to redraw. E.g. a 2x2 px can be converted to 2x8. It can be used if the display controller can refresh only areas with specific height or width (usually 8 px height with monochrome displays).
set_px_cb a custom function to write the display buffer. It can be used to store the pixels more compactly if the display has a special color format. (e.g. 1-bit monochrome, 2-bit grayscale etc.) This way the buffers used in lv_disp_buf_t can be smaller to hold only the required number of bits for the given area size. set_px_cb is not working with Two screen-sized buffers display buffer configuration.
monitor_cb a callback function tells how many pixels were refreshed in how much time.

To set the fields of lv_disp_drv_t variable it needs to be initialized with lv_disp_drv_init(&disp_drv). And finally to register a display for LittlevGL lv_disp_drv_register(&disp_drv) needs to be called.

All together it looks like this:

    lv_disp_drv_t disp_drv;                 /*A variable to hold the drivers. Can be local variable*/
    lv_disp_drv_init(&disp_drv);            /*Basic initialization*/
    disp_drv.buffer = &disp_buf;            /*Set an initialized buffer*/
    disp_drv.flush_cb = my_flush_cb;        /*Set a flush callback to draw to the display*/
    lv_disp_t * disp;
    disp = lv_disp_drv_register(&disp_drv); /*Register the driver and save the created display objects*/

Here some simple examples of the callbacks:

void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p)
{
    /*The most simple case (but also the slowest) to put all pixels to the screen one-by-one*/
    int32_t x, y;
    for(y = area->y1; y <= area->y2; y++) {
        for(x = area->x1; x <= area->x2; x++) {
            put_px(x, y, *color_p)
            color_p++;
        }
    }

    /* IMPORTANT!!!
     * Inform the graphics library that you are ready with the flushing*/
    lv_disp_flush_ready(disp);
}

void my_gpu_fill_cb(lv_disp_drv_t * disp_drv, lv_color_t * dest_buf, const lv_area_t * dest_area, const lv_area_t * fill_area, lv_color_t color);
{
    /*It's an example code which should be done by your GPU*/
    uint32_t x, y;
    dest_buf += dest_width * fill_area->y1; /*Go to the first line*/

    for(y = fill_area->y1; y < fill_area->y2; y++) {
        for(x = fill_area->x1; x < fill_area->x2; x++) {
            dest_buf[x] = color;
        }
        dest_buf+=dest_width;    /*Go to the next line*/
    }
}

void my_gpu_blend_cb(lv_disp_drv_t * disp_drv, lv_color_t * dest, const lv_color_t * src, uint32_t length, lv_opa_t opa)
{
    /*It's an example code which should be done by your GPU*/
    uint32_t i;
    for(i = 0; i < length; i++) {
        dest[i] = lv_color_mix(dest[i], src[i], opa);
    }
}

void my_rounder_cb(lv_disp_drv_t * disp_drv, lv_area_t * area)
{
  /* Update the areas as needed. Can be only larger.
   * For example to always have lines 8 px height:*/
   area->y1 = area->y1 & 0x07;
   area->y2 = (area->y2 & 0x07) + 8;
}

void my_set_px_cb(lv_disp_drv_t * disp_drv, uint8_t * buf, lv_coord_t buf_w, lv_coord_t x, lv_coord_t y, lv_color_t color, lv_opa_t opa)
{
    /* Write to the buffer as required for the display.
     * Write only 1-bit for monochrome displays mapped vertically:*/
 buf += buf_w * (y >> 3) + x;
 if(lv_color_brightness(color) > 128) (*buf) |= (1 << (y % 8));
 else (*buf) &= ~(1 << (y % 8));
}

void my_monitor_cb(lv_disp_drv_t * disp_drv, uint32_t time, uint32_t px)
{
  printf("%d px refreshed in %d ms\n", time, ms);
}

API¶

Display Driver HAL interface header file

Typedefs

typedef struct _disp_drv_t lv_disp_drv_t¶: Display Driver structure to be registered by HAL

typedef struct _disp_t lv_disp_t¶: Display structure. lv_disp_drv_t is the first member of the structure.

Functions

void lv_disp_drv_init(lv_disp_drv_t *driver)¶

Initialize a display driver with default values. It is used to have known values in the fields and not junk in memory. After it you can safely set only the fields you need.

Parameters

driver: pointer to driver variable to initialize

void lv_disp_buf_init(lv_disp_buf_t *disp_buf, void *buf1, void *buf2, uint32_t size_in_px_cnt)¶

Initialize a display buffer

Parameters

disp_buf: pointer lv_disp_buf_t variable to initialize
buf1: A buffer to be used by LittlevGL to draw the image. Always has to specified and can’t be NULL. Can be an array allocated by the user. E.g. static lv_color_t disp_buf1[1024 * 10] Or a memory address e.g. in external SRAM
buf2: Optionally specify a second buffer to make image rendering and image flushing (sending to the display) parallel. In the disp_drv->flush you should use DMA or similar hardware to send the image to the display in the background. It lets LittlevGL to render next frame into the other buffer while previous is being sent. Set to NULL if unused.
size_in_px_cnt: size of the buf1 and buf2 in pixel count.

lv_disp_t *lv_disp_drv_register(lv_disp_drv_t *driver)¶

Register an initialized display driver. Automatically set the first display as active.

Return

pointer to the new display or NULL on error

Parameters

driver: pointer to an initialized ‘lv_disp_drv_t’ variable (can be local variable)

void lv_disp_drv_update(lv_disp_t *disp, lv_disp_drv_t *new_drv)¶

Update the driver in run time.

Parameters

disp: pointer to a display. (return value of lv_disp_drv_register)
new_drv: pointer to the new driver

void lv_disp_remove(lv_disp_t *disp)¶

Remove a display

Parameters

disp: pointer to display

void lv_disp_set_default(lv_disp_t *disp)¶

Set a default screen. The new screens will be created on it by default.

Parameters

disp: pointer to a display

lv_disp_t *lv_disp_get_default(void)¶

Get the default display

Return: pointer to the default display

lv_coord_t lv_disp_get_hor_res(lv_disp_t *disp)¶

Get the horizontal resolution of a display

Return

the horizontal resolution of the display

Parameters

disp: pointer to a display (NULL to use the default display)

lv_coord_t lv_disp_get_ver_res(lv_disp_t *disp)¶

Get the vertical resolution of a display

Return

the vertical resolution of the display

Parameters

disp: pointer to a display (NULL to use the default display)

bool lv_disp_get_antialiasing(lv_disp_t *disp)¶

Get if anti-aliasing is enabled for a display or not

Return

true: anti-aliasing is enabled; false: disabled

Parameters

disp: pointer to a display (NULL to use the default display)

lv_disp_t *lv_disp_get_next(lv_disp_t *disp)¶

Get the next display.

Return

the next display or NULL if no more. Give the first display when the parameter is NULL

Parameters

disp: pointer to the current display. NULL to initialize.

lv_disp_buf_t *lv_disp_get_buf(lv_disp_t *disp)¶

Get the internal buffer of a display

Return

pointer to the internal buffers

Parameters

disp: pointer to a display

uint16_t lv_disp_get_inv_buf_size(lv_disp_t *disp)¶

Get the number of areas in the buffer

Return: number of invalid areas

void lv_disp_pop_from_inv_buf(lv_disp_t *disp, uint16_t num)¶

Pop (delete) the last ‘num’ invalidated areas from the buffer

Parameters

num: number of areas to delete

bool lv_disp_is_double_buf(lv_disp_t *disp)¶

Check the driver configuration if it’s double buffered (both buf1 and buf2 are set)

Return

true: double buffered; false: not double buffered

Parameters

disp: pointer to to display to check

bool lv_disp_is_true_double_buf(lv_disp_t *disp)¶

Check the driver configuration if it’s TRUE double buffered (both buf1 and buf2 are set and size is screen sized)

Return

true: double buffered; false: not double buffered

Parameters

disp: pointer to to display to check

struct lv_disp_buf_t¶

#include <lv_hal_disp.h>

Structure for holding display buffer information.

Public Members

void *buf1¶: First display buffer.

void *buf2¶: Second display buffer.

void *buf_act¶

uint32_t size¶

lv_area_t area¶

uint32_t flushing¶

struct _disp_drv_t¶

#include <lv_hal_disp.h>

Display Driver structure to be registered by HAL

Public Members

lv_coord_t hor_res¶: Horizontal resolution.

lv_coord_t ver_res¶: Vertical resolution.

lv_disp_buf_t *buffer¶: Pointer to a buffer initialized with lv_disp_buf_init(). LittlevGL will use this buffer(s) to draw the screens contents

uint32_t antialiasing¶: 1: antialiasing is enabled on this display.

uint32_t rotated¶

1: turn the display by 90 degree.

Warning: Does not update coordinates for you!

uint32_t screen_transp¶: Handle if the the screen doesn’t have a solid (opa == LV_OPA_COVER) background. Use only if required because it’s slower.

void (*flush_cb)(struct _disp_drv_t *disp_drv, const lv_area_t *area, lv_color_t *color_p)¶: MANDATORY: Write the internal buffer (VDB) to the display. ‘lv_disp_flush_ready()’ has to be called when finished

void (*rounder_cb)(struct _disp_drv_t *disp_drv, lv_area_t *area)¶: OPTIONAL: Extend the invalidated areas to match with the display drivers requirements E.g. round y to, 8, 16 ..) on a monochrome display

void (*set_px_cb)(struct _disp_drv_t *disp_drv, uint8_t *buf, lv_coord_t buf_w, lv_coord_t x, lv_coord_t y, lv_color_t color, lv_opa_t opa)¶

OPTIONAL: Set a pixel in a buffer according to the special requirements of the display Can be used for color format not supported in LittelvGL. E.g. 2 bit -> 4 gray scales

Note: Much slower then drawing with supported color formats.

void (*monitor_cb)(struct _disp_drv_t *disp_drv, uint32_t time, uint32_t px)¶: OPTIONAL: Called after every refresh cycle to tell the rendering and flushing time + the number of flushed pixels

void (*gpu_blend_cb)(struct _disp_drv_t *disp_drv, lv_color_t *dest, const lv_color_t *src, uint32_t length, lv_opa_t opa)¶: OPTIONAL: Blend two memories using opacity (GPU only)

void (*gpu_fill_cb)(struct _disp_drv_t *disp_drv, lv_color_t *dest_buf, lv_coord_t dest_width, const lv_area_t *fill_area, lv_color_t color)¶: OPTIONAL: Fill a memory with a color (GPU only)

lv_color_t color_chroma_key¶: On CHROMA_KEYED images this color will be transparent. LV_COLOR_TRANSP by default. (lv_conf.h)

lv_disp_drv_user_data_t user_data¶: Custom display driver user data

struct _disp_t¶

#include <lv_hal_disp.h>

Display structure. lv_disp_drv_t is the first member of the structure.

Public Members

lv_disp_drv_t driver¶: < Driver to the display A task which periodically checks the dirty areas and refreshes them

lv_task_t *refr_task¶

lv_ll_t scr_ll¶: Screens of the display

struct _lv_obj_t *act_scr¶: Currently active screen on this display

struct _lv_obj_t *top_layer¶

See: lv_disp_get_layer_top

struct _lv_obj_t *sys_layer¶

See: lv_disp_get_layer_sys

lv_area_t inv_areas[LV_INV_BUF_SIZE]¶: Invalidated (marked to redraw) areas

uint8_t inv_area_joined[LV_INV_BUF_SIZE]¶

uint32_t inv_p¶

uint32_t last_activity_time¶: Last time there was activity on this display