Canvas (lv_canvas)

Draw rectangles, text, images, lines, arcs, and more using LVGL's drawing engine.

Overview

Canvas inherits from Image and adds drawing on top. With LVGL's drawing engine you can draw rectangles, text, images, lines, arcs, and more straight into the canvas.

Buffer

The Canvas needs a buffer in which to store the drawn image. Assign one with lv_canvas_set_buffer(canvas, buffer, width, height, LV_COLOR_FORMAT_...).

buffer must remain valid for the entire lifecycle of the canvas. It can be allocated with lv_malloc or declared as a static array:

uint8_t* buffer = lv_malloc(100 * 50 * 4)
static uint8_t buffer[100 * 50 * 4]
static uint8_t buffer[LV_CANVAS_BUF_SIZE(width, height, bits_per_pixel, stride_in_bytes)]

When using lv_malloc, free the buffer on the LV_EVENT_DELETE event.

Canvas supports all color formats such as LV_COLOR_FORMAT_ARGB8888 or LV_COLOR_FORMAT_I2. See the full list in the Color formats section.

Indexed colors

For indexed color formats (LV_COLOR_FORMAT_I1/2/4/8), populate the palette for every index used with lv_canvas_set_palette(canvas, index, color). For example, set pixels with index==3 to red:

lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000))

Drawing

Set an individual pixel with lv_canvas_set_px(canvas, x, y, color, opa). With indexed formats pass the palette index via the blue channel: lv_color_make(0, 0, index).

To avoid redundant invalidation when updating many pixels in a loop:

Call lv_display_enable_invalidation to disable intermediate invalidation.
After the loop, re-enable invalidation with lv_display_enable_invalidation.
Call lv_obj_invalidate once.

lv_canvas_fill_bg(canvas, lv_color_hex(0x00ff00), LV_OPA_50) fills the entire canvas. Color is ignored for formats that don't support it (e.g. LV_COLOR_FORMAT_A8); opacity is ignored for formats that don't support it (e.g. LV_COLOR_FORMAT_RGB565).

Copy a pixel array to the canvas with lv_canvas_copy_buf(canvas, canvas_area, src_buf, src_area). The buffer and canvas color formats must match. If both areas are the same size, src_area can be NULL.

The draw functions work with any format LVGL can render to — typically LV_COLOR_FORMAT_RGB565, LV_COLOR_FORMAT_RGB888, LV_COLOR_FORMAT_XRGB8888, and LV_COLOR_FORMAT_ARGB8888.

Styling

LV_PART_MAIN Uses the typical background and image style properties.

Canvas (lv_canvas)

On this page