lv_draw_buf.h

API reference for lv_draw_buf.h

Summary

Functions

public/draw/lv_draw_buf.h:341function

lv_draw_buf_set_flag

Set a flag to a draw buffer.

void lv_draw_buf_set_flag(lv_draw_buf_t *draw_buf, lv_image_flags_t flag)

Name	Type	Description
`draw_buf`	`lv_draw_buf_t *`	pointer to a draw buffer
`flag`	`lv_image_flags_t`	the flag to set

public/draw/lv_draw_buf.h:369function

lv_draw_buf_set_palette

Set the palette color of an indexed image. Valid only for LV_COLOR_FORMAT_I1/2/4/8

void lv_draw_buf_set_palette(lv_draw_buf_t *draw_buf, uint8_t index, lv_color32_t color)

Name	Type	Description
`draw_buf`	`lv_draw_buf_t *`	pointer to an image descriptor
`index`	`uint8_t`	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`	`lv_color32_t`	the color to set in `lv_color32_t` format

public/draw/lv_draw_buf.h:375function

lv_image_buf_set_palette

> Deprecated: Use lv_draw_buf_set_palette instead.

void lv_image_buf_set_palette(lv_image_dsc_t *dsc, uint8_t id, lv_color32_t c)

Name	Type
`dsc`	`lv_image_dsc_t *`
`id`	`uint8_t`
`c`	`lv_color32_t`

public/draw/lv_draw_buf.h:138function

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

lv_draw_buf_handlers_t * lv_draw_buf_get_handlers(void)

Returns: lv_draw_buf_handlers_t * — pointer to the struct of handlers

public/draw/lv_draw_buf.h:139function

lv_draw_buf_get_font_handlers

lv_draw_buf_handlers_t * lv_draw_buf_get_font_handlers(void)

public/draw/lv_draw_buf.h:140function

lv_draw_buf_get_image_handlers

lv_draw_buf_handlers_t * lv_draw_buf_get_image_handlers(void)

public/draw/lv_draw_buf.h:110function

lv_draw_buf_init_with_default_handlers

Initialize the draw buffer with the default handlers.

void lv_draw_buf_init_with_default_handlers(lv_draw_buf_handlers_t *handlers)

Name	Type	Description
`handlers`	`lv_draw_buf_handlers_t *`	the draw buffer handlers to set

public/draw/lv_draw_buf.h:124function

lv_draw_buf_handlers_init

Initialize the draw buffer with given handlers.

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)

Name	Type	Description
`handlers`	`lv_draw_buf_handlers_t *`	the draw buffer handlers to set
`buf_malloc_cb`	`lv_draw_buf_malloc_cb_t`	the callback to allocate memory for the buffer
`buf_free_cb`	`lv_draw_buf_free_cb_t`	the callback to free memory of the buffer
`buf_copy_cb`	`lv_draw_buf_copy_cb_t`	the callback to copy a draw buffer to an other
`align_pointer_cb`	`lv_draw_buf_align_cb_t`	the callback to align the buffer
`invalidate_cache_cb`	`lv_draw_buf_cache_operation_cb_t`	the callback to invalidate the cache of the buffer
`flush_cache_cb`	`lv_draw_buf_cache_operation_cb_t`	the callback to flush buffer
`width_to_stride_cb`	`lv_draw_buf_width_to_stride_cb_t`	the callback to calculate the stride based on the width and color format

public/draw/lv_draw_buf.h:149function

lv_draw_buf_align

Align the address of a buffer. The buffer needs to be large enough for the real data after alignment

void * lv_draw_buf_align(void *buf, lv_color_format_t color_format)

Name	Type	Description
`buf`	`void *`	the data to align
`color_format`	`lv_color_format_t`	the color format of the buffer

Returns: void * — the aligned buffer

public/draw/lv_draw_buf.h:159function

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

void * lv_draw_buf_align_ex(const lv_draw_buf_handlers_t *handlers, void *buf, lv_color_format_t color_format)

Name	Type	Description
`handlers`	`const lv_draw_buf_handlers_t *`	the draw buffer handlers
`buf`	`void *`	the data to align
`color_format`	`lv_color_format_t`	the color format of the buffer

Returns: void * — the aligned buffer

public/draw/lv_draw_buf.h:167function

lv_draw_buf_invalidate_cache

Invalidate the cache of the buffer

void lv_draw_buf_invalidate_cache(const lv_draw_buf_t *draw_buf, const lv_area_t *area)

Name	Type	Description
`draw_buf`	`const lv_draw_buf_t *`	the draw buffer needs to be invalidated
`area`	`const lv_area_t *`	the area to invalidate in the buffer. May be `NULL`. When NULL the whole draw buffer address range is invalidated

public/draw/lv_draw_buf.h:175function

lv_draw_buf_flush_cache

Flush the cache of the buffer

void lv_draw_buf_flush_cache(const lv_draw_buf_t *draw_buf, const lv_area_t *area)

Name	Type	Description
`draw_buf`	`const lv_draw_buf_t *`	the draw buffer needs to be flushed
`area`	`const lv_area_t *`	the area to flush in the buffer. May be `NULL`. When NULL the whole draw buffer address range is flushed

public/draw/lv_draw_buf.h:183function

lv_draw_buf_width_to_stride

Calculate the stride in bytes based on a width and color format

uint32_t lv_draw_buf_width_to_stride(uint32_t w, lv_color_format_t color_format)

Name	Type	Description
`w`	`uint32_t`	the width in pixels
`color_format`	`lv_color_format_t`	the color format

Returns: uint32_t — the stride in bytes

public/draw/lv_draw_buf.h:192function

lv_draw_buf_width_to_stride_ex

Calculate the stride in bytes based on a width and color format

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)

Name	Type	Description
`handlers`	`const lv_draw_buf_handlers_t *`	the draw buffer handlers
`w`	`uint32_t`	the width in pixels
`color_format`	`lv_color_format_t`	the color format

Returns: uint32_t — the stride in bytes

public/draw/lv_draw_buf.h:200function

lv_draw_buf_clear

Clear an area on the buffer

void lv_draw_buf_clear(lv_draw_buf_t *draw_buf, const lv_area_t *a)

Name	Type	Description
`draw_buf`	`lv_draw_buf_t *`	pointer to draw buffer
`a`	`const lv_area_t *`	the area to clear May be `NULL`.. When NULL the whole buffer is cleared

public/draw/lv_draw_buf.h:216function

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.

lv_draw_buf_t * lv_draw_buf_create(uint32_t w, uint32_t h, lv_color_format_t cf, uint32_t stride)

Name	Type	Description
`w`	`uint32_t`	the buffer width in pixels
`h`	`uint32_t`	the buffer height in pixels
`cf`	`lv_color_format_t`	the color format for image
`stride`	`uint32_t`	the stride in bytes for image. Use 0 for automatic calculation based on w, cf, and global stride alignment configuration.

public/draw/lv_draw_buf.h:232function

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.

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)

Name	Type	Description
`handlers`	`const lv_draw_buf_handlers_t *`	the draw buffer handlers
`w`	`uint32_t`	the buffer width in pixels
`h`	`uint32_t`	the buffer height in pixels
`cf`	`lv_color_format_t`	the color format for image
`stride`	`uint32_t`	the stride in bytes for image. Use 0 for automatic calculation based on w, cf, and global stride alignment configuration.

public/draw/lv_draw_buf.h:240function

lv_draw_buf_dup

Duplicate a draw buf with same image size, stride and color format. Copy the image data too.

lv_draw_buf_t * lv_draw_buf_dup(const lv_draw_buf_t *draw_buf)

Name	Type	Description
`draw_buf`	`const lv_draw_buf_t *`	the draw buf to duplicate

Returns: lv_draw_buf_t * — the duplicated draw buf on success, NULL if failed

public/draw/lv_draw_buf.h:248function

lv_draw_buf_dup_ex

Duplicate a draw buf with same image size, stride and color format. Copy the image data too.

lv_draw_buf_t * lv_draw_buf_dup_ex(const lv_draw_buf_handlers_t *handlers, const lv_draw_buf_t *draw_buf)

Name	Type	Description
`handlers`	`const lv_draw_buf_handlers_t *`	the draw buffer handlers
`draw_buf`	`const lv_draw_buf_t *`	the draw buf to duplicate

Returns: lv_draw_buf_t * — the duplicated draw buf on success, NULL if failed

public/draw/lv_draw_buf.h:262function

lv_draw_buf_init

Initialize a draw buf with the given buffer and parameters. Clear draw buffer flag to zero.

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)

Name	Type	Description
`draw_buf`	`lv_draw_buf_t *`	the draw buf to initialize
`w`	`uint32_t`	the buffer width in pixels
`h`	`uint32_t`	the buffer height in pixels
`cf`	`lv_color_format_t`	the color format
`stride`	`uint32_t`	the stride in bytes. Use 0 for automatic calculation
`data`	`void *`	the buffer used for drawing. Unaligned `data` will be aligned internally Might be NULL as long as width and height are 0
`data_size`	`uint32_t`	the size of the buffer in bytes

Returns: lv_result_t — return LV_RESULT_OK on success, LV_RESULT_INVALID otherwise

public/draw/lv_draw_buf.h:274function

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.

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)

Name	Type	Description
`draw_buf`	`lv_draw_buf_t *`	pointer to a draw buffer May be `NULL`.. When NULL, it returns NULL
`cf`	`lv_color_format_t`	the new color format, use 0 or LV_COLOR_FORMAT_UNKNOWN to keep using the original color format.
`w`	`uint32_t`	the new width in pixels
`h`	`uint32_t`	the new height in pixels
`stride`	`uint32_t`	the stride in bytes for image. Use 0 for automatic calculation.

public/draw/lv_draw_buf.h:283function

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.

void lv_draw_buf_destroy(lv_draw_buf_t *draw_buf)

Name	Type	Description
`draw_buf`	`lv_draw_buf_t *`	the draw buffer to destroy May be `NULL`.

public/draw/lv_draw_buf.h:297function

lv_draw_buf_copy

Copy an area from a buffer to another

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)

Name	Type	Description
`dest`	`lv_draw_buf_t *`	pointer to the destination draw buffer
`dest_area`	`const lv_area_t *`	the area to copy from the destination buffer. May be `NULL`. When NULL, the whole buffer is copied
`src`	`const lv_draw_buf_t *`	pointer to the source draw buffer
`src_area`	`const lv_area_t *`	the area to copy from the destination buffer. May be `NULL`. When NULL, the whole buffer is copied

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.

public/draw/lv_draw_buf.h:303function

lv_draw_buf_goto_xy

Return pointer to the buffer at the given coordinates

void * lv_draw_buf_goto_xy(const lv_draw_buf_t *buf, uint32_t x, uint32_t y)

Name	Type
`buf`	`const lv_draw_buf_t *`
`x`	`uint32_t`
`y`	`uint32_t`

public/draw/lv_draw_buf.h:308function

lv_draw_buf_is_position_valid

Return true if x and y exist in the draw buffer

bool lv_draw_buf_is_position_valid(const lv_draw_buf_t *buf, uint32_t x, uint32_t y)

Name	Type
`buf`	`const lv_draw_buf_t *`
`x`	`uint32_t`
`y`	`uint32_t`

public/draw/lv_draw_buf.h:316function

lv_draw_buf_adjust_stride

Adjust the stride of a draw buf in place.

lv_result_t lv_draw_buf_adjust_stride(lv_draw_buf_t *src, uint32_t stride)

Name	Type	Description
`src`	`lv_draw_buf_t *`	pointer to a draw buffer
`stride`	`uint32_t`	the new stride in bytes for image. Use LV_STRIDE_AUTO for automatic calculation.

Returns: lv_result_t — LV_RESULT_OK: success or LV_RESULT_INVALID: failed

public/draw/lv_draw_buf.h:325function

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.

lv_result_t lv_draw_buf_premultiply(lv_draw_buf_t *draw_buf)

Name	Type
`draw_buf`	`lv_draw_buf_t *`

Returns: lv_result_t — LV_RESULT_OK: premultiply success

public/draw/lv_draw_buf.h:334function

lv_draw_buf_has_flag

Check if a draw buffer has a given flag.

bool lv_draw_buf_has_flag(const lv_draw_buf_t *draw_buf, lv_image_flags_t flag)

Name	Type	Description
`draw_buf`	`const lv_draw_buf_t *`	pointer to a draw buffer
`flag`	`lv_image_flags_t`	the flag to check

Returns: bool — true: the flag is set, false: the flag is not set

public/draw/lv_draw_buf.h:348function

lv_draw_buf_clear_flag

Clear a flag from a draw buffer.

void lv_draw_buf_clear_flag(lv_draw_buf_t *draw_buf, lv_image_flags_t flag)

Name	Type	Description
`draw_buf`	`lv_draw_buf_t *`	pointer to a draw buffer
`flag`	`lv_image_flags_t`	the flag to clear

public/draw/lv_draw_buf.h:355function

lv_draw_buf_from_image

As of now, draw buf share same definition as lv_image_dsc_t. And is interchangeable with lv_image_dsc_t.

lv_result_t lv_draw_buf_from_image(lv_draw_buf_t *buf, const lv_image_dsc_t *img)

Name	Type
`buf`	`lv_draw_buf_t *`
`img`	`const lv_image_dsc_t *`

public/draw/lv_draw_buf.h:357function

lv_draw_buf_to_image

void lv_draw_buf_to_image(const lv_draw_buf_t *buf, lv_image_dsc_t *img)

Name	Type
`buf`	`const lv_draw_buf_t *`
`img`	`lv_image_dsc_t *`

public/draw/lv_draw_buf.h:383function

lv_image_buf_free

> Deprecated: Use lv_draw_buffer_create/destroy instead. Free the data pointer and dsc struct of an image.

void lv_image_buf_free(lv_image_dsc_t *dsc)

Name	Type	Description
`dsc`	`lv_image_dsc_t *`	data pointer of the image May be `NULL`.

Structs

struct

_lv_draw_buf_t

Member	Type	Description
`header`	`lv_image_header_t`
`data_size`	`uint32_t`	Total buf size in bytes
`data`	`uint8_t *`
`unaligned_data`	`void *`	Unaligned address of `data`, used internally by lvgl
`handlers`	`const lv_draw_buf_handlers_t *`	draw buffer alloc/free ops.

Typedefs

public/draw/lv_draw_buf.h:78typedef

lv_draw_buf_malloc_cb_t

typedef void *(* lv_draw_buf_malloc_cb_t) (size_t size, lv_color_format_t color_format)

Used by 1 function

lv_draw_buf_handlers_init — param buf_malloc_cb

public/draw/lv_draw_buf.h:80typedef

lv_draw_buf_free_cb_t

typedef void(* lv_draw_buf_free_cb_t) (void *draw_buf)

Used by 1 function

lv_draw_buf_handlers_init — param buf_free_cb

public/draw/lv_draw_buf.h:82typedef

lv_draw_buf_copy_cb_t

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)

Used by 1 function

lv_draw_buf_handlers_init — param buf_copy_cb

public/draw/lv_draw_buf.h:85typedef

lv_draw_buf_align_cb_t

typedef void *(* lv_draw_buf_align_cb_t) (void *buf, lv_color_format_t color_format)

Used by 1 function

lv_draw_buf_handlers_init — param align_pointer_cb

public/draw/lv_draw_buf.h:87typedef

lv_draw_buf_cache_operation_cb_t

typedef void(* lv_draw_buf_cache_operation_cb_t) (const lv_draw_buf_t *draw_buf, const lv_area_t *area)

Used by 2 functions

lv_draw_buf_handlers_init — param invalidate_cache_cb
lv_draw_buf_handlers_init — param flush_cache_cb

public/draw/lv_draw_buf.h:89typedef

lv_draw_buf_width_to_stride_cb_t

typedef uint32_t(* lv_draw_buf_width_to_stride_cb_t) (uint32_t w, lv_color_format_t color_format)

Used by 1 function

lv_draw_buf_handlers_init — param width_to_stride_cb

public/draw/lv_draw_buf.h:91typedef

lv_draw_buf_clear_cb_t

typedef void(* lv_draw_buf_clear_cb_t) (lv_draw_buf_t *draw_buf, const lv_area_t *a, lv_layer_t *layer)

Macros

public/draw/lv_draw_buf.h:27macro

LV_STRIDE_AUTO

#define LV_STRIDE_AUTO 0

Use this value to let LVGL calculate stride automatically

public/draw/lv_draw_buf.h:36macro

LV_DRAW_BUF_STRIDE

#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.

public/draw/lv_draw_buf.h:40macro

LV_DRAW_BUF_SIZE

#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

public/draw/lv_draw_buf.h:50macro

LV_DRAW_BUF_DEFINE_STATIC

#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.

public/draw/lv_draw_buf.h:67macro

LV_DRAW_BUF_INIT_STATIC

#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

Indirect dependencies

lv_draw_buf.h

On this page