Canvas (lv_canvas)

Overview

A Canvas inherits from Image where the user can draw anything. Rectangles, texts, images, lines, arcs can be drawn here using lvgl's drawing engine. Additionally "effects" can be applied, such as rotation, zoom and blur.

Parts and Styles

LV_PART_MAIN Uses the typical rectangle style properties and image style properties.

Usage

Buffer

The Canvas needs a buffer in which stores the drawn image. To assign a buffer to a Canvas, use lv_canvas_set_buffer(canvas, buffer, width, height, LV_IMG_CF_...). Where buffer is a static buffer (not just a local variable) to hold the image of the canvas. For example, static lv_color_t buffer[LV_CANVAS_BUF_SIZE_TRUE_COLOR(width, height)]. LV_CANVAS_BUF_SIZE_... macros help to determine the size of the buffer with different color formats.

The canvas supports all the built-in color formats like LV_IMG_CF_TRUE_COLOR or LV_IMG_CF_INDEXED_2BIT. See the full list in the Color formats section.

Indexed colors

For LV_IMG_CF_INDEXED_1/2/4/8 color formats a palette needs to be initialized with lv_canvas_set_palette(canvas, 3, LV_COLOR_RED). It sets pixels with index=3 to red.

Drawing

To set a pixel's color on the canvas, use lv_canvas_set_px_color(canvas, x, y, LV_COLOR_RED). With LV_IMG_CF_INDEXED_... the index of the color needs to be passed as color. E.g. lv_color_t c; c.full = 3;

To set a pixel's opacity with LV_IMG_CF_TRUE_COLOR_ALPHA or LV_IMG_CF_ALPHA_... format on the canvas, use lv_canvas_set_px_opa(canvas, x, y, opa).

lv_canvas_fill_bg(canvas, LV_COLOR_BLUE, LV_OPA_50) fills the whole canvas to blue with 50% opacity. Note that if the current color format doesn't support colors (e.g. LV_IMG_CF_ALPHA_2BIT) the color will be ignored. Similarly, if opacity is not supported (e.g. LV_IMG_CF_TRUE_COLOR) it will be ignored.

An array of pixels can be copied to the canvas with lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height). The color format of the buffer and the canvas need to match.

To draw something to the canvas use

  • lv_canvas_draw_rect(canvas, x, y, width, heigth, &draw_dsc)

  • lv_canvas_draw_text(canvas, x, y, max_width, &draw_dsc, txt)

  • lv_canvas_draw_img(canvas, x, y, &img_src, &draw_dsc)

  • lv_canvas_draw_line(canvas, point_array, point_cnt, &draw_dsc)

  • lv_canvas_draw_polygon(canvas, points_array, point_cnt, &draw_dsc)

  • lv_canvas_draw_arc(canvas, x, y, radius, start_angle, end_angle, &draw_dsc)

draw_dsc is a lv_draw_rect/label/img/line/arc_dsc_t variable which should be first initialized with one of lv_draw_rect/label/img/line/arc_dsc_init() and then modified with the desired colors and other values.

The draw function can draw to any color format. For example, it's possible to draw a text to an LV_IMG_VF_ALPHA_8BIT canvas and use the result image as a draw mask later.

Transformations

lv_canvas_transform() can be used to rotate and/or scale the image of an image and store the result on the canvas. The function needs the following parameters:

  • canvas pointer to a canvas object to store the result of the transformation.

  • img pointer to an image descriptor to transform. Can be the image descriptor of another canvas too (lv_canvas_get_img()).

  • angle the angle of rotation (0..3600), 0.1 deg resolution

  • zoom zoom factor (256: no zoom, 512: double size, 128: half size);

  • offset_x offset X to tell where to put the result data on destination canvas

  • offset_y offset X to tell where to put the result data on destination canvas

  • pivot_x pivot X of rotation. Relative to the source canvas. Set to source width / 2 to rotate around the center

  • pivot_y pivot Y of rotation. Relative to the source canvas. Set to source height / 2 to rotate around the center

  • antialias true: apply anti-aliasing during the transformation. Looks better but slower.

Note that a canvas can't be rotated on itself. You need a source and destination canvas or image.

Blur

A given area of the canvas can be blurred horizontally with lv_canvas_blur_hor(canvas, &area, r) or vertically with lv_canvas_blur_ver(canvas, &area, r). r is the radius of the blur (greater value means more intensive burring). area is the area where the blur should be applied (interpreted relative to the canvas).

