The basic concept of display in LVGL is explained in the [Porting](/porting/display) section. So before reading further, please read the [Porting](/porting/display) section first.
In LVGL, you can have multiple displays, each with their own driver and objects.
Creating more displays is easy: just initialize more display buffers and register another driver for every display.
When you create the UI, use
lv_disp_set_default(disp) to tell the library which display to create objects on.
Why would you want multi-display support? Here are some examples:
Have a "normal" TFT display with local UI and create "virtual" screens on VNC on demand. (You need to add your VNC driver).
Have a large TFT display and a small monochrome display.
Have some smaller and simple displays in a large instrument or technology.
Have two large TFT displays: one for a customer and one for the shop assistant.
Using only one display¶
Using more displays can be useful, but in most cases, it's not required. Therefore, the whole concept of multi-display is completely hidden if you register only one display. By default, the lastly created (the only one) display is used as default.
LV_VER_RES are always applied on the lastly created (default) screen.
If you pass
disp parameter to display related function, usually the default display will be used.
lv_disp_trig_activity(NULL) will trigger a user activity on the default screen. (See below in Inactivity).
To mirror the image of the display to another display, you don't need to use the multi-display support. Just transfer the buffer received in
drv.flush_cb to another display too.
You can create a larger display from smaller ones. You can create it as below:
Set the resolution of the displays to the large display's resolution.
drv.flush_cb, truncate and modify the
areaparameter for each display.
Send the buffer's content to each display with the truncated area.
Every display has each set of Screens and the object on the screens.
Be sure not to confuse displays and screens:
Displays are the physical hardware drawing the pixels.
Screens are the high-level root objects associated with a particular display. One display can have multiple screens associated with it, but not vice versa.
Screens can be considered the highest level containers which have no parent.
The screen's size is always equal to its display and size their position is (0;0). Therefore, the screens coordinates can't be changed, i.e.
lv_obj_set_size() or similar functions can't be used on screens.
To create a screen, use
lv_obj_t * scr = lv_<type>_create(NULL, copy).
copy can be an other screen to copy it.
To load a screen, use
lv_scr_load(scr). To get the active screen, use
lv_scr_act(). These functions works on the default display. If you want to to specify which display to work on, use
Screens can be deleted with
lv_obj_del(scr), but ensure that you do not delete the currently loaded screen.
Usually, the opacity of the screen is
LV_OPA_COVER to provide a solid background for its children.
However, in some special cases, you might want a transparent screen. For example, if you have a video player that renders video frames on a lower layer, you want to create an OSD menu on the upper layer (over the video) using LVGL.
To do this, the screen should have a style that sets
LV_OPA_TRANSP (or another non-opaque value) to make the screen opaque.
LV_COLOR_SCREEN_TRANSP needs to be enabled. Please note that it only works with
LV_COLOR_DEPTH = 32.
The Alpha channel of 32-bit colors will be 0 where there are no objects and will be 255 where there are solid objects.
Features of displays¶
The user's inactivity is measured on each display. Every use of an Input device (if associated with the display) counts as an activity.
To get time elapsed since the last activity, use
NULL is passed, the overall smallest inactivity time will be returned from all displays (not the default display).
You can manually trigger an activity using
NULL, the default screen will be used (and not all displays).
The color module handles all color-related functions like changing color depth, creating colors from hex code, converting between color depths, mixing colors, etc.
The following variable types are defined by the color module:
lv_color1_t Store monochrome color. For compatibility, it also has R, G, B fields but they are always the same value (1 byte)
lv_color8_t A structure to store R (3 bit),G (3 bit),B (2 bit) components for 8-bit colors (1 byte)
lv_color16_t A structure to store R (5 bit),G (6 bit),B (5 bit) components for 16-bit colors (2 byte)
lv_color32_t A structure to store R (8 bit),G (8 bit), B (8 bit) components for 24-bit colors (4 byte)
lv_color_t Equal to
lv_color1/8/16/24_taccording to color depth settings
uint32_taccording to color depth setting. Used to build color arrays from plain numbers.
lv_opa_t A simple
uint8_t type to describe opacity.
lv_color32_t types have got four fields:
ch.red red channel
ch.green green channel
ch.blue blue channel
full red + green + blue as one number
You can set the current color depth in lv_conf.h, by setting the
LV_COLOR_DEPTH define to 1 (monochrome), 8, 16 or 32.
You can convert a color from the current color depth to another. The converter functions return with a number, so you have to use the
lv_color_t c; c.red = 0x38; c.green = 0x70; c.blue = 0xCC; lv_color1_t c1; c1.full = lv_color_to1(c); /*Return 1 for light colors, 0 for dark colors*/ lv_color8_t c8; c8.full = lv_color_to8(c); /*Give a 8 bit number with the converted color*/ lv_color16_t c16; c16.full = lv_color_to16(c); /*Give a 16 bit number with the converted color*/ lv_color32_t c24; c32.full = lv_color_to32(c); /*Give a 32 bit number with the converted color*/
Swap 16 colors¶
You may set
LV_COLOR_16_SWAP in lv_conf.h to swap the bytes of RGB565 colors. It's useful if you send the 16-bit colors via a byte-oriented interface like SPI.
As 16-bit numbers are stored in Little Endian format (lower byte on the lower address), the interface will send the lower byte first. However, displays usually need the higher byte first. A mismatch in the byte order will result in highly distorted colors.
Create and mix colors¶
You can create colors with the current color depth using the LV_COLOR_MAKE macro. It takes 3 arguments (red, green, blue) as 8-bit numbers.
For example to create light red color:
my_color = COLOR_MAKE(0xFF,0x80,0x80).
Colors can be created from HEX codes too:
my_color = lv_color_hex(0x288ACF) or
my_color = lv_folro_hex3(0x28C).
Mixing two colors is possible with
mixed_color = lv_color_mix(color1, color2, ratio). Ration can be 0..255. 0 results fully color2, 255 result fully color1.
Colors can be created with from HSV space too using
lv_color_hsv_to_rgb(hue, saturation, value) .
hue should be in 0..360 range,
value in 0..100 range.
To describe opacity the
lv_opa_t type is created as a wrapper to
uint8_t. Some defines are also introduced:
LV_OPA_TRANSP Value: 0, means the opacity makes the color completely transparent
LV_OPA_10 Value: 25, means the color covers only a little
LV_OPA_20 ... OPA_80 come logically
LV_OPA_90 Value: 229, means the color near completely covers
LV_OPA_COVER Value: 255, means the color completely covers
You can also use the
LV_OPA_* defines in
lv_color_mix() as a ratio.
The color module defines the most basic colors such as:
as well as
LV_COLOR_WHITE (fully white).
Return with a pointer to the active screen
pointer to the active screen object (loaded by 'lv_scr_load()')
disp: pointer to display which active screen should be get. (NULL to use the default screen)
Return with the top layer. (Same on every screen and it is above the normal screen layer)
pointer to the top layer object (transparent screen sized lv_obj)
disp: pointer to display which top layer should be get. (NULL to use the default screen)
Return with the sys. layer. (Same on every screen and it is above the normal screen and the top layer)
pointer to the sys layer object (transparent screen sized lv_obj)
disp: pointer to display which sys. layer should be get. (NULL to use the default screen)
lv_disp_assign_screen(lv_disp_t *disp, lv_obj_t *scr)¶
Assign a screen to a display.
disp: pointer to a display where to assign the screen
scr: pointer to a screen object to assign
lv_disp_get_inactive_time(const lv_disp_t *disp)¶
Get elapsed time since last user activity on a display (e.g. click)
elapsed ticks (milliseconds) since the last activity
disp: pointer to an display (NULL to get the overall smallest inactivity)
Manually trigger an activity on a display
disp: pointer to an display (NULL to use the default display)
Get a pointer to the screen refresher task to modify its parameters with
pointer to the display refresher task. (NULL on error)
disp: pointer to a display
Get the active screen of the default display
pointer to the active screen
Get the top layer of the default display
pointer to the top layer
Get the active screen of the default display
pointer to the sys layer
Get the brightness of a color
the brightness [0..255]
color: a color
lv_color_hsv_to_rgb(uint16_t h, uint8_t s, uint8_t v)¶
Convert a HSV color to RGB
the given RGB color in RGB (with LV_COLOR_DEPTH depth)
h: hue [0..359]
s: saturation [0..100]
v: value [0..100]
lv_color_rgb_to_hsv(uint8_t r8, uint8_t g8, uint8_t b8)¶
Convert a 32-bit RGB color to HSV
the given RGB color in HSV
r8: 8-bit red
g8: 8-bit green
b8: 8-bit blue