lv_draw_buf.h

Defines

LV_STRIDE_AUTO

LV_DRAW_BUF_STRIDE(w, cf)

Stride alignment for draw buffers. It may vary between different color formats and hardware. Refine it to suit your needs.

LV_DRAW_BUF_SIZE(w, h, cf)

LV_DRAW_BUF_DEFINE_STATIC(name, _w, _h, _cf)

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(name)

Typedefs

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

typedef void (*lv_draw_buf_free_cb)(void *draw_buf)

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

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

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

Functions

void lv_draw_buf_init_with_default_handlers(lv_draw_buf_handlers_t *handlers)

Initialize the draw buffer with the default handlers.

参数:

handlers -- the draw buffer handlers to set

void lv_draw_buf_handlers_init(lv_draw_buf_handlers_t *handlers, lv_draw_buf_malloc_cb buf_malloc_cb, lv_draw_buf_free_cb buf_free_cb, lv_draw_buf_align_cb align_pointer_cb, lv_draw_buf_cache_operation_cb invalidate_cache_cb, lv_draw_buf_cache_operation_cb flush_cache_cb, lv_draw_buf_width_to_stride_cb width_to_stride_cb)

Initialize the draw buffer with given handlers.

参数:

• 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

• align_pointer_cb -- the callback to align the buffer

• invalidate_cache_cb -- the callback to invalidate the cache of the buffer

• width_to_stride_cb -- the callback to calculate the stride based on the width and color format

lv_draw_buf_handlers_t *lv_draw_buf_get_handlers(void)

Get the struct which holds the callbacks for draw buf management. Custom callback can be set on the returned value

返回:

pointer to the struct of handlers

void *lv_draw_buf_align(void *buf, lv_color_format_t color_format)

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

参数:

• buf -- the data to align

• color_format -- the color format of the buffer

返回:

the aligned buffer

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

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

参数:

• handlers -- the draw buffer handlers

• buf -- the data to align

• color_format -- the color format of the buffer

返回:

the aligned buffer

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

Invalidate the cache of the buffer

参数:

• 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

void lv_draw_buf_invalidate_cache_user(const lv_draw_buf_handlers_t *handlers, const lv_draw_buf_t *draw_buf, const lv_area_t *area)

Invalidate the cache of the buffer using the user-defined callback

参数:

• handlers -- the draw buffer handlers

• draw_buf -- the draw buffer needs to be invalidated

• area -- the area to invalidate in the buffer,

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

Flush the cache of the buffer

参数:

• 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

void lv_draw_buf_flush_cache_user(const lv_draw_buf_handlers_t *handlers, const lv_draw_buf_t *draw_buf, const lv_area_t *area)

Flush the cache of the buffer using the user-defined callback

参数:

• handlers -- the draw buffer handlers

• draw_buf -- the draw buffer needs to be flushed

• area -- the area to flush in the buffer,

uint32_t lv_draw_buf_width_to_stride(uint32_t w, lv_color_format_t color_format)

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

参数:

• w -- the width in pixels

• color_format -- the color format

返回:

the stride in bytes

uint32_t lv_draw_buf_width_to_stride_user(const lv_draw_buf_handlers_t *handlers, uint32_t w, lv_color_format_t color_format)

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

参数:

• handlers -- the draw buffer handlers

• w -- the width in pixels

• color_format -- the color format

返回:

the stride in bytes

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

Clear an area on the buffer

参数:

• draw_buf -- pointer to draw buffer

• a -- the area to clear, or NULL to clear the whole buffer

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)

Copy an area from a buffer to another

备注

dest_area and src_area should have the same width and height

备注

dest and src should have same color format. Color converting is not supported fow now.

参数:

• 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

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

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.

参数:

• 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_t *lv_draw_buf_create_user(const lv_draw_buf_handlers_t *handlers, uint32_t w, uint32_t h, lv_color_format_t cf, uint32_t stride)

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.

参数:

• 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_t *lv_draw_buf_dup(const lv_draw_buf_t *draw_buf)

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

参数:

draw_buf -- the draw buf to duplicate

返回:

the duplicated draw buf on success, NULL if failed

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

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

参数:

• handlers -- the draw buffer handlers

• draw_buf -- the draw buf to duplicate

返回:

the duplicated draw buf on success, NULL if failed

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)

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

参数:

• 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 -- the buffer used for drawing. Unaligned data will be aligned internally

• data_size -- the size of the buffer in bytes

返回:

return LV_RESULT_OK on success, LV_RESULT_INVALID otherwise

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)

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.

参数:

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

void lv_draw_buf_destroy(lv_draw_buf_t *buf)

Destroy a draw buf by free the actual buffer if it's marked as LV_IMAGE_FLAGS_ALLOCATED in header. Then free the lv_draw_buf_t struct.

参数:

buf -- the draw buffer to destroy

void lv_draw_buf_destroy_user(const lv_draw_buf_handlers_t *handlers, lv_draw_buf_t *buf)

Destroy a draw buf by free the actual buffer if it's marked as LV_IMAGE_FLAGS_ALLOCATED in header. Then free the lv_draw_buf_t struct.

参数:

• handlers -- the draw buffer handlers

• buf -- the draw buffer to destroy

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

Return pointer to the buffer at the given coordinates

lv_result_t lv_draw_buf_adjust_stride(lv_draw_buf_t *src, uint32_t stride)

Adjust the stride of a draw buf in place.

参数:

• src -- pointer to a draw buffer

• stride -- the new stride in bytes for image. Use LV_STRIDE_AUTO for automatic calculation.

返回:

LV_RESULT_OK: success or LV_RESULT_INVALID: failed

lv_result_t lv_draw_buf_premultiply(lv_draw_buf_t *draw_buf)

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_OK: premultiply success

bool lv_draw_buf_has_flag(lv_draw_buf_t *draw_buf, lv_image_flags_t flag)

void lv_draw_buf_set_flag(lv_draw_buf_t *draw_buf, lv_image_flags_t flag)

void lv_draw_buf_clear_flag(lv_draw_buf_t *draw_buf, lv_image_flags_t flag)

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

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

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

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

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

参数:

• 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 lv_color32_t format

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

Deprecated:

Use lv_draw_buf_set_palette instead.

void lv_image_buf_free(lv_image_dsc_t *dsc)

Deprecated:

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

struct lv_draw_buf_t

Public Members

lv_image_header_t header

uint32_t data_size

uint8_t *data

void *unaligned_data