Events

No special events are sent by canvas objects. The same events are sent as for the

See the events of the Images too.

Learn more about Events.

Keys

No Keys are processed by the object type.

Learn more about Keys.

Example

Drawing on the Canvas and rotate

C code  

 GitHub
#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_BUILD_EXAMPLES

#define CANVAS_WIDTH  200
#define CANVAS_HEIGHT  150

void lv_example_canvas_1(void)
{
    lv_draw_rect_dsc_t rect_dsc;
    lv_draw_rect_dsc_init(&rect_dsc);
    rect_dsc.radius = 10;
    rect_dsc.bg_opa = LV_OPA_COVER;
    rect_dsc.bg_grad.dir = LV_GRAD_DIR_HOR;
    rect_dsc.bg_grad.stops[0].color = lv_palette_main(LV_PALETTE_RED);
    rect_dsc.bg_grad.stops[1].color = lv_palette_main(LV_PALETTE_BLUE);
    rect_dsc.border_width = 2;
    rect_dsc.border_opa = LV_OPA_90;
    rect_dsc.border_color = lv_color_white();
    rect_dsc.shadow_width = 5;
    rect_dsc.shadow_ofs_x = 5;
    rect_dsc.shadow_ofs_y = 5;

    lv_draw_label_dsc_t label_dsc;
    lv_draw_label_dsc_init(&label_dsc);
    label_dsc.color = lv_palette_main(LV_PALETTE_ORANGE);

    static lv_color_t cbuf[LV_CANVAS_BUF_SIZE_TRUE_COLOR(CANVAS_WIDTH, CANVAS_HEIGHT)];

    lv_obj_t * canvas = lv_canvas_create(lv_scr_act());
    lv_canvas_set_buffer(canvas, cbuf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_IMG_CF_TRUE_COLOR);
    lv_obj_center(canvas);
    lv_canvas_fill_bg(canvas, lv_palette_lighten(LV_PALETTE_GREY, 3), LV_OPA_COVER);

    lv_canvas_draw_rect(canvas, 70, 60, 100, 70, &rect_dsc);

    lv_canvas_draw_text(canvas, 40, 20, 100, &label_dsc, "Some text on text canvas");

    /*Test the rotation. It requires another buffer where the original image is stored.
     *So copy the current image to buffer and rotate it to the canvas*/
    static lv_color_t cbuf_tmp[CANVAS_WIDTH * CANVAS_HEIGHT];
    memcpy(cbuf_tmp, cbuf, sizeof(cbuf_tmp));
    lv_img_dsc_t img;
    img.data = (void *)cbuf_tmp;
    img.header.cf = LV_IMG_CF_TRUE_COLOR;
    img.header.w = CANVAS_WIDTH;
    img.header.h = CANVAS_HEIGHT;

    lv_canvas_fill_bg(canvas, lv_palette_lighten(LV_PALETTE_GREY, 3), LV_OPA_COVER);
    lv_canvas_transform(canvas, &img, 120, LV_IMG_ZOOM_NONE, 0, 0, CANVAS_WIDTH / 2, CANVAS_HEIGHT / 2, true);
}

#endif

MicroPython code  

 GitHub Simulator
_CANVAS_WIDTH = 200
_CANVAS_HEIGHT = 150
LV_IMG_ZOOM_NONE = 256

rect_dsc = lv.draw_rect_dsc_t()
rect_dsc.init()
rect_dsc.radius = 10
rect_dsc.bg_opa = lv.OPA.COVER
rect_dsc.bg_grad.dir = lv.GRAD_DIR.HOR
rect_dsc.bg_grad.stops[0].color = lv.palette_main(lv.PALETTE.RED)
rect_dsc.bg_grad.stops[1].color = lv.palette_main(lv.PALETTE.BLUE)
rect_dsc.border_width = 2
rect_dsc.border_opa = lv.OPA._90
rect_dsc.border_color = lv.color_white()
rect_dsc.shadow_width = 5
rect_dsc.shadow_ofs_x = 5
rect_dsc.shadow_ofs_y = 5

label_dsc = lv.draw_label_dsc_t()
label_dsc.init()
label_dsc.color = lv.palette_main(lv.PALETTE.YELLOW)

cbuf = bytearray(_CANVAS_WIDTH * _CANVAS_HEIGHT * 4)

