# lv_canvas.h (/api/widgets/canvas/lv_canvas_h)
Functions [#functions]
lv_canvas_set_buffer [#lv_canvas_set_buffer]
Set a buffer for the canvas.
Use instead if you need to set a buffer with alignment requirement.
```c title=" " lineNumbers=1
void lv_canvas_set_buffer(lv_obj_t *obj, void *buf, int32_t w, int32_t h, lv_color_format_t cf)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `obj` | | pointer to a canvas object |
| `buf` | `void *` | buffer where content of canvas will be. The required size is (lv\_image\_color\_format\_get\_px\_size(cf) \* w) / 8 \* h) It can be allocated with or it can be statically allocated array (e.g. static buf\[100\*50]) or it can be an address in RAM or external SRAM |
| `w` | | width of canvas |
| `h` | | height of canvas |
| `cf` | | color format. `LV_COLOR_FORMAT...` |
lv_canvas_set_draw_buf [#lv_canvas_set_draw_buf]
Set a draw buffer for the canvas. A draw buffer either can be allocated by or defined statically by `LV_DRAW_BUF_DEFINE_STATIC`. When buffer start address and stride has alignment requirement, it's recommended to use `lv_draw_buf_create`.
```c title=" " lineNumbers=1
void lv_canvas_set_draw_buf(lv_obj_t *obj, lv_draw_buf_t *draw_buf)
```
Parameters
| Name | Type | Description |
| ---------- | ---------------------------------------------------------- | -------------------------- |
| `obj` | | pointer to a canvas object |
| `draw_buf` | | pointer to a draw buffer |
lv_canvas_set_px [#lv_canvas_set_px]
Set a pixel's color and opacity
```c title=" " lineNumbers=1
void lv_canvas_set_px(lv_obj_t *obj, int32_t x, int32_t y, lv_color_t color, lv_opa_t opa)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------- |
| `obj` | | pointer to a canvas |
| `x` | | X coordinate of the pixel |
| `y` | | Y coordinate of the pixel |
| `color` | | the color |
| `opa` | | the opacity |
The following color formats are supported LV\_COLOR\_FORMAT\_I1/2/4/8, LV\_COLOR\_FORMAT\_A8, LV\_COLOR\_FORMAT\_RGB565, LV\_COLOR\_FORMAT\_RGB888, LV\_COLOR\_FORMAT\_XRGB8888, LV\_COLOR\_FORMAT\_ARGB8888
this function invalidates the canvas object every time, for best performance, if you're changing a lot of pixels in a loop, call `lv_display_enable_invalidation` before the loop starts so the invalidation isn't done on every call
lv_canvas_set_palette [#lv_canvas_set_palette]
Set the palette color of a canvas for index format. Valid only for `LV_COLOR_FORMAT_I1/2/4/8`
```c title=" " lineNumbers=1
void lv_canvas_set_palette(lv_obj_t *obj, uint8_t index, lv_color32_t color)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `obj` | | pointer to canvas object |
| `index` | | the palette color to set:
- for `LV_COLOR_FORMAT_I1`: 0..1
- for `LV_COLOR_FORMAT_I2`: 0..3
- for `LV_COLOR_FORMAT_I4`: 0..15
- for `LV_COLOR_FORMAT_I8`: 0..255 |
| `color` | | the color to set |
lv_canvas_get_draw_buf [#lv_canvas_get_draw_buf]
```c title=" " lineNumbers=1
lv_draw_buf_t * lv_canvas_get_draw_buf(lv_obj_t *obj)
```
Parameters
| Name | Type |
| ----- | ------------------------------------------------ |
| `obj` | |
lv_canvas_get_px [#lv_canvas_get_px]
Get a pixel's color and opacity
```c title=" " lineNumbers=1
lv_color32_t lv_canvas_get_px(lv_obj_t *obj, int32_t x, int32_t y)
```
Parameters
| Name | Type | Description |
| ----- | ------------------------------------------------ | ------------------------- |
| `obj` | | pointer to a canvas |
| `x` | | X coordinate of the pixel |
| `y` | | Y coordinate of the pixel |
**Returns:** — ARGB8888 color of the pixel
lv_canvas_get_image [#lv_canvas_get_image]
Get the image of the canvas as a pointer to an variable.
```c title=" " lineNumbers=1
lv_image_dsc_t * lv_canvas_get_image(lv_obj_t *canvas)
```
Parameters
| Name | Type | Description |
| -------- | ------------------------------------------------ | -------------------------- |
| `canvas` | | pointer to a canvas object |
**Returns:** — pointer to the image descriptor.
lv_canvas_get_buf [#lv_canvas_get_buf]
Return the pointer for the buffer. It's recommended to use this function instead of the buffer form the return value of as is can be aligned
```c title=" " lineNumbers=1
const void * lv_canvas_get_buf(lv_obj_t *canvas)
```
Parameters
| Name | Type | Description |
| -------- | ------------------------------------------------ | -------------------------- |
| `canvas` | | pointer to a canvas object |
**Returns:** `const void *` — pointer to the buffer
lv_canvas_create [#lv_canvas_create]
Create a canvas object
```c title=" " lineNumbers=1
lv_obj_t * lv_canvas_create(lv_obj_t *parent)
```
Parameters
| Name | Type | Description |
| -------- | ------------------------------------------------ | ------------------------------------------------------------- |
| `parent` | | pointer to an object, it will be the parent of the new canvas |
**Returns:** — pointer to the created canvas
lv_canvas_copy_buf [#lv_canvas_copy_buf]
Copy a buffer to the canvas
```c title=" " lineNumbers=1
void lv_canvas_copy_buf(lv_obj_t *obj, const lv_area_t *canvas_area, lv_draw_buf_t *src_buf, const lv_area_t *src_area)
```
Parameters
| Name | Type | Description |
| ------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| `obj` | | pointer to a canvas object |
| `canvas_area` | | the area of the canvas to copy the new data to |
| `src_buf` | | pointer to a buffer holding the source data |
| `src_area` | | the area of the source buffer to copy from. If NULL, copy the whole buffer. |
canvas\_area and src\_area should be the same size. If canvas\_area and the size of src\_buf are the same, src\_area can be left NULL.
lv_canvas_fill_bg [#lv_canvas_fill_bg]
Fill the canvas with color
```c title=" " lineNumbers=1
void lv_canvas_fill_bg(lv_obj_t *obj, lv_color_t color, lv_opa_t opa)
```
Parameters
| Name | Type | Description |
| ------- | ------------------------------------------------ | -------------------- |
| `obj` | | pointer to a canvas |
| `color` | | the background color |
| `opa` | | the desired opacity |
lv_canvas_init_layer [#lv_canvas_init_layer]
Initialize a layer to use LVGL's generic draw functions (lv\_draw\_rect/label/...) on the canvas. Needs to be usd in pair with `lv_canvas_finish_layer`.
```c title=" " lineNumbers=1
void lv_canvas_init_layer(lv_obj_t *canvas, lv_layer_t *layer)
```
Parameters
| Name | Type | Description |
| -------- | ---------------------------------------------------- | ----------------------------------------- |
| `canvas` | | pointer to a canvas |
| `layer` | | pointer to a layer variable to initialize |
lv_canvas_finish_layer [#lv_canvas_finish_layer]
Wait until all the drawings are finished on layer. Needs to be usd in pair with `lv_canvas_init_layer`.
```c title=" " lineNumbers=1
void lv_canvas_finish_layer(lv_obj_t *canvas, lv_layer_t *layer)
```
Parameters
| Name | Type | Description |
| -------- | ---------------------------------------------------- | ------------------------------ |
| `canvas` | | pointer to a canvas |
| `layer` | | pointer to a layer to finalize |
lv_canvas_buf_size [#lv_canvas_buf_size]
Just a wrapper to `LV_CANVAS_BUF_SIZE` for bindings.
```c title=" " lineNumbers=1
uint32_t lv_canvas_buf_size(int32_t w, int32_t h, uint8_t bpp, uint8_t stride)
```
Parameters
| Name | Type |
| -------- | -------------------------- |
| `w` | |
| `h` | |
| `bpp` | |
| `stride` | |
Macros [#macros]
LV_CANVAS_BUF_SIZE [#lv_canvas_buf_size-1]
```c title=" " lineNumbers=1
#define LV_CANVAS_BUF_SIZE(w, h, bpp, stride) \
(((((w * bpp + 7) >> 3) + stride - 1) & ~(stride - 1)) * h + LV_DRAW_BUF_ALIGN)
```
Variables [#variables]
lv_canvas_class [#lv_canvas_class]
```c title=" " lineNumbers=1
const lv_obj_class_t lv_canvas_class
```
Dependencies [#dependencies]