lv_display.h

Defines

LV_HOR_RES

The horizontal resolution of the currently active display.

LV_VER_RES

The vertical resolution of the currently active display.

LV_DPX_CALC(dpi, n)

See lv_dpx() and lv_display_dpx(). Same as Android's DIP. (Different name is chosen to avoid mistype between LV_DPI and LV_DIP)

• 40 dip is 40 px on a 160 DPI screen (distance = 1/4 inch).

• 40 dip is 80 px on a 320 DPI screen (distance still = 1/4 inch).

See also

https://stackoverflow.com/questions/2025282/what-is-the-difference-between-px-dip-dp-and-sp

LV_DPX(n)

Typedefs

typedef void (*lv_display_flush_cb_t)(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map)

typedef void (*lv_display_flush_wait_cb_t)(lv_display_t *disp)

Enums

enum lv_display_rotation_t

Values:

enumerator LV_DISPLAY_ROTATION_0

enumerator LV_DISPLAY_ROTATION_90

enumerator LV_DISPLAY_ROTATION_180

enumerator LV_DISPLAY_ROTATION_270

enum lv_display_render_mode_t

Values:

enumerator LV_DISPLAY_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 screen size buffer(s) are recommended.

enumerator LV_DISPLAY_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_DISPLAY_RENDER_MODE_FULL

Always redraw the whole screen even if only one pixel has been changed. With 2 buffers in flush_cb only an address change is required.

