1# Canvas (lv_canvas)
2
3
4## Overview
5
6A Canvas inherits from [Image](/widgets/core/img) where the user can draw anything.
7Rectangles, texts, images, lines, arcs can be drawn here using lvgl's drawing engine.
8Additionally "effects" can be applied, such as rotation, zoom and blur.
9
10
11## Parts and Styles
12`LV_PART_MAIN` Uses the typical rectangle style properties and image style properties.
13
14## Usage
15
16### Buffer
17The Canvas needs a buffer in which stores the drawn image.
18To assign a buffer to a Canvas, use `lv_canvas_set_buffer(canvas, buffer, width, height, LV_IMG_CF_...)`.
19Where  `buffer` is a static buffer (not just a local variable) to hold the image of the canvas.
20For example,
21`static lv_color_t buffer[LV_CANVAS_BUF_SIZE_TRUE_COLOR(width, height)]`.
22`LV_CANVAS_BUF_SIZE_...` macros help to determine the size of the buffer with different color formats.
23
24The canvas supports all the built-in color formats like `LV_IMG_CF_TRUE_COLOR` or `LV_IMG_CF_INDEXED_2BIT`.
25See the full list in the [Color formats](/overview/image.html#color-formats) section.
26
27### Indexed colors
28For `LV_IMG_CF_INDEXED_1/2/4/8` color formats a palette needs to be
29initialized with  `lv_canvas_set_palette(canvas, 3, LV_COLOR_RED)`. It sets pixels with *index=3* to red.
30
31### Drawing
32To set a pixel's color on the canvas, use `lv_canvas_set_px_color(canvas, x, y, LV_COLOR_RED)`.
33With `LV_IMG_CF_INDEXED_...`  the index of the color needs to be passed as color.
34E.g. `lv_color_t c; c.full = 3;`
35
36To 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)`.
37
38
39`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.
40Similarly, if opacity is not supported (e.g. `LV_IMG_CF_TRUE_COLOR`) it will be ignored.
41
42An array of pixels can be copied to the canvas with `lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height)`.
43The color format of the buffer and the canvas need to match.
44
45To draw something to the canvas use
46- `lv_canvas_draw_rect(canvas, x, y, width, heigth, &draw_dsc)`
47- `lv_canvas_draw_text(canvas, x, y, max_width, &draw_dsc, txt)`
48- `lv_canvas_draw_img(canvas, x, y, &img_src, &draw_dsc)`
49- `lv_canvas_draw_line(canvas, point_array, point_cnt, &draw_dsc)`
50- `lv_canvas_draw_polygon(canvas, points_array, point_cnt, &draw_dsc)`
51- `lv_canvas_draw_arc(canvas, x, y, radius, start_angle, end_angle, &draw_dsc)`
52
53`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.
54
55The 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](/overview/drawing) later.
56
57### Transformations
58`lv_canvas_transform()` can be used to rotate and/or scale the image of an image and store the result on the canvas.
59The function needs the following parameters:
60- `canvas` pointer to a canvas object to store the result of the transformation.
61- `img pointer` to an image descriptor to transform. Can be the image descriptor of another canvas too (`lv_canvas_get_img()`).
62- `angle` the angle of rotation (0..3600), 0.1 deg resolution
63- `zoom` zoom factor (256: no zoom, 512: double size, 128: half size);
64- `offset_x` offset X to tell where to put the result data on destination canvas
65- `offset_y` offset X to tell where to put the result data on destination canvas
66- `pivot_x` pivot X of rotation. Relative to the source canvas. Set to `source width / 2` to rotate around the center
67- `pivot_y` pivot Y of rotation. Relative to the source canvas. Set to `source height / 2` to rotate around the center
68- `antialias` true: apply anti-aliasing during the transformation. Looks better but slower.
69
70Note that a canvas can't be rotated on itself.  You need a source and destination canvas or image.
71
72### Blur
73A 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)`.
74`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).
75
76## Events
77No special events are sent by canvas objects.
78The same events are sent as for the
79
80See the events of the [Images](/widgets/core/img) too.
81
82Learn more about [Events](/overview/event).
83
84## Keys
85No *Keys* are processed by the object type.
86
87Learn more about [Keys](/overview/indev).
88
89## Example
90```eval_rst
91
92.. include:: ../../../examples/widgets/canvas/index.rst
93
94```
95
96## API
97
98```eval_rst
99
100.. doxygenfile:: lv_canvas.h
101  :project: lvgl
102
103```
104