# Canvas (lv_canvas) (/widgets/canvas)



Overview [#overview]

A Canvas inherits from [Image](/widgets/image) and extends it, enabling the user to draw
anything. Rectangles, text, images, lines, arcs, etc. can be drawn here using
LVGL's extensive drawing engine.

Parts and Styles [#parts-and-styles]

* <ApiLink name="LV_PART_MAIN" /> Uses the [typical background](/common-widget-features/styles/overview)
  and image style properties.

Usage [#usage]

Buffer [#buffer]

The Canvas needs a buffer in which to store the drawn image. To assign a
buffer to a Canvas, use
<ApiLink name="lv_canvas_set_buffer" display="lv_canvas_set_buffer(canvas, buffer, width, height, LV_COLOR_FORMAT_...)" />.

Where `buffer` has to be valid for the entire lifecycle of the object created by <ApiLink name="lv_canvas_create" />.
It can be allocated by using <ApiLink name="lv_malloc" /> or a statically allocated array.

For example, for a 100x50 ARGB8888 buffer you can use:

* `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)]`

In case you choose the <ApiLink name="lv_malloc" /> way, it is up to the programmer to free the memory area, for example, on <ApiLink name="LV_EVENT_DELETE" /> event.

Canvas supports all the color formats like
<ApiLink name="LV_COLOR_FORMAT_ARGB8888" /> or <ApiLink name="LV_COLOR_FORMAT_I2" />. See the full
list in the [Color formats](/main-modules/images/color_formats) section.

Indexed colors [#indexed-colors]

For indexed color formats (`LV_COLOR_FORMAT_I1/2/4/8`), the palette needs to be
populated for all palette indices that will be used using
<ApiLink name="lv_canvas_set_palette" display="lv_canvas_set_palette(canvas, index, color)" />.  For example, the following
sets pixels with *index==3* to red.

```c title=" " lineNumbers=1
lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000))
```

Drawing [#drawing]

To set an individual pixel's color on the Canvas, use
<ApiLink name="lv_canvas_set_px" display="lv_canvas_set_px(canvas, x, y, color, opa)" />.  With indexed color formats
(`LV_COLOR_FORMAT_I1/2/4/8`) pass the color index as the `color` argument by using
the *blue* channel in the `color` value, e.g. <ApiLink name="lv_color_make" display="lv_color_make(0, 0, index)" />.

<Callout type="info">
  To prevent the canvas from being redundantly invalidated for every single pixel update in a loop:

  1. Use <ApiLink name="lv_display_enable_invalidation" /> to disable intermediate object invalidation
  2. After the loop is done, re-enable the display invalidation (via <ApiLink name="lv_display_enable_invalidation" />)
  3. With the invalidation re-enabled, call <ApiLink name="lv_obj_invalidate" /> once.
</Callout>

<ApiLink name="lv_canvas_fill_bg" display="lv_canvas_fill_bg(canvas, lv_color_hex(0x00ff00), 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. <ApiLink name="LV_COLOR_FORMAT_A8" />) the color will be
ignored. Similarly, if opacity is not supported
(e.g. <ApiLink name="LV_COLOR_FORMAT_RGB565" />), it will be ignored.

An array of pixels can be copied to the Canvas with
<ApiLink name="lv_canvas_copy_buf" display="lv_canvas_copy_buf(canvas, canvas_area, src_buf, src_area)" />. The
color format of the buffer and Canvas need to match. If the canvas area and source buffer
are the same size, the source area can be left NULL.

To draw something to the Canvas use LVGL's draw functions directly. See the examples for more details.

The draw functions can draw to any color format to which LVGL can render. Typically this means
<ApiLink name="LV_COLOR_FORMAT_RGB565" />, <ApiLink name="LV_COLOR_FORMAT_RGB888" />,
<ApiLink name="LV_COLOR_FORMAT_XRGB888" />, and <ApiLink name="LV_COLOR_FORMAT_ARGB8888" />.

Events [#events]

No special events are sent by Canvas Widgets.

<Callout type="info" title="Further Reading">
  Learn more about [Events](/common-widget-features/events) emitted by all Widgets.

  Learn more about [events](/common-widget-features/events).
</Callout>

Keys [#keys]

No *Keys* are processed by Canvas Widgets.

<Callout type="info" title="Further Reading">
  Learn more about [Keys](/main-modules/indev/keypad).
</Callout>

Examples [#examples]

Drawing on the Canvas and rotate [#drawing-on-the-canvas-and-rotate]

<LvglExample name="lv_example_canvas_1" path="widgets/canvas/lv_example_canvas_1" />

Transparent Canvas with chroma keying [#transparent-canvas-with-chroma-keying]

<LvglExample name="lv_example_canvas_2" path="widgets/canvas/lv_example_canvas_2" />

Draw a rectangle to the canvas [#draw-a-rectangle-to-the-canvas]

<LvglExample name="lv_example_canvas_3" path="widgets/canvas/lv_example_canvas_3" />

Draw a label to the canvas [#draw-a-label-to-the-canvas]

<LvglExample name="lv_example_canvas_4" path="widgets/canvas/lv_example_canvas_4" />

Draw an arc to the canvas [#draw-an-arc-to-the-canvas]

<LvglExample name="lv_example_canvas_5" path="widgets/canvas/lv_example_canvas_5" />

Draw an image to the canvas [#draw-an-image-to-the-canvas]

<LvglExample name="lv_example_canvas_6" path="widgets/canvas/lv_example_canvas_6" />

Draw a line to the canvas [#draw-a-line-to-the-canvas]

<LvglExample name="lv_example_canvas_7" path="widgets/canvas/lv_example_canvas_7" />

Draw a vector graphic to the canvas [#draw-a-vector-graphic-to-the-canvas]

<LvglExample name="lv_example_canvas_8" path="widgets/canvas/lv_example_canvas_8" />

Draw a triangle to the canvas [#draw-a-triangle-to-the-canvas]

<LvglExample name="lv_example_canvas_9" path="widgets/canvas/lv_example_canvas_9" />

Blur an area on the canvas [#blur-an-area-on-the-canvas]

<LvglExample name="lv_example_canvas_10" path="widgets/canvas/lv_example_canvas_10" />

Draw Fancy Letter Effects [#draw-fancy-letter-effects]

<LvglExample name="lv_example_canvas_11" path="widgets/canvas/lv_example_canvas_11" />

Draw Fancy Letter Effects 2 [#draw-fancy-letter-effects-2]

<LvglExample name="lv_example_canvas_12" path="widgets/canvas/lv_example_canvas_12" />

API [#api]