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