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