# Canvas (lv_canvas) (/widgets/canvas)



Overview [#overview]

Canvas inherits from [Image](/widgets/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 [#buffer]

The Canvas needs a buffer in which to store the drawn image. Assign one with
<ApiLink name="lv_canvas_set_buffer" display="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 <ApiLink name="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 <ApiLink name="lv_malloc" />, free the buffer on the <ApiLink name="LV_EVENT_DELETE" /> event.

Canvas supports all color formats such as
<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`), populate the palette for
every index used with
<ApiLink name="lv_canvas_set_palette" display="lv_canvas_set_palette(canvas, index, color)" />. For example,
set pixels with *index==3* to red:

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

Drawing [#drawing]

Set an individual pixel with
<ApiLink name="lv_canvas_set_px" display="lv_canvas_set_px(canvas, x, y, color, opa)" />. With indexed
formats pass the palette index via the *blue* channel:
<ApiLink name="lv_color_make" display="lv_color_make(0, 0, index)" />.

<Callout type="info">
  To avoid redundant invalidation when updating many pixels in a loop:

  1. Call <ApiLink name="lv_display_enable_invalidation" /> to disable intermediate invalidation.
  2. After the loop, re-enable invalidation with <ApiLink name="lv_display_enable_invalidation" />.
  3. 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
entire canvas. Color is ignored for formats that don't support it (e.g. <ApiLink name="LV_COLOR_FORMAT_A8" />);
opacity is ignored for formats that don't support it (e.g. <ApiLink name="LV_COLOR_FORMAT_RGB565" />).

Copy a pixel array to the canvas with
<ApiLink name="lv_canvas_copy_buf" display="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
<ApiLink name="LV_COLOR_FORMAT_RGB565" />, <ApiLink name="LV_COLOR_FORMAT_RGB888" />,
<ApiLink name="LV_COLOR_FORMAT_XRGB8888" />, and <ApiLink name="LV_COLOR_FORMAT_ARGB8888" />.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Animated wave text [#animated-wave-text]

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

Text scattered along a curve [#text-scattered-along-a-curve]

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

Styling [#styling]

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