# lv_draw_buf.h (/api/draw/lv_draw_buf_h) Functions [#functions] lv_draw_buf_set_flag [#lv_draw_buf_set_flag] Set a flag to a draw buffer. ```c title=" " lineNumbers=1 static void lv_draw_buf_set_flag(lv_draw_buf_t *draw_buf, lv_image_flags_t flag) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------- | ------------------------ | | `draw_buf` | | pointer to a draw buffer | | `flag` | | the flag to set | lv_draw_buf_set_palette [#lv_draw_buf_set_palette] Set the palette color of an indexed image. Valid only for `LV_COLOR_FORMAT_I1/2/4/8` ```c title=" " lineNumbers=1 void lv_draw_buf_set_palette(lv_draw_buf_t *draw_buf, uint8_t index, lv_color32_t color) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `draw_buf` | | pointer to an image descriptor | | `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 in format | lv_image_buf_set_palette [#lv_image_buf_set_palette] \> **Deprecated:** Use lv\_draw\_buf\_set\_palette instead. ```c title=" " lineNumbers=1 void lv_image_buf_set_palette(lv_image_dsc_t *dsc, uint8_t id, lv_color32_t c) ``` Parameters | Name | Type | | ----- | ------------------------------------------------------------ | | `dsc` | | | `id` | | | `c` | | lv_draw_buf_get_handlers [#lv_draw_buf_get_handlers] Get the struct which holds the callbacks for draw buf management. Custom callback can be set on the returned value ```c title=" " lineNumbers=1 lv_draw_buf_handlers_t * lv_draw_buf_get_handlers(void) ``` **Returns:** — pointer to the struct of handlers lv_draw_buf_get_font_handlers [#lv_draw_buf_get_font_handlers] ```c title=" " lineNumbers=1 lv_draw_buf_handlers_t * lv_draw_buf_get_font_handlers(void) ``` lv_draw_buf_get_image_handlers [#lv_draw_buf_get_image_handlers] ```c title=" " lineNumbers=1 lv_draw_buf_handlers_t * lv_draw_buf_get_image_handlers(void) ``` lv_draw_buf_init_with_default_handlers [#lv_draw_buf_init_with_default_handlers] Initialize the draw buffer with the default handlers. ```c title=" " lineNumbers=1 void lv_draw_buf_init_with_default_handlers(lv_draw_buf_handlers_t *handlers) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------------------------- | ------------------------------- | | `handlers` | | the draw buffer handlers to set | lv_draw_buf_handlers_init [#lv_draw_buf_handlers_init] Initialize the draw buffer with given handlers. ```c title=" " lineNumbers=1 void lv_draw_buf_handlers_init(lv_draw_buf_handlers_t *handlers, lv_draw_buf_malloc_cb_t buf_malloc_cb, lv_draw_buf_free_cb_t buf_free_cb, lv_draw_buf_copy_cb_t buf_copy_cb, lv_draw_buf_align_cb_t align_pointer_cb, lv_draw_buf_cache_operation_cb_t invalidate_cache_cb, lv_draw_buf_cache_operation_cb_t flush_cache_cb, lv_draw_buf_width_to_stride_cb_t width_to_stride_cb) ``` Parameters | Name | Type | Description | | --------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `handlers` | | the draw buffer handlers to set | | `buf_malloc_cb` | | the callback to allocate memory for the buffer | | `buf_free_cb` | | the callback to free memory of the buffer | | `buf_copy_cb` | | the callback to copy a draw buffer to an other | | `align_pointer_cb` | | the callback to align the buffer | | `invalidate_cache_cb` | | the callback to invalidate the cache of the buffer | | `flush_cache_cb` | | the callback to flush buffer | | `width_to_stride_cb` | | the callback to calculate the stride based on the width and color format | lv_draw_buf_align [#lv_draw_buf_align] Align the address of a buffer. The buffer needs to be large enough for the real data after alignment ```c title=" " lineNumbers=1 void * lv_draw_buf_align(void *buf, lv_color_format_t color_format) ``` Parameters | Name | Type | Description | | -------------- | ------------------------------------ | ------------------------------ | | `buf` | `void *` | the data to align | | `color_format` | | the color format of the buffer | **Returns:** `void *` — the aligned buffer lv_draw_buf_align_ex [#lv_draw_buf_align_ex] Align the address of a buffer with custom draw buffer handlers. The buffer needs to be large enough for the real data after alignment ```c title=" " lineNumbers=1 void * lv_draw_buf_align_ex(const lv_draw_buf_handlers_t *handlers, void *buf, lv_color_format_t color_format) ``` Parameters | Name | Type | Description | | -------------- | ---------------------------------------------------------------------------------- | ------------------------------ | | `handlers` | | the draw buffer handlers | | `buf` | `void *` | the data to align | | `color_format` | | the color format of the buffer | **Returns:** `void *` — the aligned buffer lv_draw_buf_invalidate_cache [#lv_draw_buf_invalidate_cache] Invalidate the cache of the buffer ```c title=" " lineNumbers=1 void lv_draw_buf_invalidate_cache(const lv_draw_buf_t *draw_buf, const lv_area_t *area) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `draw_buf` | | the draw buffer needs to be invalidated | | `area` | | the area to invalidate in the buffer, use NULL to invalidate the whole draw buffer address range | lv_draw_buf_flush_cache [#lv_draw_buf_flush_cache] Flush the cache of the buffer ```c title=" " lineNumbers=1 void lv_draw_buf_flush_cache(const lv_draw_buf_t *draw_buf, const lv_area_t *area) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `draw_buf` | | the draw buffer needs to be flushed | | `area` | | the area to flush in the buffer, use NULL to flush the whole draw buffer address range | lv_draw_buf_width_to_stride [#lv_draw_buf_width_to_stride] Calculate the stride in bytes based on a width and color format ```c title=" " lineNumbers=1 uint32_t lv_draw_buf_width_to_stride(uint32_t w, lv_color_format_t color_format) ``` Parameters | Name | Type | Description | | -------------- | ------------------------------------ | ------------------- | | `w` | | the width in pixels | | `color_format` | | the color format | **Returns:** — the stride in bytes lv_draw_buf_width_to_stride_ex [#lv_draw_buf_width_to_stride_ex] Calculate the stride in bytes based on a width and color format ```c title=" " lineNumbers=1 uint32_t lv_draw_buf_width_to_stride_ex(const lv_draw_buf_handlers_t *handlers, uint32_t w, lv_color_format_t color_format) ``` Parameters | Name | Type | Description | | -------------- | ---------------------------------------------------------------------------------- | ------------------------ | | `handlers` | | the draw buffer handlers | | `w` | | the width in pixels | | `color_format` | | the color format | **Returns:** — the stride in bytes lv_draw_buf_clear [#lv_draw_buf_clear] Clear an area on the buffer ```c title=" " lineNumbers=1 void lv_draw_buf_clear(lv_draw_buf_t *draw_buf, const lv_area_t *a) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------- | ---------------------------------------------------- | | `draw_buf` | | pointer to draw buffer | | `a` | | the area to clear, or NULL to clear the whole buffer | lv_draw_buf_create [#lv_draw_buf_create] Note: Eventually, lv\_draw\_buf\_malloc/free will be kept as private. For now, we use `create` to distinguish with malloc. Create an draw buf by allocating struct for `lv_draw_buf_t` and allocating a buffer for it that meets specified requirements. ```c title=" " lineNumbers=1 lv_draw_buf_t * lv_draw_buf_create(uint32_t w, uint32_t h, lv_color_format_t cf, uint32_t stride) ``` Parameters | Name | Type | Description | | -------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `w` | | the buffer width in pixels | | `h` | | the buffer height in pixels | | `cf` | | the color format for image | | `stride` | | the stride in bytes for image. Use 0 for automatic calculation based on w, cf, and global stride alignment configuration. | lv_draw_buf_create_ex [#lv_draw_buf_create_ex] Note: Eventually, lv\_draw\_buf\_malloc/free will be kept as private. For now, we use `create` to distinguish with malloc. Create an draw buf by allocating struct for `lv_draw_buf_t` and allocating a buffer for it that meets specified requirements. ```c title=" " lineNumbers=1 lv_draw_buf_t * lv_draw_buf_create_ex(const lv_draw_buf_handlers_t *handlers, uint32_t w, uint32_t h, lv_color_format_t cf, uint32_t stride) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `handlers` | | the draw buffer handlers | | `w` | | the buffer width in pixels | | `h` | | the buffer height in pixels | | `cf` | | the color format for image | | `stride` | | the stride in bytes for image. Use 0 for automatic calculation based on w, cf, and global stride alignment configuration. | lv_draw_buf_dup [#lv_draw_buf_dup] Duplicate a draw buf with same image size, stride and color format. Copy the image data too. ```c title=" " lineNumbers=1 lv_draw_buf_t * lv_draw_buf_dup(const lv_draw_buf_t *draw_buf) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------------- | ------------------------- | | `draw_buf` | | the draw buf to duplicate | **Returns:** — the duplicated draw buf on success, NULL if failed lv_draw_buf_dup_ex [#lv_draw_buf_dup_ex] Duplicate a draw buf with same image size, stride and color format. Copy the image data too. ```c title=" " lineNumbers=1 lv_draw_buf_t * lv_draw_buf_dup_ex(const lv_draw_buf_handlers_t *handlers, const lv_draw_buf_t *draw_buf) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------------------------------- | ------------------------- | | `handlers` | | the draw buffer handlers | | `draw_buf` | | the draw buf to duplicate | **Returns:** — the duplicated draw buf on success, NULL if failed lv_draw_buf_init [#lv_draw_buf_init] Initialize a draw buf with the given buffer and parameters. Clear draw buffer flag to zero. ```c title=" " lineNumbers=1 lv_result_t lv_draw_buf_init(lv_draw_buf_t *draw_buf, uint32_t w, uint32_t h, lv_color_format_t cf, uint32_t stride, void *data, uint32_t data_size) ``` Parameters | Name | Type | Description | | ----------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ | | `draw_buf` | | the draw buf to initialize | | `w` | | the buffer width in pixels | | `h` | | the buffer height in pixels | | `cf` | | the color format | | `stride` | | the stride in bytes. Use 0 for automatic calculation | | `data` | `void *` | the buffer used for drawing. Unaligned `data` will be aligned internally | | `data_size` | | the size of the buffer in bytes | **Returns:** — return LV\_RESULT\_OK on success, LV\_RESULT\_INVALID otherwise lv_draw_buf_reshape [#lv_draw_buf_reshape] Keep using the existing memory, reshape the draw buffer to the given width and height. Return NULL if data\_size is smaller than the required size. ```c title=" " lineNumbers=1 lv_draw_buf_t * lv_draw_buf_reshape(lv_draw_buf_t *draw_buf, lv_color_format_t cf, uint32_t w, uint32_t h, uint32_t stride) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `draw_buf` | | pointer to a draw buffer | | `cf` | | the new color format, use 0 or LV\_COLOR\_FORMAT\_UNKNOWN to keep using the original color format. | | `w` | | the new width in pixels | | `h` | | the new height in pixels | | `stride` | | the stride in bytes for image. Use 0 for automatic calculation. | lv_draw_buf_destroy [#lv_draw_buf_destroy] Destroy a draw buf by freeing the actual buffer if it's marked as LV\_IMAGE\_FLAGS\_ALLOCATED in header. Then free the lv\_draw\_buf\_t struct. ```c title=" " lineNumbers=1 void lv_draw_buf_destroy(lv_draw_buf_t *draw_buf) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------- | -------------------------- | | `draw_buf` | | the draw buffer to destroy | lv_draw_buf_copy [#lv_draw_buf_copy] Copy an area from a buffer to another ```c title=" " lineNumbers=1 void lv_draw_buf_copy(lv_draw_buf_t *dest, const lv_area_t *dest_area, const lv_draw_buf_t *src, const lv_area_t *src_area) ``` Parameters | Name | Type | Description | | ----------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------- | | `dest` | | pointer to the destination draw buffer | | `dest_area` | | the area to copy from the destination buffer, if NULL, use the whole buffer | | `src` | | pointer to the source draw buffer | | `src_area` | | the area to copy from the destination buffer, if NULL, use the whole buffer | `dest_area` and `src_area` should have the same width and height The default copy function required `dest` and `src` to have the same color format. Overwriting dest->handlers->buf\_copy\_cb can resolve this limitation. lv_draw_buf_goto_xy [#lv_draw_buf_goto_xy] Return pointer to the buffer at the given coordinates ```c title=" " lineNumbers=1 void * lv_draw_buf_goto_xy(const lv_draw_buf_t *buf, uint32_t x, uint32_t y) ``` Parameters | Name | Type | | ----- | ---------------------------------------------------------------- | | `buf` | | | `x` | | | `y` | | lv_draw_buf_adjust_stride [#lv_draw_buf_adjust_stride] Adjust the stride of a draw buf in place. ```c title=" " lineNumbers=1 lv_result_t lv_draw_buf_adjust_stride(lv_draw_buf_t *src, uint32_t stride) ``` Parameters | Name | Type | Description | | -------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `src` | | pointer to a draw buffer | | `stride` | | the new stride in bytes for image. Use LV\_STRIDE\_AUTO for automatic calculation. | **Returns:** — LV\_RESULT\_OK: success or LV\_RESULT\_INVALID: failed lv_draw_buf_premultiply [#lv_draw_buf_premultiply] Premultiply draw buffer color with alpha channel. If it's already premultiplied, return directly. Only color formats with alpha channel will be processed. ```c title=" " lineNumbers=1 lv_result_t lv_draw_buf_premultiply(lv_draw_buf_t *draw_buf) ``` Parameters | Name | Type | | ---------- | ---------------------------------------------------------- | | `draw_buf` | | **Returns:** — LV\_RESULT\_OK: premultiply success lv_draw_buf_has_flag [#lv_draw_buf_has_flag] Check if a draw buffer has a given flag. ```c title=" " lineNumbers=1 static bool lv_draw_buf_has_flag(const lv_draw_buf_t *draw_buf, lv_image_flags_t flag) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------------- | ------------------------ | | `draw_buf` | | pointer to a draw buffer | | `flag` | | the flag to check | **Returns:** — true: the flag is set, false: the flag is not set lv_draw_buf_clear_flag [#lv_draw_buf_clear_flag] Clear a flag from a draw buffer. ```c title=" " lineNumbers=1 static void lv_draw_buf_clear_flag(lv_draw_buf_t *draw_buf, lv_image_flags_t flag) ``` Parameters | Name | Type | Description | | ---------- | ---------------------------------------------------------- | ------------------------ | | `draw_buf` | | pointer to a draw buffer | | `flag` | | the flag to clear | lv_draw_buf_from_image [#lv_draw_buf_from_image] As of now, draw buf share same definition as . And is interchangeable with . ```c title=" " lineNumbers=1 lv_result_t lv_draw_buf_from_image(lv_draw_buf_t *buf, const lv_image_dsc_t *img) ``` Parameters | Name | Type | | ----- | ------------------------------------------------------------------ | | `buf` | | | `img` | | lv_draw_buf_to_image [#lv_draw_buf_to_image] ```c title=" " lineNumbers=1 void lv_draw_buf_to_image(const lv_draw_buf_t *buf, lv_image_dsc_t *img) ``` Parameters | Name | Type | | ----- | ---------------------------------------------------------------- | | `buf` | | | `img` | | lv_image_buf_free [#lv_image_buf_free] \> **Deprecated:** Use lv\_draw\_buffer\_create/destroy instead. Free the data pointer and dsc struct of an image. ```c title=" " lineNumbers=1 void lv_image_buf_free(lv_image_dsc_t *dsc) ``` Parameters | Name | Type | | ----- | ------------------------------------------------------------ | | `dsc` | | Structs [#structs] \_lv_draw_buf_t [#_lv_draw_buf_t] | Member | Type | Description | | ---------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------- | | `header` | | | | `data_size` | | Total buf size in bytes | | `data` | | | | `unaligned_data` | `void *` | Unaligned address of `data`, used internally by lvgl | | `handlers` | | draw buffer alloc/free ops. | Typedefs [#typedefs] lv_draw_buf_malloc_cb_t [#lv_draw_buf_malloc_cb_t] ```c title=" " lineNumbers=1 typedef void *(* lv_draw_buf_malloc_cb_t) (size_t size, lv_color_format_t color_format) ``` * `lv_draw_buf_handlers_init` — param `buf_malloc_cb` lv_draw_buf_free_cb_t [#lv_draw_buf_free_cb_t] ```c title=" " lineNumbers=1 typedef void(* lv_draw_buf_free_cb_t) (void *draw_buf) ``` * `lv_draw_buf_handlers_init` — param `buf_free_cb` lv_draw_buf_copy_cb_t [#lv_draw_buf_copy_cb_t] ```c title=" " lineNumbers=1 typedef void(* lv_draw_buf_copy_cb_t) (lv_draw_buf_t *dest, const lv_area_t *dest_area, const lv_draw_buf_t *src, const lv_area_t *src_area) ``` * `lv_draw_buf_handlers_init` — param `buf_copy_cb` lv_draw_buf_align_cb_t [#lv_draw_buf_align_cb_t] ```c title=" " lineNumbers=1 typedef void *(* lv_draw_buf_align_cb_t) (void *buf, lv_color_format_t color_format) ``` * `lv_draw_buf_handlers_init` — param `align_pointer_cb` lv_draw_buf_cache_operation_cb_t [#lv_draw_buf_cache_operation_cb_t] ```c title=" " lineNumbers=1 typedef void(* lv_draw_buf_cache_operation_cb_t) (const lv_draw_buf_t *draw_buf, const lv_area_t *area) ``` * `lv_draw_buf_handlers_init` — param `invalidate_cache_cb` * `lv_draw_buf_handlers_init` — param `flush_cache_cb` lv_draw_buf_width_to_stride_cb_t [#lv_draw_buf_width_to_stride_cb_t] ```c title=" " lineNumbers=1 typedef uint32_t(* lv_draw_buf_width_to_stride_cb_t) (uint32_t w, lv_color_format_t color_format) ``` * `lv_draw_buf_handlers_init` — param `width_to_stride_cb` Macros [#macros] LV_STRIDE_AUTO [#lv_stride_auto] ```c title=" " lineNumbers=1 #define LV_STRIDE_AUTO 0 ``` Use this value to let LVGL calculate stride automatically LV_DRAW_BUF_STRIDE [#lv_draw_buf_stride] ```c title=" " lineNumbers=1 #define LV_DRAW_BUF_STRIDE(w, cf) \ LV_ROUND_UP(((w) * LV_COLOR_FORMAT_GET_BPP(cf) + 7) / 8, LV_DRAW_BUF_STRIDE_ALIGN) ``` Stride alignment for draw buffers. It may vary between different color formats and hardware. Refine it to suit your needs. LV_DRAW_BUF_SIZE [#lv_draw_buf_size] ```c title=" " lineNumbers=1 #define LV_DRAW_BUF_SIZE(w, h, cf) \ (LV_DRAW_BUF_STRIDE(w, cf) * (h) + LV_DRAW_BUF_ALIGN + \ LV_COLOR_INDEXED_PALETTE_SIZE(cf) * sizeof(lv_color32_t)) ``` Allocate a slightly larger buffer, so we can adjust the start address to meet alignment LV_DRAW_BUF_DEFINE_STATIC [#lv_draw_buf_define_static] ```c title=" " lineNumbers=1 #define LV_DRAW_BUF_DEFINE_STATIC(name, _w, _h, _cf) \ static LV_ATTRIBUTE_MEM_ALIGN uint8_t buf_##name[LV_DRAW_BUF_SIZE(_w, _h, _cf)]; \ static lv_draw_buf_t name = { \ .header = { \ .magic = LV_IMAGE_HEADER_MAGIC, \ .cf = (_cf), \ .flags = LV_IMAGE_FLAGS_MODIFIABLE, \ .w = (_w), \ .h = (_h), \ .stride = LV_DRAW_BUF_STRIDE(_w, _cf), \ .reserved_2 = 0, \ }, \ .data_size = sizeof(buf_##name), \ .data = buf_##name, \ .unaligned_data = buf_##name, \ } ``` Define a static draw buffer with the given width, height, and color format. Stride alignment is set to LV\_DRAW\_BUF\_STRIDE\_ALIGN. For platform that needs special buffer alignment, call LV\_DRAW\_BUF\_INIT\_STATIC. LV_DRAW_BUF_INIT_STATIC [#lv_draw_buf_init_static] ```c title=" " lineNumbers=1 #define LV_DRAW_BUF_INIT_STATIC(name) \ do { \ lv_image_header_t * header = &name.header; \ lv_draw_buf_init(&name, header->w, header->h, (lv_color_format_t)header->cf, header->stride, buf_##name, sizeof(buf_##name)); \ lv_draw_buf_set_flag(&name, LV_IMAGE_FLAGS_MODIFIABLE); \ } while(0) ``` Dependencies [#dependencies]