Displays¶
Important
The basic concept of a display in LVGL is explained in the [Porting](/porting/display) section. So before reading further, please read the [Porting](/porting/display) section first.
Multiple display support¶
In LVGL you can have multiple displays, each with their own driver and objects. The only limitation is that every display needs to have the same color depth (as defined in LV_COLOR_DEPTH
).
If the displays are different in this regard the rendered image can be converted to the correct format in the drivers flush_cb
.
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 on which display to create objects.
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 handling is completely hidden if you register only one display. By default, the last created (and only) display is used.
lv_scr_act()
, lv_scr_load(scr)
, lv_layer_top()
, lv_layer_sys()
, LV_HOR_RES
and LV_VER_RES
are always applied on the most recently created (default) display.
If you pass NULL
as disp
parameter to display related functions the default display will usually be used.
E.g. lv_disp_trig_activity(NULL)
will trigger a user activity on the default display. (See below in Inactivity).
Duplicate display¶
To duplicate the image of a display to another display, you don't need to the use multi-display support. Just transfer the buffer received in flush_cb
to the other display too.
Split image¶
You can create a larger virtual display from an array of smaller ones. You can create it as below:
Set the resolution of the displays to the large display's resolution.
In
flush_cb
, truncate and modify thearea
parameter for each display.Send the buffer's content to each real display with the truncated area.
Screens¶
Every display has its own set of screens and the objects on each screen.
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.
A screen's size is always equal to its display and their origin is (0;0). Therefore, a screen's coordinates can't be changed, i.e. lv_obj_set_pos()
, lv_obj_set_size()
or similar functions can't be used on screens.
A screen can be created from any object type but the two most typical types are Base object and Image (to create a wallpaper).
To create a screen, use lv_obj_t * scr = lv_<type>_create(NULL, copy)
. copy
can be an existing screen copied into the new screen.
To load a screen, use lv_scr_load(scr)
. To get the active screen, use lv_scr_act()
. These functions work on the default display. If you want to specify which display to work on, use lv_disp_get_scr_act(disp)
and lv_disp_load_scr(disp, scr)
. A screen can be loaded with animations too. Read more here.
Screens can be deleted with lv_obj_del(scr)
, but ensure that you do not delete the currently loaded screen.
Transparent screens¶
Usually, the opacity of the screen is LV_OPA_COVER
to provide a solid background for its children. If this is not the case (opacity < 100%) the display's bottom_layer
will be visible.
If the bottom layer's opacity is also not LV_OPA_COVER
LVGL has no solid background to draw.
This configuration (transparent screen and display) could be used to create for example OSD menus where a video is played on a lower layer, and a menu is overlaid on an upper layer.
To properly render the screen the display's color format needs to be set to one with alpha channel.
In summary, to enable transparent screens and displays for OSD menu-like UIs:
Set the screen's
bg_opa
to transparent:lv_obj_set_style_local_bg_opa(lv_scr_act(), LV_OPA_TRANSP, 0)
Set the bottom layer's
bg_opa
to transparent:lv_obj_set_style_local_bg_opa(lv_bottom_layer(), LV_OPA_TRANSP, 0)
Set a color format with alpha channel. E.g.
lv_disp_set_color_format(disp, LV_COLOR_FORMAT_NATIVE_ALPHA)
Features of displays¶
Inactivity¶
A user's inactivity time 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 lv_disp_get_inactive_time(disp)
. If NULL
is passed, the lowest inactivity time among all displays will be returned (NULL isn't just the default display).
You can manually trigger an activity using lv_disp_trig_activity(disp)
. If disp
is NULL
, the default screen will be used (and not all displays).
Background¶
Every display has a background color, background image and background opacity properties. They become visible when the current screen is transparent or not positioned to cover the whole display.
The background color is a simple color to fill the display. It can be adjusted with lv_disp_set_bg_color(disp, color)
;
The display background image is a path to a file or a pointer to an lv_img_dsc_t
variable (converted image data) to be used as wallpaper. It can be set with lv_disp_set_bg_image(disp, &my_img)
;
If a background image is configured the background won't be filled with bg_color
.
The opacity of the background color or image can be adjusted with lv_disp_set_bg_opa(disp, opa)
.
The disp
parameter of these functions can be NULL
to select the default display.
API¶
Typedefs
-
typedef struct _lv_disp_t lv_disp_t¶
Enums
-
enum lv_disp_rotation_t¶
Values:
-
enumerator LV_DISP_ROTATION_0¶
-
enumerator LV_DISP_ROTATION_90¶
-
enumerator LV_DISP_ROTATION_180¶
-
enumerator LV_DISP_ROTATION_270¶
-
enumerator LV_DISP_ROTATION_0¶
-
enum lv_disp_render_mode_t¶
Values:
-
enumerator LV_DISP_RENDER_MODE_PARTIAL¶
Use the buffer(s) to render the screen is smaller parts. This way the buffers can be smaller then the display to save RAM. At least 1/10 sceen size buffer(s) are recommended.
-
enumerator LV_DISP_RENDER_MODE_DIRECT¶
The buffer(s) has to be screen sized and LVGL will render into the correct location of the buffer. This way the buffer always contain the whole image. Only the changed ares will be updated. With 2 buffers the buffers' content are kept in sync automatically and in flush_cb only address change is required.
-
enumerator LV_DISP_RENDER_MODE_FULL¶
Always redraw the whole screen even if only one pixel has been changed. With 2 buffers in flush_cb only and address change is required.
-
enumerator LV_DISP_RENDER_MODE_PARTIAL¶
-
enum lv_scr_load_anim_t¶
Values:
-
enumerator LV_SCR_LOAD_ANIM_NONE¶
-
enumerator LV_SCR_LOAD_ANIM_OVER_LEFT¶
-
enumerator LV_SCR_LOAD_ANIM_OVER_RIGHT¶
-
enumerator LV_SCR_LOAD_ANIM_OVER_TOP¶
-
enumerator LV_SCR_LOAD_ANIM_OVER_BOTTOM¶
-
enumerator LV_SCR_LOAD_ANIM_MOVE_LEFT¶
-
enumerator LV_SCR_LOAD_ANIM_MOVE_RIGHT¶
-
enumerator LV_SCR_LOAD_ANIM_MOVE_TOP¶
-
enumerator LV_SCR_LOAD_ANIM_MOVE_BOTTOM¶
-
enumerator LV_SCR_LOAD_ANIM_FADE_IN¶
-
enumerator LV_SCR_LOAD_ANIM_FADE_ON¶
-
enumerator LV_SCR_LOAD_ANIM_FADE_OUT¶
-
enumerator LV_SCR_LOAD_ANIM_OUT_LEFT¶
-
enumerator LV_SCR_LOAD_ANIM_OUT_RIGHT¶
-
enumerator LV_SCR_LOAD_ANIM_OUT_TOP¶
-
enumerator LV_SCR_LOAD_ANIM_OUT_BOTTOM¶
-
enumerator LV_SCR_LOAD_ANIM_NONE¶
Functions
-
lv_disp_t *lv_disp_create(lv_coord_t hor_res, lv_coord_t ver_res)¶
Create a new display with the given resolution
- Parameters
hor_res -- horizontal resolution in pixels
ver_res -- vertical resolution in pixels
- Returns
pointer to a display object or
NULL
on error
-
void lv_disp_set_default(lv_disp_t *disp)¶
Set a default display. 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
- Returns
pointer to the default display
-
lv_disp_t *lv_disp_get_next(lv_disp_t *disp)¶
Get the next display.
- Parameters
disp -- pointer to the current display. NULL to initialize.
- Returns
the next display or NULL if no more. Gives the first display when the parameter is NULL.
-
void lv_disp_set_res(lv_disp_t *disp, lv_coord_t hor_res, lv_coord_t ver_res)¶
Sets the resolution of a display.
LV_EVENT_RESOLUTION_CHANGED
event will be sent. Here the native resolution of the device should be set. If the display will be rotated later withlv_disp_set_rotation
LVGL will swap the hor. and ver. resolution automatically.- Parameters
disp -- pointer to a display
hor_res -- the new horizontal resolution
ver_res -- the new vertical resolution
-
void lv_disp_set_physical_res(lv_disp_t *disp, lv_coord_t hor_res, lv_coord_t ver_res)¶
It's not mandatory to use the whole display for LVGL, however in some cases physical resolution is important. For example the touchpad still sees whole resolution and the values needs to be converted to the active LVGL display area.
- Parameters
disp -- pointer to a display
hor_res -- the new physical horizontal resolution, or -1 to assume it's the same as the normal hor. res.
ver_res -- the new physical vertical resolution, or -1 to assume it's the same as the normal hor. res.
-
void lv_disp_set_offset(lv_disp_t *disp, lv_coord_t x, lv_coord_t y)¶
If physical resolution is not the same as the normal resolution the offset of the active display area can be set here.
- Parameters
disp -- pointer to a display
x -- X offset
y -- Y offset
-
void lv_disp_set_rotation(lv_disp_t *disp, lv_disp_rotation_t rotation, bool sw_rotate)¶
Set the rotation of this display. LVGL will swap the horizontal and vertical resolutions internally.
- Parameters
disp -- pointer to a display (NULL to use the default display)
rotation --
LV_DISP_ROTATION_0/90/180/270
sw_rotate -- true: make LVGL rotate the rendered image; false: the display driver should rotate the rendered image
-
void lv_disp_set_dpi(lv_disp_t *disp, lv_coord_t dpi)¶
Set the DPI (dot per inch) of the display. dpi = sqrt(hor_res^2 + ver_res^2) / diagonal"
- Parameters
disp -- pointer to a display
dpi -- the new DPI
-
lv_coord_t lv_disp_get_hor_res(const lv_disp_t *disp)¶
Get the horizontal resolution of a display.
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
the horizontal resolution of the display.
-
lv_coord_t lv_disp_get_ver_res(const lv_disp_t *disp)¶
Get the vertical resolution of a display
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
the vertical resolution of the display
-
lv_coord_t lv_disp_get_physical_hor_res(const lv_disp_t *disp)¶
Get the physical horizontal resolution of a display
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
the physical horizontal resolution of the display
-
lv_coord_t lv_disp_get_physical_ver_res(const lv_disp_t *disp)¶
Get the physical vertical resolution of a display
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
the physical vertical resolution of the display
-
lv_coord_t lv_disp_get_offset_x(const lv_disp_t *disp)¶
Get the horizontal offset from the full / physical display
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
the horizontal offset from the physical display
-
lv_coord_t lv_disp_get_offset_y(const lv_disp_t *disp)¶
Get the vertical offset from the full / physical display
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
the horizontal offset from the physical display
-
lv_disp_rotation_t lv_disp_get_rotation(lv_disp_t *disp)¶
Get the current rotation of this display.
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
the current rotation
-
lv_coord_t lv_disp_get_dpi(const lv_disp_t *disp)¶
Get the DPI of the display
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
dpi of the display
-
void lv_disp_set_draw_buffers(lv_disp_t *disp, void *buf1, void *buf2, uint32_t buf_size_byte, lv_disp_render_mode_t render_mode)¶
Set the buffers for a display
- Parameters
disp -- pointer to a display
buf1 -- first buffer
buf2 -- second buffer (can be
NULL
)buf_size_byte -- size of the buffer in bytes
render_mode -- LV_DISP_RENDER_MODE_PARTIAL/DIRECT/FULL
-
void lv_disp_set_flush_cb(lv_disp_t *disp, void (*flush_cb)(struct _lv_disp_t *disp, const lv_area_t *area, lv_color_t *px_map))¶
Set the flush callback whcih will be called to copy the rendered image to the display.
- Parameters
disp -- pointer to a display
flush_cb -- the flush callback (
px_map
contains the rendered image as raw pixel map and it should be copied toarea
on the display)
-
void lv_disp_set_color_format(lv_disp_t *disp, lv_color_format_t color_format)¶
Set the color format of the display. If set to other than
LV_COLOR_FORMAT_NATIVE
the draw_ctx'sbuffer_convert
function will be used to convert the rendered content to the desired color format.- Parameters
disp -- pointer to a display
color_format -- By default
LV_COLOR_FORMAT_NATIVE
to render with L8, RGB565, RGB888 or ARGB8888.LV_COLOR_FORMAT_NATIVE_REVERSE
to change endianess.
-
lv_color_format_t lv_disp_get_color_format(lv_disp_t *disp)¶
Get the color format of the display
- Parameters
disp -- pointer to a display
- Returns
the color format
-
void lv_disp_set_antialaising(lv_disp_t *disp, bool en)¶
Enable anti-aliasing for the render engine
- Parameters
disp -- pointer to a display
en -- true/false
-
bool lv_disp_get_antialiasing(lv_disp_t *disp)¶
Get if anti-aliasing is enabled for a display or not
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
true/false
-
void lv_disp_set_draw_ctx(lv_disp_t *disp, void (*draw_ctx_init)(lv_disp_t *disp, struct _lv_draw_ctx_t *draw_ctx), void (*draw_ctx_deinit)(lv_disp_t *disp, struct _lv_draw_ctx_t *draw_ctx), size_t draw_ctx_size)¶
Initialize a new draw context for the display
- Parameters
disp -- pointer to a display
draw_ctx_init -- init callback
draw_ctx_deinit -- deinit callback
draw_ctx_size -- size of the draw context instance
-
struct _lv_obj_t *lv_disp_get_scr_act(lv_disp_t *disp)¶
Return a pointer to the active screen on a display
- Parameters
disp -- pointer to display which active screen should be get. (NULL to use the default screen)
- Returns
pointer to the active screen object (loaded by 'lv_scr_load()')
-
struct _lv_obj_t *lv_disp_get_scr_prev(lv_disp_t *disp)¶
Return with a pointer to the previous screen. Only used during screen transitions.
- Parameters
disp -- pointer to display which previous screen should be get. (NULL to use the default screen)
- Returns
pointer to the previous screen object or NULL if not used now
-
void lv_disp_load_scr(struct _lv_obj_t *scr)¶
Make a screen active
- Parameters
scr -- pointer to a screen
-
struct _lv_obj_t *lv_disp_get_layer_top(lv_disp_t *disp)¶
Return the top layer. The top layer is the same on all screens and it is above the normal screen layer.
- Parameters
disp -- pointer to display which top layer should be get. (NULL to use the default screen)
- Returns
pointer to the top layer object
-
struct _lv_obj_t *lv_disp_get_layer_sys(lv_disp_t *disp)¶
Return the sys. layer. The system layer is the same on all screen and it is above the normal screen and the top layer.
- Parameters
disp -- pointer to display which sys. layer should be retrieved. (NULL to use the default screen)
- Returns
pointer to the sys layer object
-
struct _lv_obj_t *lv_disp_get_layer_bottom(lv_disp_t *disp)¶
Return the bottom layer. The bottom layer is the same on all screen and it is under the normal screen layer. It's visble only if the the screen is transparent.
- Parameters
disp -- pointer to display (NULL to use the default screen)
- Returns
pointer to the bottom layer object
-
void lv_scr_load_anim(struct _lv_obj_t *scr, lv_scr_load_anim_t anim_type, uint32_t time, uint32_t delay, bool auto_del)¶
Switch screen with animation
- Parameters
scr -- pointer to the new screen to load
anim_type -- type of the animation from
lv_scr_load_anim_t
, e.g.LV_SCR_LOAD_ANIM_MOVE_LEFT
time -- time of the animation
delay -- delay before the transition
auto_del -- true: automatically delete the old screen
-
static inline struct _lv_obj_t *lv_scr_act(void)¶
Get the active screen of the default display
- Returns
pointer to the active screen
-
static inline struct _lv_obj_t *lv_layer_top(void)¶
Get the top layer of the default display
- Returns
pointer to the top layer
-
static inline struct _lv_obj_t *lv_layer_sys(void)¶
Get the system layer of the default display
- Returns
pointer to the sys layer
-
static inline struct _lv_obj_t *lv_layer_bottom(void)¶
Get the bottom layer of the default display
- Returns
pointer to the bottom layer
-
static inline void lv_scr_load(struct _lv_obj_t *scr)¶
Load a screen on the default display
- Parameters
scr -- pointer to a screen
-
void lv_disp_add_event(lv_disp_t *disp, lv_event_cb_t event_cb, lv_event_code_t filter, void *user_data)¶
Add an event handler to the display
- Parameters
disp -- pointer to a display
event_cb -- an event callback
filter -- event code to react or
LV_EVENT_ALL
user_data -- optional user_data
-
lv_event_dsc_t *lv_disp_get_event_dsc(lv_disp_t *disp, uint32_t index)¶
-
lv_res_t lv_disp_send_event(lv_disp_t *disp, lv_event_code_t code, void *user_data)¶
Send amn event to a display
- Parameters
disp -- pointer to a display
code -- an event code. LV_EVENT_...
user_data -- optional user_data
- Returns
LV_RES_OK: disp wasn't deleted in the event.
-
void lv_disp_set_theme(lv_disp_t *disp, struct _lv_theme_t *th)¶
Set the theme of a display. If there are no user created widgets yet the screens' theme will be updated
- Parameters
disp -- pointer to a display
th -- pointer to a theme
-
struct _lv_theme_t *lv_disp_get_theme(lv_disp_t *disp)¶
Get the theme of a display
- Parameters
disp -- pointer to a display
- Returns
the display's theme (can be NULL)
-
uint32_t lv_disp_get_inactive_time(const lv_disp_t *disp)¶
Get elapsed time since last user activity on a display (e.g. click)
- Parameters
disp -- pointer to a display (NULL to get the overall smallest inactivity)
- Returns
elapsed ticks (milliseconds) since the last activity
-
void lv_disp_trig_activity(lv_disp_t *disp)¶
Manually trigger an activity on a display
- Parameters
disp -- pointer to a display (NULL to use the default display)
-
void lv_disp_enable_invalidation(lv_disp_t *disp, bool en)¶
Temporarily enable and disable the invalidation of the display.
- Parameters
disp -- pointer to a display (NULL to use the default display)
en -- true: enable invalidation; false: invalidation
-
bool lv_disp_is_invalidation_enabled(lv_disp_t *disp)¶
Get display invalidation is enabled.
- Parameters
disp -- pointer to a display (NULL to use the default display)
- Returns
return true if invalidation is enabled
-
lv_timer_t *_lv_disp_get_refr_timer(lv_disp_t *disp)¶
Get a pointer to the screen refresher timer to modify its parameters with
lv_timer_...
functions.- Parameters
disp -- pointer to a display
- Returns
pointer to the display refresher timer. (NULL on error)
-
static inline lv_coord_t lv_dpx(lv_coord_t n)¶
Scale the given number of pixels (a distance or size) relative to a 160 DPI display considering the DPI of the default display. It ensures that e.g.
lv_dpx(100)
will have the same physical size regardless to the DPI of the display.- Parameters
n -- the number of pixels to scale
- Returns
n x current_dpi/160
-
static inline lv_coord_t lv_disp_dpx(const lv_disp_t *disp, lv_coord_t n)¶
Scale the given number of pixels (a distance or size) relative to a 160 DPI display considering the DPI of the given display. It ensures that e.g.
lv_dpx(100)
will have the same physical size regardless to the DPI of the display.- Parameters
obj -- a display whose dpi should be considered
n -- the number of pixels to scale
- Returns
n x current_dpi/160