lv_image_decoder.h

Typedefs

typedef _lv_image_src_t lv_image_src_t
typedef struct _lv_image_decoder_dsc_t lv_image_decoder_dsc_t
typedef struct _lv_image_decoder_args_t lv_image_decoder_args_t

Image decoder args. It determines how to decoder an image, e.g. whether to premultiply the alpha or not. It should be passed to lv_img_decoder_open() function. If NULL is provided, default args are used.

Default args: all field are zero or false.

typedef lv_result_t (*lv_image_decoder_info_f_t)(lv_image_decoder_t *decoder, const void *src, lv_image_header_t *header)

Get info from an image and store in the header

Param src:

the image source. Can be a pointer to a C array or a file name (Use lv_image_src_get_type to determine the type)

Param header:

store the info here

Return:

LV_RESULT_OK: info written correctly; LV_RESULT_INVALID: failed

typedef lv_result_t (*lv_image_decoder_open_f_t)(lv_image_decoder_t *decoder, lv_image_decoder_dsc_t *dsc)

Open an image for decoding. Prepare it as it is required to read it later

Param decoder:

pointer to the decoder the function associated with

Param dsc:

pointer to decoder descriptor. src, color are already initialized in it.

typedef lv_result_t (*lv_image_decoder_get_area_cb_t)(lv_image_decoder_t *decoder, lv_image_decoder_dsc_t *dsc, const lv_area_t *full_area, lv_area_t *decoded_area)

Decode len pixels starting from the given x, y coordinates and store them in buf. Required only if the "open" function can't return with the whole decoded pixel array.

Param decoder:

pointer to the decoder the function associated with

Param dsc:

pointer to decoder descriptor

Param x:

start x coordinate

Param y:

start y coordinate

Param len:

number of pixels to decode

Param buf:

a buffer to store the decoded pixels

Return:

LV_RESULT_OK: ok; LV_RESULT_INVALID: failed

typedef void (*lv_image_decoder_close_f_t)(lv_image_decoder_t *decoder, lv_image_decoder_dsc_t *dsc)

Close the pending decoding. Free resources etc.

Param decoder:

pointer to the decoder the function associated with

Param dsc:

pointer to decoder descriptor

typedef struct _lv_image_decoder_cache_data_t lv_image_cache_data_t
typedef struct _lv_image_decoder_header_cache_data_t lv_image_header_cache_data_t

Enums

enum _lv_image_src_t

Source of image.

Values:

enumerator LV_IMAGE_SRC_VARIABLE
enumerator LV_IMAGE_SRC_FILE

Binary/C variable

enumerator LV_IMAGE_SRC_SYMBOL

File in filesystem

enumerator LV_IMAGE_SRC_UNKNOWN

Symbol (lv_symbol_def.h)

Functions

void _lv_image_decoder_init(void)

Initialize the image decoder module

void _lv_image_decoder_deinit(void)

Deinitialize the image decoder module

lv_result_t lv_image_decoder_get_info(const void *src, lv_image_header_t *header)

Get information about an image. Try the created image decoder one by one. Once one is able to get info that info will be used.

参数:

  • src -- the image source. Can be 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via lv_fs_drv_register()) 2) Variable: Pointer to an lv_image_dsc_t variable 3) Symbol: E.g. LV_SYMBOL_OK

  • header -- the image info will be stored here

返回:

LV_RESULT_OK: success; LV_RESULT_INVALID: wasn't able to get info about the image

lv_result_t lv_image_decoder_open(lv_image_decoder_dsc_t *dsc, const void *src, const lv_image_decoder_args_t *args)

Open an image. Try the created image decoders one by one. Once one is able to open the image that decoder is saved in dsc

参数:

  • dsc -- describes a decoding session. Simply a pointer to an lv_image_decoder_dsc_t variable.

  • src -- the image source. Can be 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via lv_fs_drv_register())) 2) Variable: Pointer to an lv_image_dsc_t variable 3) Symbol: E.g. LV_SYMBOL_OK

  • color -- The color of the image with LV_COLOR_FORMAT_ALPHA_...

  • args -- args about how the image should be opened.

返回:

LV_RESULT_OK: opened the image. dsc->decoded and dsc->header are set. LV_RESULT_INVALID: none of the registered image decoders were able to open the image.

lv_result_t lv_image_decoder_get_area(lv_image_decoder_dsc_t *dsc, const lv_area_t *full_area, lv_area_t *decoded_area)

Decode an area of the opened image

参数:

  • dsc -- image decoder descriptor

  • full_area -- start X coordinate (from left)

  • decoded_area -- start Y coordinate (from top)

返回:

LV_RESULT_OK: success; LV_RESULT_INVALID: an error occurred

void lv_image_decoder_close(lv_image_decoder_dsc_t *dsc)

Close a decoding session

参数:

dsc -- pointer to lv_image_decoder_dsc_t used in lv_image_decoder_open

