1
/**
2
 * @file lv_draw_img.h
3
 *
4
 */
5

6
#ifndef LV_DRAW_IMG_H
7
#define LV_DRAW_IMG_H
8

9
#ifdef __cplusplus
10
extern "C" {
11
#endif
12

13
/*********************
14
 *      INCLUDES
15
 *********************/
16
#include "lv_draw.h"
17
#include "../lv_core/lv_obj.h"
18

19
/*********************
20
 *      DEFINES
21
 *********************/
22
#define LV_IMG_DECODER_OPEN_FAIL    ((void*)(-1))
23

24
/**********************
25
 *      TYPEDEFS
26
 **********************/
27
struct _lv_img_t;
28

29
typedef struct {
30

31
    /* The first 8 bit is very important to distinguish the different source types.
32
     * For more info see `lv_img_get_src_type()` in lv_img.c */
33
    uint32_t cf           :5;    /* Color format: See `lv_img_color_format_t`*/
34
    uint32_t always_zero  :3;    /*It the upper bits of the first byte. Always zero to look like a non-printable character*/
35

36
    uint32_t reserved     :2;   /*Reserved to be used later*/
37

38
    uint32_t w:11;              /*Width of the image map*/
39
    uint32_t h:11;              /*Height of the image map*/
40
} lv_img_header_t;
41

42
/*Image color format*/
43
enum {
44
    LV_IMG_CF_UNKOWN = 0,
45

46
    LV_IMG_CF_RAW,                  /*Contains the file as it is. Needs custom decoder function*/
47
    LV_IMG_CF_RAW_ALPHA,            /*Contains the file as it is. The image has alpha. Needs custom decoder function*/
48
    LV_IMG_CF_RAW_CHROMA_KEYED,     /*Contains the file as it is. The image is chroma keyed. Needs custom decoder function*/
49

50
    LV_IMG_CF_TRUE_COLOR,           /*Color format and depth should match with LV_COLOR settings*/
51
    LV_IMG_CF_TRUE_COLOR_ALPHA,     /*Same as `LV_IMG_CF_TRUE_COLOR` but every pixel has an alpha byte*/
52
    LV_IMG_CF_TRUE_COLOR_CHROMA_KEYED,  /*Same as `LV_IMG_CF_TRUE_COLOR` but LV_COLOR_TRANSP pixels will be transparent*/
53

54
    LV_IMG_CF_INDEXED_1BIT,         /*Can have 2 different colors in a palette (always chroma keyed)*/
55
    LV_IMG_CF_INDEXED_2BIT,         /*Can have 4 different colors in a palette (always chroma keyed)*/
56
    LV_IMG_CF_INDEXED_4BIT,         /*Can have 16 different colors in a palette (always chroma keyed)*/
57
    LV_IMG_CF_INDEXED_8BIT,         /*Can have 256 different colors in a palette (always chroma keyed)*/
58

59
    LV_IMG_CF_ALPHA_1BIT,           /*Can have one color and it can be drawn or not*/
60
    LV_IMG_CF_ALPHA_2BIT,           /*Can have one color but 4 different alpha value*/
61
    LV_IMG_CF_ALPHA_4BIT,           /*Can have one color but 16 different alpha value*/
62
    LV_IMG_CF_ALPHA_8BIT,           /*Can have one color but 256 different alpha value*/
63
};
64
typedef uint8_t lv_img_cf_t;
65

66
/* Image header it is compatible with
67
 * the result image converter utility*/
68
typedef struct
69
{
70
    lv_img_header_t header;
71
    uint32_t data_size;
72
    const uint8_t * data;
73
} lv_img_dsc_t;
74

75
/* Decoder function definitions */
76

77

78
/**
79
 * Get info from an image and store in the `header`
80
 * @param src the image source. Can be a pointer to a C array or a file name (Use `lv_img_src_get_type` to determine the type)
81
 * @param header store the info here
82
 * @return LV_RES_OK: info written correctly; LV_RES_INV: failed
83
 */
84
typedef lv_res_t (*lv_img_decoder_info_f_t)(const void * src, lv_img_header_t * header);
85

86
/**
87
 * Open an image for decoding. Prepare it as it is required to read it later
88
 * @param src the image source. Can be a pointer to a C array or a file name (Use `lv_img_src_get_type` to determine the type)
89
 * @param style the style of image (maybe it will be required to determine a color or something)
90
 * @return there are 3 possible return values:
91
 *    1) buffer with the decoded image
92
 *    2) if can decode the whole image NULL. decoder_read_line will be called to read the image line-by-line
93
 *    3) LV_IMG_DECODER_OPEN_FAIL if the image format is unknown to the decoder or an error occurred
94
 */
95
typedef const uint8_t * (*lv_img_decoder_open_f_t)(const void * src, const lv_style_t * style);
96

97
/**
98
 * Decode `len` pixels starting from the given `x`, `y` coordinates and store them in `buf`.
99
 * Required only if the "open" function can't return with the whole decoded pixel array.
100
 * @param x start x coordinate
101
 * @param y startt y coordinate
102
 * @param len number of pixels to decode
103
 * @param buf a buffer to store the decoded pixels
104
 * @return LV_RES_OK: ok; LV_RES_INV: failed
105
 */
106
typedef lv_res_t (*lv_img_decoder_read_line_f_t)(lv_coord_t x, lv_coord_t y, lv_coord_t len, uint8_t * buf);
107

108
/**
109
 * Close the pending decoding. Free resources etc.
110
 */
111
typedef void (*lv_img_decoder_close_f_t)(void);
112

113
/**********************
114
 * GLOBAL PROTOTYPES
115
 **********************/
116

117
/**
118
 * Draw an image
119
 * @param coords the coordinates of the image
120
 * @param mask the image will be drawn only in this area
121
 * @param src pointer to a lv_color_t array which contains the pixels of the image
122
 * @param style style of the image
123
 * @param opa_scale scale down all opacities by the factor
124
 */
125
void lv_draw_img(const lv_area_t * coords, const lv_area_t * mask,
126
                 const void * src, const lv_style_t * style, lv_opa_t opa_scale);
127

128

129
/**
130
 * Get the type of an image source
131
 * @param src pointer to an image source:
132
 *  - pointer to an 'lv_img_t' variable (image stored internally and compiled into the code)
133
 *  - a path to a file (e.g. "S:/folder/image.bin")
134
 *  - or a symbol (e.g. SYMBOL_CLOSE)
135
 * @return type of the image source LV_IMG_SRC_VARIABLE/FILE/SYMBOL/UNKOWN
136
 */
137
lv_img_src_t lv_img_src_get_type(const void * src);
138

139
/**
140
 * Set custom decoder functions. See the typdefs of the function typed above for more info about them
141
 * @param info_fp info get function
142
 * @param open_fp open function
143
 * @param read_fp read line function
144
 * @param close_fp clode function
145
 */
146
void lv_img_decoder_set_custom(lv_img_decoder_info_f_t  info_fp, lv_img_decoder_open_f_t  open_fp,
147
                               lv_img_decoder_read_line_f_t read_fp, lv_img_decoder_close_f_t close_fp);
148

149
lv_res_t lv_img_dsc_get_info(const char * src, lv_img_header_t * header);
150

151
uint8_t lv_img_color_format_get_px_size(lv_img_cf_t cf);
152

153
bool lv_img_color_format_is_chroma_keyed(lv_img_cf_t cf);
154

155
bool lv_img_color_format_has_alpha(lv_img_cf_t cf);
156

157

158
/**********************
159
 *      MACROS
160
 **********************/
161

162

163
#ifdef __cplusplus
164
} /* extern "C" */
165
#endif
166

167
#endif /*LV_TEMPL_H*/
168

169