显示器¶

Important

LVGL 中 显示器 的基本概念在 [Porting](/porting/display) 部分中进行了说明。因此，在继续阅读之前，请先阅读 [Porting](/porting/display) 部分。

多显示器支持¶

在 LVGL 中，您可以拥有多个显示器，每个显示器都有自己的驱动程序和对象。唯一的限制是每个显示器需要具有相同的颜色深度（由 LV_COLOR_DEPTH 定义）。如果显示器在这方面不同，则可以在驱动程序的 flush_cb 中将渲染的图像转换为正确的格式。

创建更多显示器很简单：只需初始化更多显示缓冲区并为每个显示器注册另一个驱动程序。当您创建 UI 时，使用 lv_disp_set_default(disp) 告诉库在哪个显示器上创建对象。

为什么需要多显示器支持？以下是一些示例：

使用一个“普通”的 TFT 显示器进行本地 UI，并根据需要在 VNC 上创建“虚拟”屏幕。（您需要添加自己的 VNC 驱动程序）。
使用一个大型 TFT 显示器和一个小型单色显示器。
在大型仪器或设备中使用一些较小且简单的显示器。
使用两个大型 TFT 显示器：一个用于客户，一个用于店员。

仅使用一个显示器¶

使用多个显示器可能很有用，但在大多数情况下并不需要。因此，如果您只注册了一个显示器，多显示器处理的整个概念将完全隐藏。默认情况下，将使用最后创建的（也是唯一的）显示器。

lv_scr_act()、lv_scr_load(scr)、lv_layer_top()、lv_layer_sys()、LV_HOR_RES 和 LV_VER_RES 始终应用于最近创建的（默认）显示器。如果您将 NULL 作为 disp 参数传递给与显示器相关的函数，通常会使用默认显示器。例如，lv_disp_trig_activity(NULL) 将触发默认显示器上的用户活动。（请参阅 Inactivity 部分）。

镜像显示器¶

要将一个显示器的图像镜像到另一个显示器，您无需使用多显示器支持。只需将 drv.flush_cb 中接收到的缓冲区传输到另一个显示器即可。

分割图像¶

您可以通过一组较小的显示器创建一个更大的虚拟显示器。可以按以下方式创建：

将显示器的分辨率设置为大显示器的分辨率。
在 drv.flush_cb 中，为每个显示器截取并修改 area 参数。
使用截取的区域将缓冲区的内容发送到每个实际显示器。

屏幕¶

每个显示器都有自己的一组屏幕和屏幕上的对象。

请确保不要混淆显示器和屏幕：

显示器 是绘制像素的物理硬件。
屏幕是与特定显示器关联的高级根对象。一个显示器可以有多个屏幕与之关联，但反之则不行。

屏幕可以被认为是没有父对象的最高级容器。屏幕的大小始终等于其显示器，并且其原点为 (0;0)。因此，屏幕的坐标无法更改，即不能对屏幕使用 lv_obj_set_pos()、lv_obj_set_size() 或类似函数。

屏幕可以从任何对象类型创建，但最典型的两种类型是基础对象和图像（用于创建壁纸）。

要创建屏幕，请使用 lv_obj_t * scr = lv_<type>_create(NULL, copy)。copy 可以是复制到新屏幕的现有屏幕。

要加载屏幕，请使用 lv_scr_load(scr)。要获取活动屏幕，请使用 lv_scr_act()。这些函数适用于默认显示器。如果您想指定要操作的显示器，请使用 lv_disp_get_scr_act(disp) 和 lv_disp_load_scr(disp, scr)。屏幕也可以通过动画加载。更多信息请阅读此处。

可以使用 lv_obj_del(scr) 删除屏幕，但请确保不要删除当前加载的屏幕。

透明屏幕¶

通常，屏幕的不透明度为 LV_OPA_COVER，为其子对象提供实心背景。如果不是这种情况（不透明度 < 100%），显示器的背景颜色或图像将可见。有关更多详细信息，请参阅显示器背景部分。如果显示器的背景不透明度也不是 LV_OPA_COVER，LVGL 将没有可绘制的实心背景。