canvas = lv.canvas(lv.scr_act())
canvas.set_buffer(cbuf, _CANVAS_WIDTH, _CANVAS_HEIGHT, lv.img.CF.TRUE_COLOR)
canvas.center()
canvas.fill_bg(lv.palette_lighten(lv.PALETTE.GREY, 3), lv.OPA.COVER)

canvas.draw_rect(70, 60, 100, 70, rect_dsc)
canvas.draw_text(40, 20, 100, label_dsc, "Some text on text canvas")

# Test the rotation. It requires another buffer where the original image is stored.
# So copy the current image to buffer and rotate it to the canvas

img = lv.img_dsc_t()
img.data = cbuf[:]
img.header.cf = lv.img.CF.TRUE_COLOR
img.header.w = _CANVAS_WIDTH
img.header.h = _CANVAS_HEIGHT

canvas.fill_bg(lv.palette_lighten(lv.PALETTE.GREY, 3), lv.OPA.COVER)
canvas.transform(img, 30, LV_IMG_ZOOM_NONE, 0, 0, _CANVAS_WIDTH // 2, _CANVAS_HEIGHT // 2, True)

Transparent Canvas with chroma keying

C code  

 GitHub
#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_BUILD_EXAMPLES

#define CANVAS_WIDTH  50
#define CANVAS_HEIGHT  50

/**
 * Create a transparent canvas with Chroma keying and indexed color format (palette).
 */
void lv_example_canvas_2(void)
{
    /*Create a button to better see the transparency*/
    lv_btn_create(lv_scr_act());

    /*Create a buffer for the canvas*/
    static lv_color_t cbuf[LV_CANVAS_BUF_SIZE_INDEXED_1BIT(CANVAS_WIDTH, CANVAS_HEIGHT)];

    /*Create a canvas and initialize its palette*/
    lv_obj_t * canvas = lv_canvas_create(lv_scr_act());
    lv_canvas_set_buffer(canvas, cbuf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_IMG_CF_INDEXED_1BIT);
    lv_canvas_set_palette(canvas, 0, LV_COLOR_CHROMA_KEY);
    lv_canvas_set_palette(canvas, 1, lv_palette_main(LV_PALETTE_RED));

    /*Create colors with the indices of the palette*/
    lv_color_t c0;
    lv_color_t c1;

    c0.full = 0;
    c1.full = 1;

    /*Red background (There is no dedicated alpha channel in indexed images so LV_OPA_COVER is ignored)*/
    lv_canvas_fill_bg(canvas, c1, LV_OPA_COVER);

    /*Create hole on the canvas*/
    uint32_t x;
    uint32_t y;
    for(y = 10; y < 30; y++) {
        for(x = 5; x < 20; x++) {
            lv_canvas_set_px_color(canvas, x, y, c0);
        }
    }

}
#endif

MicroPython code  

 GitHub Simulator
CANVAS_WIDTH   = 50
CANVAS_HEIGHT  = 50
LV_COLOR_CHROMA_KEY = lv.color_hex(0x00ff00)

def LV_IMG_BUF_SIZE_ALPHA_1BIT(w, h):
    return int(((w / 8) + 1) * h)

def LV_IMG_BUF_SIZE_INDEXED_1BIT(w, h):
    return LV_IMG_BUF_SIZE_ALPHA_1BIT(w, h) + 4 * 2

def LV_CANVAS_BUF_SIZE_INDEXED_1BIT(w, h):
    return LV_IMG_BUF_SIZE_INDEXED_1BIT(w, h)

#
# Create a transparent canvas with Chroma keying and indexed color format (palette).
#

# Create a button to better see the transparency
btn=lv.btn(lv.scr_act())

# Create a buffer for the canvas
cbuf= bytearray(LV_CANVAS_BUF_SIZE_INDEXED_1BIT(CANVAS_WIDTH, CANVAS_HEIGHT))

# Create a canvas and initialize its palette
canvas = lv.canvas(lv.scr_act())
canvas.set_buffer(cbuf, CANVAS_WIDTH, CANVAS_HEIGHT, lv.img.CF.INDEXED_1BIT)
canvas.set_palette(0, LV_COLOR_CHROMA_KEY)
canvas.set_palette(1, lv.palette_main(lv.PALETTE.RED))

# Create colors with the indices of the palette
c0 = lv.color_t()
c1 = lv.color_t()

c0.full = 0
c1.full = 1

# Red background (There is no dedicated alpha channel in indexed images so LV_OPA_COVER is ignored)
canvas.fill_bg(c1, lv.OPA.COVER)

# Create hole on the canvas
for y in range(10,30):
    for x in range(5,20):
        canvas.set_px(x, y, c0)

API

Functions

lv_obj_t *lv_canvas_create(lv_obj_t *parent)

Create a canvas object

Parameters

parent -- pointer to an object, it will be the parent of the new canvas

Returns

pointer to the created canvas

void lv_canvas_set_buffer(lv_obj_t *canvas, void *buf, lv_coord_t w, lv_coord_t h, lv_img_cf_t cf)

Set a buffer for the canvas.

Parameters

  • buf -- a buffer where the content of the canvas will be. The required size is (lv_img_color_format_get_px_size(cf) * w) / 8 * h) It can be allocated with lv_mem_alloc() or it can be statically allocated array (e.g. static lv_color_t buf[100*50]) or it can be an address in RAM or external SRAM

  • canvas -- pointer to a canvas object

  • w -- width of the canvas

  • h -- height of the canvas

  • cf -- color format. LV_IMG_CF_...

