1 /** 2 * @file lv_image_decoder.h 3 * 4 */ 5 6 #ifndef LV_IMAGE_DECODER_H 7 #define LV_IMAGE_DECODER_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /********************* 14 * INCLUDES 15 *********************/ 16 #include "../lv_conf_internal.h" 17 18 #include "lv_draw_buf.h" 19 #include "../misc/lv_fs.h" 20 #include "../misc/lv_types.h" 21 #include "../misc/lv_area.h" 22 23 /********************* 24 * DEFINES 25 *********************/ 26 27 /********************** 28 * TYPEDEFS 29 **********************/ 30 31 /** 32 * Source of image.*/ 33 typedef enum { 34 LV_IMAGE_SRC_VARIABLE, /** Binary/C variable*/ 35 LV_IMAGE_SRC_FILE, /** File in filesystem*/ 36 LV_IMAGE_SRC_SYMBOL, /** Symbol (@ref lv_symbol_def.h)*/ 37 LV_IMAGE_SRC_UNKNOWN, /** Unknown source*/ 38 } lv_image_src_t; 39 40 /** 41 * Get info from an image and store in the `header` 42 * @param decoder pointer to decoder object 43 * @param dsc pointer to decoder descriptor 44 * @param header store the info here 45 * @return LV_RESULT_OK: info written correctly; LV_RESULT_INVALID: failed 46 */ 47 typedef lv_result_t (*lv_image_decoder_info_f_t)(lv_image_decoder_t * decoder, lv_image_decoder_dsc_t * dsc, 48 lv_image_header_t * header); 49 50 /** 51 * Open an image for decoding. Prepare it as it is required to read it later 52 * @param decoder pointer to the decoder the function associated with 53 * @param dsc pointer to decoder descriptor. `src`, `color` are already initialized in it. 54 */ 55 typedef lv_result_t (*lv_image_decoder_open_f_t)(lv_image_decoder_t * decoder, lv_image_decoder_dsc_t * dsc); 56 57 /** 58 * Decode `full_area` pixels incrementally by calling in a loop. Set `decoded_area` values to `LV_COORD_MIN` on first call. 59 * Required only if the "open" function can't return with the whole decoded pixel array. 60 * @param decoder pointer to the decoder the function associated with 61 * @param dsc pointer to decoder descriptor 62 * @param full_area input parameter. the full area to decode after enough subsequent calls 63 * @param decoded_area input+output parameter. set the values to `LV_COORD_MIN` for the first call and to reset decoding. 64 * the decoded area is stored here after each call. 65 * @return LV_RESULT_OK: ok; LV_RESULT_INVALID: failed or there is nothing left to decode 66 */ 67 typedef lv_result_t (*lv_image_decoder_get_area_cb_t)(lv_image_decoder_t * decoder, 68 lv_image_decoder_dsc_t * dsc, 69 const lv_area_t * full_area, lv_area_t * decoded_area); 70 71 /** 72 * Close the pending decoding. Free resources etc. 73 * @param decoder pointer to the decoder the function associated with 74 * @param dsc pointer to decoder descriptor 75 */ 76 typedef void (*lv_image_decoder_close_f_t)(lv_image_decoder_t * decoder, lv_image_decoder_dsc_t * dsc); 77 78 /********************** 79 * GLOBAL PROTOTYPES 80 **********************/ 81 82 /** 83 * Get information about an image. 84 * Try the created image decoder one by one. Once one is able to get info that info will be used. 85 * @param src the image source. Can be 86 * 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via `lv_fs_drv_register()`) 87 * 2) Variable: Pointer to an `lv_image_dsc_t` variable 88 * 3) Symbol: E.g. `LV_SYMBOL_OK` 89 * @param header the image info will be stored here 90 * @return LV_RESULT_OK: success; LV_RESULT_INVALID: wasn't able to get info about the image 91 */ 92 lv_result_t lv_image_decoder_get_info(const void * src, lv_image_header_t * header); 93 94 /** 95 * Open an image. 96 * Try the created image decoders one by one. Once one is able to open the image that decoder is saved in `dsc` 97 * @param dsc describes a decoding session. Simply a pointer to an `lv_image_decoder_dsc_t` variable. 98 * @param src the image source. Can be 99 * 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via `lv_fs_drv_register())`) 100 * 2) Variable: Pointer to an `lv_image_dsc_t` variable 101 * 3) Symbol: E.g. `LV_SYMBOL_OK` 102 * @param args args about how the image should be opened. 103 * @return LV_RESULT_OK: opened the image. `dsc->decoded` and `dsc->header` are set. 104 * LV_RESULT_INVALID: none of the registered image decoders were able to open the image. 105 */ 106 lv_result_t lv_image_decoder_open(lv_image_decoder_dsc_t * dsc, const void * src, const lv_image_decoder_args_t * args); 107 108 /** 109 * Decode `full_area` pixels incrementally by calling in a loop. Set `decoded_area` to `LV_COORD_MIN` on first call. 110 * @param dsc image decoder descriptor 111 * @param full_area input parameter. the full area to decode after enough subsequent calls 112 * @param decoded_area input+output parameter. set the values to `LV_COORD_MIN` for the first call and to reset decoding. 113 * the decoded area is stored here after each call. 114 * @return LV_RESULT_OK: success; LV_RESULT_INVALID: an error occurred or there is nothing left to decode 115 */ 116 lv_result_t lv_image_decoder_get_area(lv_image_decoder_dsc_t * dsc, const lv_area_t * full_area, 117 lv_area_t * decoded_area); 118 119 /** 120 * Close a decoding session 121 * @param dsc pointer to `lv_image_decoder_dsc_t` used in `lv_image_decoder_open` 122 */ 123 void lv_image_decoder_close(lv_image_decoder_dsc_t * dsc); 124 125 /** 126 * Create a new image decoder 127 * @return pointer to the new image decoder 128 */ 129 lv_image_decoder_t * lv_image_decoder_create(void); 130 131 /** 132 * Delete an image decoder 133 * @param decoder pointer to an image decoder 134 */ 135 void lv_image_decoder_delete(lv_image_decoder_t * decoder); 136 137 /** 138 * Get the next image decoder in the linked list of image decoders 139 * @param decoder pointer to an image decoder or NULL to get the first one 140 * @return the next image decoder or NULL if no more image decoder exists 141 */ 142 lv_image_decoder_t * lv_image_decoder_get_next(lv_image_decoder_t * decoder); 143 144 /** 145 * Set a callback to get information about the image 146 * @param decoder pointer to an image decoder 147 * @param info_cb a function to collect info about an image (fill an `lv_image_header_t` struct) 148 */ 149 void lv_image_decoder_set_info_cb(lv_image_decoder_t * decoder, lv_image_decoder_info_f_t info_cb); 150 151 /** 152 * Set a callback to open an image 153 * @param decoder pointer to an image decoder 154 * @param open_cb a function to open an image 155 */ 156 void lv_image_decoder_set_open_cb(lv_image_decoder_t * decoder, lv_image_decoder_open_f_t open_cb); 157 158 /** 159 * Set a callback to a decoded line of an image 160 * @param decoder pointer to an image decoder 161 * @param read_line_cb a function to read a line of an image 162 */ 163 void lv_image_decoder_set_get_area_cb(lv_image_decoder_t * decoder, lv_image_decoder_get_area_cb_t read_line_cb); 164 165 /** 166 * Set a callback to close a decoding session. E.g. close files and free other resources. 167 * @param decoder pointer to an image decoder 168 * @param close_cb a function to close a decoding session 169 */ 170 void lv_image_decoder_set_close_cb(lv_image_decoder_t * decoder, lv_image_decoder_close_f_t close_cb); 171 172 lv_cache_entry_t * lv_image_decoder_add_to_cache(lv_image_decoder_t * decoder, 173 lv_image_cache_data_t * search_key, 174 const lv_draw_buf_t * decoded, void * user_data); 175 176 /** 177 * Check the decoded image, make any modification if decoder `args` requires. 178 * @note A new draw buf will be allocated if provided `decoded` is not modifiable or stride mismatch etc. 179 * @param dsc pointer to a decoder descriptor 180 * @param decoded pointer to a decoded image to post process to meet dsc->args requirement. 181 * @return post processed draw buffer, when it differs with `decoded`, it's newly allocated. 182 */ 183 lv_draw_buf_t * lv_image_decoder_post_process(lv_image_decoder_dsc_t * dsc, lv_draw_buf_t * decoded); 184 185 /********************** 186 * MACROS 187 **********************/ 188 189 #ifdef __cplusplus 190 } /*extern "C"*/ 191 #endif 192 193 #endif /*LV_IMAGE_DECODER_H*/ 194