这种配置（透明屏幕和显示器）可用于创建例如 OSD 菜单，其中视频在下层播放，菜单在上层覆盖。

要处理透明显示器，LVGL 需要使用特殊（较慢）的颜色混合算法，因此需要在 lv_conf.h 中启用此功能，方法是设置 LV_COLOR_SCREEN_TRANSP。 32 位颜色的 Alpha 通道将在没有对象的地方为 0，在有实心对象的地方为 255。

总结如下，启用 OSD 菜单样式 UI 的透明屏幕和显示器：

在 lv_conf.h 中启用 LV_COLOR_SCREEN_TRANSP。
将屏幕的不透明度设置为 LV_OPA_TRANSP，例如使用 lv_obj_set_style_local_bg_opa(lv_scr_act(), LV_OBJMASK_PART_MAIN, LV_STATE_DEFAULT, LV_OPA_TRANSP)。
使用 lv_disp_set_bg_opa(NULL, LV_OPA_TRANSP); 将显示器的不透明度设置为 LV_OPA_TRANSP。

显示器的功能¶

不活动时间¶

每个显示器都会测量用户的不活动时间。每次使用输入设备（如果与显示器关联）都会计为一次活动。要获取自上次活动以来的时间，请使用 lv_disp_get_inactive_time(disp)。如果传递 NULL，将返回所有显示器中最低的不活动时间（NULL 不仅仅是默认显示器）。

您可以使用 lv_disp_trig_activity(disp) 手动触发活动。如果 disp 为 NULL，将使用默认屏幕（而不是所有显示器）。

背景¶

每个显示器都有背景颜色、背景图像和背景不透明度属性。当当前屏幕是透明的或未覆盖整个显示器时，它们会变得可见。

背景颜色是填充显示器的简单颜色。可以使用 lv_disp_set_bg_color(disp, color) 调整。

显示器背景图像是文件路径或指向 lv_img_dsc_t 变量（转换后的图像数据）的指针，用作壁纸。可以使用 lv_disp_set_bg_image(disp, &my_img) 设置；如果配置了背景图像，则背景不会填充 bg_color。

可以使用 lv_disp_set_bg_opa(disp, opa) 调整背景颜色或图像的不透明度。

这些函数的 disp 参数可以为 NULL，以选择默认显示器。

API¶

Enums

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¶

Functions

lv_obj_t *lv_disp_get_scr_act(lv_disp_t *disp)¶

Return with a pointer to the active screen

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()')

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(lv_obj_t *scr)¶

Make a screen active

Parameters: scr -- pointer to a screen

lv_obj_t *lv_disp_get_layer_top(lv_disp_t *disp)¶

Return with the top layer. (Same on every screen 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 (transparent screen sized lv_obj)

lv_obj_t *lv_disp_get_layer_sys(lv_disp_t *disp)¶

Return with the sys. layer. (Same on every 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 (transparent screen sized lv_obj)

void lv_disp_set_theme(lv_disp_t *disp, lv_theme_t *th)¶

Set the theme of a display

Parameters: disp -- pointer to a display

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)

void lv_disp_set_bg_color(lv_disp_t *disp, lv_color_t color)¶

Set the background color of a display

Parameters

disp -- pointer to a display
color -- color of the background

void lv_disp_set_bg_image(lv_disp_t *disp, const void *img_src)¶

Set the background image of a display

Parameters

disp -- pointer to a display
img_src -- path to file or pointer to an lv_img_dsc_t variable

void lv_disp_set_bg_opa(lv_disp_t *disp, lv_opa_t opa)¶

Set opacity of the background

Parameters

disp -- pointer to a display
opa -- opacity (0..255)

void lv_scr_load_anim(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

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_clean_dcache(lv_disp_t *disp)¶

Clean any CPU cache that is related to the 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_obj_t *lv_scr_act(void)¶

Get the active screen of the default display

Returns: pointer to the active screen

static inline lv_obj_t *lv_layer_top(void)¶

Get the top layer of the default display

Returns: pointer to the top layer

static inline lv_obj_t *lv_layer_sys(void)¶

Get the active screen of the default display

Returns: pointer to the sys layer

static inline void lv_scr_load(lv_obj_t *scr)¶

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