enum lv_screen_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_display_t *lv_display_create(int32_t hor_res, int32_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_display_delete(lv_display_t *disp)

Remove a display

Parameters:

disp – pointer to display

void lv_display_set_default(lv_display_t *disp)

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

Parameters:

disp – pointer to a display

lv_display_t *lv_display_get_default(void)

Get the default display

Returns:

pointer to the default display

lv_display_t *lv_display_get_next(lv_display_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_display_set_resolution(lv_display_t *disp, int32_t hor_res, int32_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 with lv_display_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_display_set_physical_resolution(lv_display_t *disp, int32_t hor_res, int32_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_display_set_offset(lv_display_t *disp, int32_t x, int32_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_display_set_rotation(lv_display_t *disp, lv_display_rotation_t rotation)

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_DISPLAY_ROTATION_0/90/180/270

void lv_display_set_dpi(lv_display_t *disp, int32_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

int32_t lv_display_get_horizontal_resolution(const lv_display_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.

int32_t lv_display_get_vertical_resolution(const lv_display_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

int32_t lv_display_get_physical_horizontal_resolution(const lv_display_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

int32_t lv_display_get_physical_vertical_resolution(const lv_display_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

int32_t lv_display_get_offset_x(const lv_display_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

int32_t lv_display_get_offset_y(const lv_display_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_display_rotation_t lv_display_get_rotation(lv_display_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

int32_t lv_display_get_dpi(const lv_display_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_display_set_buffers(lv_display_t *disp, void *buf1, void *buf2, uint32_t buf_size, lv_display_render_mode_t render_mode)

Set the buffers for a display, similarly to lv_display_set_draw_buffers, but accept the raw buffer pointers. For DIRECT/FULL rending modes, the buffer size must be at least hor_res * ver_res * lv_color_format_get_size(lv_display_get_color_format(disp))

Parameters:

• disp – pointer to a display

• buf1 – first buffer

• buf2 – second buffer (can be NULL)

• buf_size – buffer size in byte

• render_mode – LV_DISPLAY_RENDER_MODE_PARTIAL/DIRECT/FULL

void lv_display_set_buffers_with_stride(lv_display_t *disp, void *buf1, void *buf2, uint32_t buf_size, uint32_t stride, lv_display_render_mode_t render_mode)

Set the frame buffers for a display, similarly to lv_display_set_buffers, but allow for a custom stride as required by a display controller. This allows the frame buffers to have a stride alignment different from the rest of the buffers`

Parameters:

• disp – pointer to a display

• buf1 – first buffer

• buf2 – second buffer (can be NULL)

• buf_size – buffer size in byte

• stride – buffer stride in bytes

• render_mode – LV_DISPLAY_RENDER_MODE_PARTIAL/DIRECT/FULL

void lv_display_set_draw_buffers(lv_display_t *disp, lv_draw_buf_t *buf1, lv_draw_buf_t *buf2)

Set the buffers for a display, accept a draw buffer pointer. Normally use lv_display_set_buffers is enough for most cases. Use this function when an existing lv_draw_buf_t is available.

Parameters:

• disp – pointer to a display

• buf1 – first buffer

• buf2 – second buffer (can be NULL)

void lv_display_set_render_mode(lv_display_t *disp, lv_display_render_mode_t render_mode)

Set display render mode

Parameters:

• disp – pointer to a display

• render_mode – LV_DISPLAY_RENDER_MODE_PARTIAL/DIRECT/FULL

void lv_display_set_flush_cb(lv_display_t *disp, lv_display_flush_cb_t flush_cb)

Set the flush callback which 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 to area on the display)

void lv_display_set_flush_wait_cb(lv_display_t *disp, lv_display_flush_wait_cb_t wait_cb)

Set a callback to be used while LVGL is waiting flushing to be finished. It can do any complex logic to wait, including semaphores, mutexes, polling flags, etc. If not set the disp->flushing flag is used which can be cleared with lv_display_flush_ready()

Parameters:

• disp – pointer to a display

• wait_cb – a callback to call while LVGL is waiting for flush ready. If NULL lv_display_flush_ready() can be used to signal that flushing is ready.

void lv_display_set_color_format(lv_display_t *disp, lv_color_format_t color_format)

Set the color format of the display.

Note

To change the endianness of the rendered image in case of RGB565 format (i.e. swap the 2 bytes) call lv_draw_sw_rgb565_swap in the flush_cb

Parameters:

• disp – pointer to a display

• color_format – Possible values are

  • LV_COLOR_FORMAT_RGB565

  • LV_COLOR_FORMAT_RGB888

  • LV_COLOR_FORMAT_XRGB888

  • LV_COLOR_FORMAT_ARGB888

lv_color_format_t lv_display_get_color_format(lv_display_t *disp)

Get the color format of the display

Parameters:

disp – pointer to a display

Returns:

the color format

void lv_display_set_tile_cnt(lv_display_t *disp, uint32_t tile_cnt)

Set the number of tiles for parallel rendering.

Parameters:

• disp – pointer to a display

• tile_cnt – number of tiles (1 =< tile_cnt < 256)

uint32_t lv_display_get_tile_cnt(lv_display_t *disp)

Get the number of tiles used for parallel rendering

Parameters:

disp – pointer to a display

Returns:

number of tiles

void lv_display_set_antialiasing(lv_display_t *disp, bool en)

Enable anti-aliasing for the render engine

Parameters:

• disp – pointer to a display

• en – true/false

bool lv_display_get_antialiasing(lv_display_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

bool lv_display_is_double_buffered(lv_display_t *disp)

lv_obj_t *lv_display_get_screen_active(lv_display_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_screen_load()')

lv_obj_t *lv_display_get_screen_prev(lv_display_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

lv_obj_t *lv_display_get_layer_top(lv_display_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

lv_obj_t *lv_display_get_layer_sys(lv_display_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

lv_obj_t *lv_display_get_layer_bottom(lv_display_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 visible only if the screen is transparent.

Parameters:

disp – pointer to display (NULL to use the default screen)

Returns:

pointer to the bottom layer object

void lv_screen_load(struct _lv_obj_t *scr)

Load a screen on the default display

Parameters:

scr – pointer to a screen

void lv_screen_load_anim(lv_obj_t *scr, lv_screen_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_screen_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

lv_obj_t *lv_screen_active(void)

Get the active screen of the default display

Returns:

pointer to the active screen

lv_obj_t *lv_layer_top(void)

Get the top layer of the default display

Returns:

pointer to the top layer

lv_obj_t *lv_layer_sys(void)

Get the system layer of the default display

Returns:

pointer to the sys layer

lv_obj_t *lv_layer_bottom(void)

Get the bottom layer of the default display

Returns:

pointer to the bottom layer

void lv_display_add_event_cb(lv_display_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

uint32_t lv_display_get_event_count(lv_display_t *disp)

Get the number of event attached to a display

Parameters:

disp – pointer to a display

Returns:

number of events

lv_event_dsc_t *lv_display_get_event_dsc(lv_display_t *disp, uint32_t index)

Get an event descriptor for an event

Parameters:

• disp – pointer to a display

• index – the index of the event

Returns:

the event descriptor

bool lv_display_delete_event(lv_display_t *disp, uint32_t index)

Remove an event

Parameters:

• disp – pointer to a display

• index – the index of the event to remove

Returns:

true: and event was removed; false: no event was removed

uint32_t lv_display_remove_event_cb_with_user_data(lv_display_t *disp, lv_event_cb_t event_cb, void *user_data)

Remove an event_cb with user_data

Parameters:

• disp – pointer to a display

• event_cb – the event_cb of the event to remove

• user_data – user_data

Returns:

the count of the event removed

lv_result_t lv_display_send_event(lv_display_t *disp, lv_event_code_t code, void *param)

Send an event to a display

Parameters:

• disp – pointer to a display

• code – an event code. LV_EVENT_...

• param – optional param

Returns:

LV_RESULT_OK: disp wasn't deleted in the event.

lv_area_t *lv_event_get_invalidated_area(lv_event_t *e)

Get the area to be invalidated. Can be used in LV_EVENT_INVALIDATE_AREA

Parameters:

e – pointer to an event

Returns:

the area to invalidated (can be modified as required)

void lv_display_set_theme(lv_display_t *disp, 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

lv_theme_t *lv_display_get_theme(lv_display_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_display_get_inactive_time(const lv_display_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_display_trigger_activity(lv_display_t *disp)

Manually trigger an activity on a display

Parameters:

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

void lv_display_enable_invalidation(lv_display_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_display_is_invalidation_enabled(lv_display_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_display_get_refr_timer(lv_display_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)

void lv_display_delete_refr_timer(lv_display_t *disp)

Delete screen refresher timer

Parameters:

disp – pointer to a display

void lv_display_set_user_data(lv_display_t *disp, void *user_data)

void lv_display_set_driver_data(lv_display_t *disp, void *driver_data)

void *lv_display_get_user_data(lv_display_t *disp)

void *lv_display_get_driver_data(lv_display_t *disp)

lv_draw_buf_t *lv_display_get_buf_active(lv_display_t *disp)

void lv_display_rotate_area(lv_display_t *disp, lv_area_t *area)

Rotate an area in-place according to the display's rotation

Parameters:

• disp – pointer to a display

• area – pointer to an area to rotate

uint32_t lv_display_get_draw_buf_size(lv_display_t *disp)

Get the size of the draw buffers

Parameters:

disp – pointer to a display

Returns:

the size of the draw buffer in bytes for valid display, 0 otherwise

uint32_t lv_display_get_invalidated_draw_buf_size(lv_display_t *disp, uint32_t width, uint32_t height)

Get the size of the invalidated draw buffer. Can be used in the flush callback to get the number of bytes used in the current render buffer.

Parameters:

• disp – pointer to a display

• width – the width of the invalidated area

• height – the height of the invalidated area

Returns:

the size of the invalidated draw buffer in bytes, not accounting for any preceeding palette information for a valid display, 0 otherwise

int32_t lv_dpx(int32_t n)

For default display, computes the number of pixels (a distance or size) as if the display had 160 DPI. This allows you to specify 1/160-th fractions of an inch to get real distance on the display that will be consistent regardless of its current DPI. It ensures lv_dpx(100), for example, will have the same physical size regardless to the DPI of the display.

Parameters:

n – number of 1/160-th-inch units to compute with

Returns:

number of pixels to use to make that distance

int32_t lv_display_dpx(const lv_display_t *disp, int32_t n)

For specified display, computes the number of pixels (a distance or size) as if the display had 160 DPI. This allows you to specify 1/160-th fractions of an inch to get real distance on the display that will be consistent regardless of its current DPI. It ensures lv_dpx(100), for example, will have the same physical size regardless to the DPI of the display.

Parameters:

• disp – pointer to display whose dpi should be considered

• n – number of 1/160-th-inch units to compute with

Returns:

number of pixels to use to make that distance