1 /** 2 * @file lv_img_decoder.h 3 * 4 */ 5 6 #ifndef LV_IMG_DEOCER_H 7 #define LV_IMG_DEOCER_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /********************* 14 * INCLUDES 15 *********************/ 16 #include "../lv_conf_internal.h" 17 18 #include <stdint.h> 19 #include "lv_img_buf.h" 20 #include "../lv_misc/lv_fs.h" 21 #include "../lv_misc/lv_types.h" 22 #include "../lv_misc/lv_area.h" 23 #include "../lv_core/lv_style.h" 24 25 /********************* 26 * DEFINES 27 *********************/ 28 29 /********************** 30 * TYPEDEFS 31 **********************/ 32 33 /** 34 * Source of image. */ 35 enum { 36 LV_IMG_SRC_VARIABLE, /** Binary/C variable */ 37 LV_IMG_SRC_FILE, /** File in filesystem */ 38 LV_IMG_SRC_SYMBOL, /** Symbol (@ref lv_symbol_def.h) */ 39 LV_IMG_SRC_UNKNOWN, /** Unknown source */ 40 }; 41 42 typedef uint8_t lv_img_src_t; 43 44 /* Decoder function definitions */ 45 46 struct _lv_img_decoder; 47 struct _lv_img_decoder_dsc; 48 49 /** 50 * Get info from an image and store in the `header` 51 * @param src the image source. Can be a pointer to a C array or a file name (Use 52 * `lv_img_src_get_type` to determine the type) 53 * @param header store the info here 54 * @return LV_RES_OK: info written correctly; LV_RES_INV: failed 55 */ 56 typedef lv_res_t (*lv_img_decoder_info_f_t)(struct _lv_img_decoder * decoder, const void * src, 57 lv_img_header_t * header); 58 59 /** 60 * Open an image for decoding. Prepare it as it is required to read it later 61 * @param decoder pointer to the decoder the function associated with 62 * @param dsc pointer to decoder descriptor. `src`, `style` are already initialized in it. 63 */ 64 typedef lv_res_t (*lv_img_decoder_open_f_t)(struct _lv_img_decoder * decoder, struct _lv_img_decoder_dsc * dsc); 65 66 /** 67 * Decode `len` pixels starting from the given `x`, `y` coordinates and store them in `buf`. 68 * Required only if the "open" function can't return with the whole decoded pixel array. 69 * @param decoder pointer to the decoder the function associated with 70 * @param dsc pointer to decoder descriptor 71 * @param x start x coordinate 72 * @param y start y coordinate 73 * @param len number of pixels to decode 74 * @param buf a buffer to store the decoded pixels 75 * @return LV_RES_OK: ok; LV_RES_INV: failed 76 */ 77 typedef lv_res_t (*lv_img_decoder_read_line_f_t)(struct _lv_img_decoder * decoder, struct _lv_img_decoder_dsc * dsc, 78 lv_coord_t x, lv_coord_t y, lv_coord_t len, uint8_t * buf); 79 80 /** 81 * Close the pending decoding. Free resources etc. 82 * @param decoder pointer to the decoder the function associated with 83 * @param dsc pointer to decoder descriptor 84 */ 85 typedef void (*lv_img_decoder_close_f_t)(struct _lv_img_decoder * decoder, struct _lv_img_decoder_dsc * dsc); 86 87 typedef struct _lv_img_decoder { 88 lv_img_decoder_info_f_t info_cb; 89 lv_img_decoder_open_f_t open_cb; 90 lv_img_decoder_read_line_f_t read_line_cb; 91 lv_img_decoder_close_f_t close_cb; 92 93 #if LV_USE_USER_DATA 94 lv_img_decoder_user_data_t user_data; 95 #endif 96 } lv_img_decoder_t; 97 98 /**Describe an image decoding session. Stores data about the decoding*/ 99 typedef struct _lv_img_decoder_dsc { 100 /**The decoder which was able to open the image source*/ 101 lv_img_decoder_t * decoder; 102 103 /**The image source. A file path like "S:my_img.png" or pointer to an `lv_img_dsc_t` variable*/ 104 const void * src; 105 106 /**Style to draw the image.*/ 107 lv_color_t color; 108 109 /**Type of the source: file or variable. Can be set in `open` function if required*/ 110 lv_img_src_t src_type; 111 112 /**Info about the opened image: color format, size, etc. MUST be set in `open` function*/ 113 lv_img_header_t header; 114 115 /** Pointer to a buffer where the image's data (pixels) are stored in a decoded, plain format. 116 * MUST be set in `open` function*/ 117 const uint8_t * img_data; 118 119 /** How much time did it take to open the image. [ms] 120 * If not set `lv_img_cache` will measure and set the time to open*/ 121 uint32_t time_to_open; 122 123 /**A text to display instead of the image when the image can't be opened. 124 * Can be set in `open` function or set NULL. */ 125 const char * error_msg; 126 127 /**Store any custom data here is required*/ 128 void * user_data; 129 } lv_img_decoder_dsc_t; 130 131 /********************** 132 * GLOBAL PROTOTYPES 133 **********************/ 134 135 /** 136 * Initialize the image decoder module 137 */ 138 void _lv_img_decoder_init(void); 139 140 /** 141 * Get information about an image. 142 * Try the created image decoder one by one. Once one is able to get info that info will be used. 143 * @param src the image source. Can be 144 * 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via `lv_fs_add_drv()`) 145 * 2) Variable: Pointer to an `lv_img_dsc_t` variable 146 * 3) Symbol: E.g. `LV_SYMBOL_OK` 147 * @param header the image info will be stored here 148 * @return LV_RES_OK: success; LV_RES_INV: wasn't able to get info about the image 149 */ 150 lv_res_t lv_img_decoder_get_info(const char * src, lv_img_header_t * header); 151 152 /** 153 * Open an image. 154 * Try the created image decoder one by one. Once one is able to open the image that decoder is save in `dsc` 155 * @param dsc describe a decoding session. Simply a pointer to an `lv_img_decoder_dsc_t` variable. 156 * @param src the image source. Can be 157 * 1) File name: E.g. "S:folder/img1.png" (The drivers needs to registered via `lv_fs_add_drv()`) 158 * 2) Variable: Pointer to an `lv_img_dsc_t` variable 159 * 3) Symbol: E.g. `LV_SYMBOL_OK` 160 * @param color The color of the image with `LV_IMG_CF_ALPHA_...` 161 * @return LV_RES_OK: opened the image. `dsc->img_data` and `dsc->header` are set. 162 * LV_RES_INV: none of the registered image decoders were able to open the image. 163 */ 164 lv_res_t lv_img_decoder_open(lv_img_decoder_dsc_t * dsc, const void * src, lv_color_t color); 165 166 /** 167 * Read a line from an opened image 168 * @param dsc pointer to `lv_img_decoder_dsc_t` used in `lv_img_decoder_open` 169 * @param x start X coordinate (from left) 170 * @param y start Y coordinate (from top) 171 * @param len number of pixels to read 172 * @param buf store the data here 173 * @return LV_RES_OK: success; LV_RES_INV: an error occurred 174 */ 175 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, 176 uint8_t * buf); 177 178 /** 179 * Close a decoding session 180 * @param dsc pointer to `lv_img_decoder_dsc_t` used in `lv_img_decoder_open` 181 */ 182 void lv_img_decoder_close(lv_img_decoder_dsc_t * dsc); 183 184 /** 185 * Create a new image decoder 186 * @return pointer to the new image decoder 187 */ 188 lv_img_decoder_t * lv_img_decoder_create(void); 189 190 /** 191 * Delete an image decoder 192 * @param decoder pointer to an image decoder 193 */ 194 void lv_img_decoder_delete(lv_img_decoder_t * decoder); 195 196 /** 197 * Set a callback to get information about the image 198 * @param decoder pointer to an image decoder 199 * @param info_cb a function to collect info about an image (fill an `lv_img_header_t` struct) 200 */ 201 void lv_img_decoder_set_info_cb(lv_img_decoder_t * decoder, lv_img_decoder_info_f_t info_cb); 202 203 /** 204 * Set a callback to open an image 205 * @param decoder pointer to an image decoder 206 * @param open_cb a function to open an image 207 */ 208 void lv_img_decoder_set_open_cb(lv_img_decoder_t * decoder, lv_img_decoder_open_f_t open_cb); 209 210 /** 211 * Set a callback to a decoded line of an image 212 * @param decoder pointer to an image decoder 213 * @param read_line_cb a function to read a line of an image 214 */ 215 void lv_img_decoder_set_read_line_cb(lv_img_decoder_t * decoder, lv_img_decoder_read_line_f_t read_line_cb); 216 217 /** 218 * Set a callback to close a decoding session. E.g. close files and free other resources. 219 * @param decoder pointer to an image decoder 220 * @param close_cb a function to close a decoding session 221 */ 222 void lv_img_decoder_set_close_cb(lv_img_decoder_t * decoder, lv_img_decoder_close_f_t close_cb); 223 224 /** 225 * Get info about a built-in image 226 * @param decoder the decoder where this function belongs 227 * @param src the image source: pointer to an `lv_img_dsc_t` variable, a file path or a symbol 228 * @param header store the image data here 229 * @return LV_RES_OK: the info is successfully stored in `header`; LV_RES_INV: unknown format or other error. 230 */ 231 lv_res_t lv_img_decoder_built_in_info(lv_img_decoder_t * decoder, const void * src, lv_img_header_t * header); 232 233 /** 234 * Open a built in image 235 * @param decoder the decoder where this function belongs 236 * @param dsc pointer to decoder descriptor. `src`, `style` are already initialized in it. 237 * @return LV_RES_OK: the info is successfully stored in `header`; LV_RES_INV: unknown format or other error. 238 */ 239 lv_res_t lv_img_decoder_built_in_open(lv_img_decoder_t * decoder, lv_img_decoder_dsc_t * dsc); 240 241 /** 242 * Decode `len` pixels starting from the given `x`, `y` coordinates and store them in `buf`. 243 * Required only if the "open" function can't return with the whole decoded pixel array. 244 * @param decoder pointer to the decoder the function associated with 245 * @param dsc pointer to decoder descriptor 246 * @param x start x coordinate 247 * @param y start y coordinate 248 * @param len number of pixels to decode 249 * @param buf a buffer to store the decoded pixels 250 * @return LV_RES_OK: ok; LV_RES_INV: failed 251 */ 252 lv_res_t lv_img_decoder_built_in_read_line(lv_img_decoder_t * decoder, lv_img_decoder_dsc_t * dsc, lv_coord_t x, 253 lv_coord_t y, lv_coord_t len, uint8_t * buf); 254 255 /** 256 * Close the pending decoding. Free resources etc. 257 * @param decoder pointer to the decoder the function associated with 258 * @param dsc pointer to decoder descriptor 259 */ 260 void lv_img_decoder_built_in_close(lv_img_decoder_t * decoder, lv_img_decoder_dsc_t * dsc); 261 262 /********************** 263 * MACROS 264 **********************/ 265 266 #ifdef __cplusplus 267 } /* extern "C" */ 268 #endif 269 270 #endif /*LV_TEMPL_H*/ 271