lv_image_decoder_t *lv_image_decoder_create(void)

Create a new image decoder

返回:

pointer to the new image decoder

void lv_image_decoder_delete(lv_image_decoder_t *decoder)

Delete an image decoder

参数:

decoder -- pointer to an image decoder

lv_image_decoder_t *lv_image_decoder_get_next(lv_image_decoder_t *decoder)

Get the next image decoder in the linked list of image decoders

参数:

decoder -- pointer to an image decoder or NULL to get the first one

返回:

the next image decoder or NULL if no more image decoder exists

void lv_image_decoder_set_info_cb(lv_image_decoder_t *decoder, lv_image_decoder_info_f_t info_cb)

Set a callback to get information about the image

参数:

  • decoder -- pointer to an image decoder

  • info_cb -- a function to collect info about an image (fill an lv_image_header_t struct)

void lv_image_decoder_set_open_cb(lv_image_decoder_t *decoder, lv_image_decoder_open_f_t open_cb)

Set a callback to open an image

参数:

  • decoder -- pointer to an image decoder

  • open_cb -- a function to open an image

void lv_image_decoder_set_get_area_cb(lv_image_decoder_t *decoder, lv_image_decoder_get_area_cb_t read_line_cb)

Set a callback to a decoded line of an image

参数:

  • decoder -- pointer to an image decoder

  • read_line_cb -- a function to read a line of an image

void lv_image_decoder_set_close_cb(lv_image_decoder_t *decoder, lv_image_decoder_close_f_t close_cb)

Set a callback to close a decoding session. E.g. close files and free other resources.

参数:

  • decoder -- pointer to an image decoder

  • close_cb -- a function to close a decoding session

void lv_image_decoder_set_cache_free_cb(lv_image_decoder_t *decoder, lv_cache_free_cb_t cache_free_cb)

Set a custom method to free cache data. Normally this is not needed. If the custom decoder allocates additional memory other than dsc->decoded draw buffer, then you need to register your own method to free it. By default the cache entry is free'ed in image_decoder_cache_free_cb.

参数:

  • decoder -- pointer to the image decoder

  • cache_free_cb -- the custom callback to free cache data. Refer to image_decoder_cache_free_cb.

lv_draw_buf_t *lv_image_decoder_post_process(lv_image_decoder_dsc_t *dsc, lv_draw_buf_t *decoded)

Check the decoded image, make any modification if decoder args requires.

备注

A new draw buf will be allocated if provided decoded is not modifiable or stride mismatch etc.

参数:

  • dsc -- pointer to a decoder descriptor

  • decoded -- pointer to a decoded image to post process to meet dsc->args requirement.

返回:

post processed draw buffer, when it differs with decoded, it's newly allocated.

struct _lv_image_decoder_args_t
#include <lv_image_decoder.h>

Image decoder args. It determines how to decoder an image, e.g. whether to premultiply the alpha or not. It should be passed to lv_img_decoder_open() function. If NULL is provided, default args are used.

Default args: all field are zero or false.

Public Members

bool stride_align
bool premultiply
bool no_cache
bool use_indexed
struct _lv_image_decoder_t

Public Members

lv_image_decoder_info_f_t info_cb
lv_image_decoder_open_f_t open_cb
lv_image_decoder_get_area_cb_t get_area_cb
lv_image_decoder_close_f_t close_cb
lv_cache_free_cb_t cache_free_cb
void *user_data
struct _lv_image_decoder_cache_data_t

Public Members

lv_cache_slot_size_t slot
const void *src
lv_image_src_t src_type
const lv_draw_buf_t *decoded
const lv_image_decoder_t *decoder
void *user_data
struct _lv_image_decoder_header_cache_data_t

Public Members

const void *src
lv_image_src_t src_type
lv_image_header_t header
lv_image_decoder_t *decoder
struct _lv_image_decoder_dsc_t
#include <lv_image_decoder.h>

Describe an image decoding session. Stores data about the decoding

Public Members

lv_image_decoder_t *decoder

The decoder which was able to open the image source

lv_image_decoder_args_t args
const void *src

The image source. A file path like "S:my_img.png" or pointer to an lv_image_dsc_t variable

lv_image_src_t src_type

Type of the source: file or variable. Can be set in open function if required

lv_image_header_t header

Info about the opened image: color format, size, etc. MUST be set in open function

const lv_draw_buf_t *decoded

Pointer to a draw buffer where the image's data (pixels) are stored in a decoded, plain format. MUST be set in open or get_area_cbfunction

const lv_color32_t *palette
uint32_t palette_size
uint32_t time_to_open

How much time did it take to open the image. [ms] If not set lv_image_cache will measure and set the time to open

const char *error_msg

A text to display instead of the image when the image can't be opened. Can be set in open function or set NULL.

lv_cache_t *cache
lv_cache_entry_t *cache_entry

Point to cache entry information

void *user_data

Store any custom data here is required