void lv_canvas_set_px_color(lv_obj_t *canvas, lv_coord_t x, lv_coord_t y, lv_color_t c)

Set the color of a pixel on the canvas

Parameters

  • canvas --

  • x -- x coordinate of the point to set

  • y -- x coordinate of the point to set

  • c -- color of the pixel

static inline void lv_canvas_set_px(lv_obj_t *canvas, lv_coord_t x, lv_coord_t y, lv_color_t c)

DEPRECATED: added only for backward compatibility

void lv_canvas_set_px_opa(lv_obj_t *canvas, lv_coord_t x, lv_coord_t y, lv_opa_t opa)

Set the opacity of a pixel on the canvas

Parameters

  • canvas --

  • x -- x coordinate of the point to set

  • y -- x coordinate of the point to set

  • opa -- opacity of the pixel (0..255)

void lv_canvas_set_palette(lv_obj_t *canvas, uint8_t id, lv_color_t c)

Set the palette color of a canvas with index format. Valid only for LV_IMG_CF_INDEXED1/2/4/8

Parameters

  • canvas -- pointer to canvas object

  • id -- the palette color to set:

    • for LV_IMG_CF_INDEXED1: 0..1

    • for LV_IMG_CF_INDEXED2: 0..3

    • for LV_IMG_CF_INDEXED4: 0..15

    • for LV_IMG_CF_INDEXED8: 0..255

  • c -- the color to set

lv_color_t lv_canvas_get_px(lv_obj_t *canvas, lv_coord_t x, lv_coord_t y)

Get the color of a pixel on the canvas

Parameters

  • canvas --

  • x -- x coordinate of the point to set

  • y -- x coordinate of the point to set

Returns

color of the point

lv_img_dsc_t *lv_canvas_get_img(lv_obj_t *canvas)

Get the image of the canvas as a pointer to an lv_img_dsc_t variable.

Parameters

canvas -- pointer to a canvas object

Returns

pointer to the image descriptor.

void lv_canvas_copy_buf(lv_obj_t *canvas, const void *to_copy, lv_coord_t x, lv_coord_t y, lv_coord_t w, lv_coord_t h)

Copy a buffer to the canvas

Parameters

  • canvas -- pointer to a canvas object

  • to_copy -- buffer to copy. The color format has to match with the canvas's buffer color format

  • x -- left side of the destination position

  • y -- top side of the destination position

  • w -- width of the buffer to copy

  • h -- height of the buffer to copy

void lv_canvas_transform(lv_obj_t *canvas, lv_img_dsc_t *img, int16_t angle, uint16_t zoom, lv_coord_t offset_x, lv_coord_t offset_y, int32_t pivot_x, int32_t pivot_y, bool antialias)

Transform and image and store the result on a canvas.

Parameters

  • canvas -- pointer to a canvas object to store the result of the transformation.

  • img -- pointer to an image descriptor to transform. Can be the image descriptor of an other canvas too (lv_canvas_get_img()).

  • angle -- the angle of rotation (0..3600), 0.1 deg resolution

  • zoom -- zoom factor (256 no zoom);

  • offset_x -- offset X to tell where to put the result data on destination canvas

  • offset_y -- offset X to tell where to put the result data on destination canvas

  • pivot_x -- pivot X of rotation. Relative to the source canvas Set to source width / 2 to rotate around the center

  • pivot_y -- pivot Y of rotation. Relative to the source canvas Set to source height / 2 to rotate around the center

  • antialias -- apply anti-aliasing during the transformation. Looks better but slower.

