diff --git a/src/lv_draw/lv_img_decoder.c b/src/lv_draw/lv_img_decoder.c index 5822be982..bf10848f4 100644 --- a/src/lv_draw/lv_img_decoder.c +++ b/src/lv_draw/lv_img_decoder.c @@ -81,59 +81,13 @@ void lv_img_decoder_init(void) lv_img_decoder_set_close_cb(decoder, lv_img_decoder_built_in_close); } -lv_img_decoder_t * lv_img_decoder_create(void) -{ - lv_img_decoder_t * decoder; - decoder = lv_ll_ins_head(&LV_GC_ROOT(_lv_img_defoder_ll)); - lv_mem_assert(decoder); - if(decoder == NULL) return NULL; - - memset(decoder, 0, sizeof(lv_img_decoder_t)); - - return decoder; -} - -void lv_img_decoder_delete(lv_img_decoder_t * decoder) -{ - lv_ll_rem(&LV_GC_ROOT(_lv_img_defoder_ll), decoder); - lv_mem_free(decoder); -} - -void lv_img_decoder_set_info_cb(lv_img_decoder_t * decoder, lv_img_decoder_info_f_t info_cb) -{ - decoder->info_cb = info_cb; -} - -void lv_img_decoder_set_open_cb(lv_img_decoder_t * decoder, lv_img_decoder_open_f_t open_cb) -{ - decoder->open_cb = open_cb; -} - -void lv_img_decoder_set_read_line_cb(lv_img_decoder_t * decoder, lv_img_decoder_read_line_f_t read_line_cb) -{ - decoder->read_line_cb = read_line_cb; -} - -void lv_img_decoder_set_close_cb(lv_img_decoder_t * decoder, lv_img_decoder_close_f_t close_cb) -{ - decoder->close_cb = close_cb; -} - -void lv_img_decoder_set_user_data(lv_img_decoder_t * decoder, lv_img_decoder_t user_data) -{ - memcpy(&decoder->user_data, &user_data, sizeof(user_data)); -} - -lv_img_decoder_user_data_t lv_img_decoder_get_user_data(lv_img_decoder_t * decoder) -{ - return decoder->user_data; -} - -lv_img_decoder_user_data_t * lv_img_decoder_get_user_data_ptr(lv_img_decoder_t * decoder) -{ - return &decoder->user_data; -} - +/** + * 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. + * @param src the image source. E.g. file name or variable. + * @param header the image info will be stored here + * @return LV_RES_OK: success; LV_RES_INV: wasn't able to get info about the image + */ lv_res_t lv_img_decoder_get_info(const char * src, lv_img_header_t * header) { header->always_zero = 0; @@ -151,6 +105,19 @@ lv_res_t lv_img_decoder_get_info(const char * src, lv_img_header_t * header) return res; } +/** + * Open an image. + * Try the created image decoder one by one. Once one is able to open the image that decoder is save in `dsc` + * @param dsc describe a decoding session. Simply a pointer to an `lv_img_decoder_dsc_t` variable. + * @param src the image source. Can be + * 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via `lv_fs_add_drv()`) + * 2) Variable: Pointer to an `lv_img_dsc_t` variable + * 3) Symbol: E.g. `LV_SYMBOL_OK` + * @param style the style of the image + * @return LV_IMG_DECODER_OPEN_FAIL: can open the image + * NULL: the image is opened but `lv_img_decoder_read_line` needs to be used to get the info line by line + * Else: a pointer to a buffer which holds the uncompressed pixels of the image + */ const uint8_t * lv_img_decoder_open(lv_img_decoder_dsc_t * dsc, const void * src, const lv_style_t * style) { dsc->style = style; @@ -175,6 +142,15 @@ const uint8_t * lv_img_decoder_open(lv_img_decoder_dsc_t * dsc, const void * src return res; } +/** + * Read a line from an opened image + * @param dsc pointer to `lv_img_decoder_dsc_t` used in `lv_img_decoder_open` + * @param x start X coordinate (from left) + * @param y start Y coordinate (from top) + * @param len number of pixels to read + * @param buf store the data here + * @return LV_RES_OK: success; LV_RES_INV: an error occurred + */ lv_res_t lv_img_decoder_read_line(lv_img_decoder_dsc_t * dsc, lv_coord_t x, lv_coord_t y, lv_coord_t len, uint8_t * buf) { lv_res_t res = LV_RES_INV; @@ -183,17 +159,85 @@ lv_res_t lv_img_decoder_read_line(lv_img_decoder_dsc_t * dsc, lv_coord_t x, lv_c return res; } +/** + * Close a decoding session + * @param dsc pointer to `lv_img_decoder_dsc_t` used in `lv_img_decoder_open` + */ void lv_img_decoder_close(lv_img_decoder_dsc_t * dsc) { if(dsc->decoder->close_cb) dsc->decoder->close_cb(dsc->decoder, dsc); } +/** + * Create a new image decoder + * @return pointer to the new image decoder + */ +lv_img_decoder_t * lv_img_decoder_create(void) +{ + lv_img_decoder_t * decoder; + decoder = lv_ll_ins_head(&LV_GC_ROOT(_lv_img_defoder_ll)); + lv_mem_assert(decoder); + if(decoder == NULL) return NULL; + + memset(decoder, 0, sizeof(lv_img_decoder_t)); + + return decoder; +} + +/** + * Delete an image decoder + * @param decoder pointer to an image decoder + */ +void lv_img_decoder_delete(lv_img_decoder_t * decoder) +{ + lv_ll_rem(&LV_GC_ROOT(_lv_img_defoder_ll), decoder); + lv_mem_free(decoder); +} + +/** + * Set a callback to get information about the image + * @param decoder pointer to an image decoder + * @param info_cb a function to collect info about an image (fill an `lv_img_header_t` struct) + */ +void lv_img_decoder_set_info_cb(lv_img_decoder_t * decoder, lv_img_decoder_info_f_t info_cb) +{ + decoder->info_cb = info_cb; +} + +/** + * Set a callback to open an image + * @param decoder pointer to an image decoder + * @param open_cb a function to open an image + */ +void lv_img_decoder_set_open_cb(lv_img_decoder_t * decoder, lv_img_decoder_open_f_t open_cb) +{ + decoder->open_cb = open_cb; +} + +/** + * Set a callback to a decoded line of an image + * @param decoder pointer to an image decoder + * @param read_line_cb a function to read a line of an image + */ +void lv_img_decoder_set_read_line_cb(lv_img_decoder_t * decoder, lv_img_decoder_read_line_f_t read_line_cb) +{ + decoder->read_line_cb = read_line_cb; +} + +/** + * Set a callback to close a decoding session. E.g. close files and free other resources. + * @param decoder pointer to an image decoder + * @param close_cb a function to close a decoding session + */ +void lv_img_decoder_set_close_cb(lv_img_decoder_t * decoder, lv_img_decoder_close_f_t close_cb) +{ + decoder->close_cb = close_cb; +} /********************** * STATIC FUNCTIONS **********************/ - static lv_res_t lv_img_decoder_built_in_info(lv_img_decoder_t * decoder, const void * src, lv_img_header_t * header) { (void)decoder; /*Unused*/ diff --git a/src/lv_draw/lv_img_decoder.h b/src/lv_draw/lv_img_decoder.h index 2dc6227bf..811247869 100644 --- a/src/lv_draw/lv_img_decoder.h +++ b/src/lv_draw/lv_img_decoder.h @@ -179,31 +179,123 @@ typedef struct _lv_img_decoder_dsc { /** * Initialize the image decoder module - * */ + */ void lv_img_decoder_init(void); -lv_img_decoder_t * lv_img_decoder_create(void); - -void lv_img_decoder_delete(lv_img_decoder_t * decoder); - -void lv_img_decoder_set_info_cb(lv_img_decoder_t * decoder, lv_img_decoder_info_f_t info_cb); - -void lv_img_decoder_set_open_cb(lv_img_decoder_t * decoder, lv_img_decoder_open_f_t open_cb); - -void lv_img_decoder_set_read_line_cb(lv_img_decoder_t * decoder, lv_img_decoder_read_line_f_t read_line_cb); - -void lv_img_decoder_set_close_cb(lv_img_decoder_t * decoder, lv_img_decoder_close_f_t close_cb); -void lv_img_decoder_set_user_data(lv_img_decoder_t * decoder, lv_img_decoder_t user_data); - -lv_img_decoder_user_data_t lv_img_decoder_get_user_data(lv_img_decoder_t * decoder); -lv_img_decoder_user_data_t * lv_img_decoder_get_user_data_ptr(lv_img_decoder_t * decoder); - +/** + * 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. + * @param src the image source. Can be + * 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via `lv_fs_add_drv()`) + * 2) Variable: Pointer to an `lv_img_dsc_t` variable + * 3) Symbol: E.g. `LV_SYMBOL_OK` + * @param header the image info will be stored here + * @return LV_RES_OK: success; LV_RES_INV: wasn't able to get info about the image + */ lv_res_t lv_img_decoder_get_info(const char * src, lv_img_header_t * header); + +/** + * Open an image. + * Try the created image decoder one by one. Once one is able to open the image that decoder is save in `dsc` + * @param dsc describe a decoding session. Simply a pointer to an `lv_img_decoder_dsc_t` variable. + * @param src the image source. Can be + * 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via `lv_fs_add_drv()`) + * 2) Variable: Pointer to an `lv_img_dsc_t` variable + * 3) Symbol: E.g. `LV_SYMBOL_OK` + * @param style the style of the image + * @return LV_IMG_DECODER_OPEN_FAIL: can open the image + * NULL: the image is opened but `lv_img_decoder_read_line` needs to be used to get the info line by line + * Else: a pointer to a buffer which holds the uncompressed pixels of the image + */ const uint8_t * lv_img_decoder_open(lv_img_decoder_dsc_t * dsc, const void * src, const lv_style_t * style); +/** + * Read a line from an opened image + * @param dsc pointer to `lv_img_decoder_dsc_t` used in `lv_img_decoder_open` + * @param x start X coordinate (from left) + * @param y start Y coordinate (from top) + * @param len number of pixels to read + * @param buf store the data here + * @return LV_RES_OK: success; LV_RES_INV: an error occurred + */ lv_res_t lv_img_decoder_read_line(lv_img_decoder_dsc_t * dsc, lv_coord_t x, lv_coord_t y, lv_coord_t len, uint8_t * buf); +/** + * Close a decoding session + * @param dsc pointer to `lv_img_decoder_dsc_t` used in `lv_img_decoder_open` + */ void lv_img_decoder_close(lv_img_decoder_dsc_t * dsc); + +/** + * Create a new image decoder + * @return pointer to the new image decoder + */ +lv_img_decoder_t * lv_img_decoder_create(void); + +/** + * Delete an image decoder + * @param decoder pointer to an image decoder + */ +void lv_img_decoder_delete(lv_img_decoder_t * decoder); + +/** + * Set a callback to get information about the image + * @param decoder pointer to an image decoder + * @param info_cb a function to collect info about an image (fill an `lv_img_header_t` struct) + */ +void lv_img_decoder_set_info_cb(lv_img_decoder_t * decoder, lv_img_decoder_info_f_t info_cb); + +/** + * Set a callback to open an image + * @param decoder pointer to an image decoder + * @param open_cb a function to open an image + */ +void lv_img_decoder_set_open_cb(lv_img_decoder_t * decoder, lv_img_decoder_open_f_t open_cb); + +/** + * Set a callback to a decoded line of an image + * @param decoder pointer to an image decoder + * @param read_line_cb a function to read a line of an image + */ +void lv_img_decoder_set_read_line_cb(lv_img_decoder_t * decoder, lv_img_decoder_read_line_f_t read_line_cb); + +/** + * Set a callback to close a decoding session. E.g. close files and free other resources. + * @param decoder pointer to an image decoder + * @param close_cb a function to close a decoding session + */ +void lv_img_decoder_set_close_cb(lv_img_decoder_t * decoder, lv_img_decoder_close_f_t close_cb); + +/** + * Set a custom user data in an image decoder. + * @param decoder pointer to an image decoder + * @param user_data the user data to set + */ +static inline void lv_img_decoder_set_user_data(lv_img_decoder_t * decoder, lv_img_decoder_t user_data) +{ + memcpy(&decoder->user_data, &user_data, sizeof(user_data)); +} + +/** + * Get the user data + * @param decoder pointer to an image decoder + * @return the user data + */ +static inline lv_img_decoder_user_data_t lv_img_decoder_get_user_data(lv_img_decoder_t * decoder) +{ + return decoder->user_data; +} + +/** + * Get a pointer to the user data + * @param decoder pointer to an image decoder + * @return pointer to the user data + */ +static inline lv_img_decoder_user_data_t * lv_img_decoder_get_user_data_ptr(lv_img_decoder_t * decoder) +{ + return &decoder->user_data; +} + /********************** * MACROS **********************/