void lv_canvas_blur_hor(lv_obj_t *canvas, const lv_area_t *area, uint16_t r)

Apply horizontal blur on the canvas

Parameters

  • canvas -- pointer to a canvas object

  • area -- the area to blur. If NULL the whole canvas will be blurred.

  • r -- radius of the blur

void lv_canvas_blur_ver(lv_obj_t *canvas, const lv_area_t *area, uint16_t r)

Apply vertical blur on the canvas

Parameters

  • canvas -- pointer to a canvas object

  • area -- the area to blur. If NULL the whole canvas will be blurred.

  • r -- radius of the blur

void lv_canvas_fill_bg(lv_obj_t *canvas, lv_color_t color, lv_opa_t opa)

Fill the canvas with color

Parameters

  • canvas -- pointer to a canvas

  • color -- the background color

  • opa -- the desired opacity

void lv_canvas_draw_rect(lv_obj_t *canvas, lv_coord_t x, lv_coord_t y, lv_coord_t w, lv_coord_t h, const lv_draw_rect_dsc_t *draw_dsc)

Draw a rectangle on the canvas

Parameters

  • canvas -- pointer to a canvas object

  • x -- left coordinate of the rectangle

  • y -- top coordinate of the rectangle

  • w -- width of the rectangle

  • h -- height of the rectangle

  • draw_dsc -- descriptor of the rectangle

void lv_canvas_draw_text(lv_obj_t *canvas, lv_coord_t x, lv_coord_t y, lv_coord_t max_w, lv_draw_label_dsc_t *draw_dsc, const char *txt)

Draw a text on the canvas.

Parameters

  • canvas -- pointer to a canvas object

  • x -- left coordinate of the text

  • y -- top coordinate of the text

  • max_w -- max width of the text. The text will be wrapped to fit into this size

  • draw_dsc -- pointer to a valid label descriptor lv_draw_label_dsc_t

  • txt -- text to display

void lv_canvas_draw_img(lv_obj_t *canvas, lv_coord_t x, lv_coord_t y, const void *src, const lv_draw_img_dsc_t *draw_dsc)

Draw an image on the canvas

Parameters

  • canvas -- pointer to a canvas object

  • x -- left coordinate of the image

  • y -- top coordinate of the image

  • src -- image source. Can be a pointer an lv_img_dsc_t variable or a path an image.

  • draw_dsc -- pointer to a valid label descriptor lv_draw_img_dsc_t

void lv_canvas_draw_line(lv_obj_t *canvas, const lv_point_t points[], uint32_t point_cnt, const lv_draw_line_dsc_t *draw_dsc)

Draw a line on the canvas

Parameters

  • canvas -- pointer to a canvas object

  • points -- point of the line

  • point_cnt -- number of points

  • draw_dsc -- pointer to an initialized lv_draw_line_dsc_t variable

void lv_canvas_draw_polygon(lv_obj_t *canvas, const lv_point_t points[], uint32_t point_cnt, const lv_draw_rect_dsc_t *draw_dsc)

Draw a polygon on the canvas

Parameters

  • canvas -- pointer to a canvas object

  • points -- point of the polygon

  • point_cnt -- number of points

  • draw_dsc -- pointer to an initialized lv_draw_rect_dsc_t variable

void lv_canvas_draw_arc(lv_obj_t *canvas, lv_coord_t x, lv_coord_t y, lv_coord_t r, int32_t start_angle, int32_t end_angle, const lv_draw_arc_dsc_t *draw_dsc)

Draw an arc on the canvas

Parameters

  • canvas -- pointer to a canvas object

  • x -- origo x of the arc

  • y -- origo y of the arc

  • r -- radius of the arc

  • start_angle -- start angle in degrees

  • end_angle -- end angle in degrees

  • draw_dsc -- pointer to an initialized lv_draw_line_dsc_t variable

Variables

const lv_obj_class_t lv_canvas_class
struct lv_canvas_t

Public Members

lv_img_t img
lv_img_dsc_t dsc