1 /*
2  * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #pragma once
8 
9 #include <stdint.h>
10 
11 #ifdef __cplusplus
12 extern "C" {
13 #endif
14 
15 /*---------------------------------------------------------------
16                       Color Space
17 ---------------------------------------------------------------*/
18 /**
19  * @brief Color Space
20  *
21  * @note Save enum 0 for special purpose
22  */
23 typedef enum {
24     COLOR_SPACE_RAW = 1,     ///< Color space raw
25     COLOR_SPACE_RGB,         ///< Color space rgb
26     COLOR_SPACE_YUV,         ///< Color space yuv
27     COLOR_SPACE_GRAY,        ///< Color space gray
28     COLOR_SPACE_ARGB,        ///< Color space argb
29     COLOR_SPACE_ALPHA,       ///< Color space alpha (A)
30     COLOR_SPACE_CLUT,        ///< Color look-up table (L)
31 } color_space_t;
32 
33 /*---------------------------------------------------------------
34                       Color Pixel Format
35 ---------------------------------------------------------------*/
36 /**
37  * @brief Raw Format
38  */
39 typedef enum {
40     COLOR_PIXEL_RAW8,     ///< 8 bits per pixel
41     COLOR_PIXEL_RAW10,    ///< 10 bits per pixel
42     COLOR_PIXEL_RAW12,    ///< 12 bits per pixel
43 } color_pixel_raw_format_t;
44 
45 /**
46  * @brief RGB Format
47  */
48 typedef enum {
49     COLOR_PIXEL_RGB888,      ///< 24 bits, 8 bits per R/G/B value
50     COLOR_PIXEL_RGB666,      ///< 18 bits, 6 bits per R/G/B value
51     COLOR_PIXEL_RGB565,      ///< 16 bits, 5 bits per R/B value, 6 bits for G value
52 } color_pixel_rgb_format_t;
53 
54 /**
55  * @brief YUV Format
56  */
57 typedef enum {
58     COLOR_PIXEL_YUV444,    ///< 24 bits, 8 bits per Y/U/V value
59     COLOR_PIXEL_YUV422,    ///< 16 bits, 8-bit Y per pixel, 8-bit U and V per two pixels
60     COLOR_PIXEL_YUV420,    ///< 12 bits, 8-bit Y per pixel, 8-bit U and V per four pixels
61     COLOR_PIXEL_YUV411,    ///< 12 bits, 8-bit Y per pixel, 8-bit U and V per four pixels
62 } color_pixel_yuv_format_t;
63 
64 /**
65  * @brief Gray Format
66  */
67 typedef enum {
68     COLOR_PIXEL_GRAY4,    ///< 4 bits, grayscale
69     COLOR_PIXEL_GRAY8,    ///< 8 bits, grayscale
70 } color_pixel_gray_format_t;
71 
72 /**
73  * @brief ARGB Format
74  */
75 typedef enum {
76     COLOR_PIXEL_ARGB8888,   ///< 32 bits, 8 bits per A(alpha)/R/G/B value
77 } color_pixel_argb_format_t;
78 
79 /**
80  * @brief Alpha(A) Format
81  */
82 typedef enum {
83     COLOR_PIXEL_A4,   ///< 4 bits, opacity only
84     COLOR_PIXEL_A8,   ///< 8 bits, opacity only
85 } color_pixel_alpha_format_t;
86 
87 /**
88  * @brief CLUT(L) Format
89  */
90 typedef enum {
91     COLOR_PIXEL_L4,   ///< 4 bits, color look-up table
92     COLOR_PIXEL_L8,   ///< 8 bits, color look-up table
93 } color_pixel_clut_format_t;
94 
95 /*---------------------------------------------------------------
96                 Color Space Pixel Struct Type
97 ---------------------------------------------------------------*/
98 ///< Bitwidth of the `color_space_pixel_format_t::color_space` field
99 #define COLOR_SPACE_BITWIDTH                 8
100 ///< Bitwidth of the `color_space_pixel_format_t::pixel_format` field
101 #define COLOR_PIXEL_FORMAT_BITWIDTH          24
102 ///< Helper to get the color_space from a unique color type ID
103 #define COLOR_SPACE_TYPE(color_type_id)      (((color_type_id) >> COLOR_PIXEL_FORMAT_BITWIDTH) & ((1 << COLOR_SPACE_BITWIDTH) - 1))
104 ///< Helper to get the pixel_format from a unique color type ID
105 #define COLOR_PIXEL_FORMAT(color_type_id)    ((color_type_id) & ((1 << COLOR_PIXEL_FORMAT_BITWIDTH) - 1))
106 ///< Make a unique ID of a color based on the value of color space and pixel format
107 #define COLOR_TYPE_ID(color_space, pixel_format) (((color_space) << COLOR_PIXEL_FORMAT_BITWIDTH) | (pixel_format))
108 
109 /**
110  * @brief Color Space Info Structure
111  */
112 typedef union {
113     struct {
114         uint32_t pixel_format: COLOR_PIXEL_FORMAT_BITWIDTH;    ///< Format of a certain color space type
115         uint32_t color_space: COLOR_SPACE_BITWIDTH;            ///< Color space type
116     };
117     uint32_t color_type_id;                                    ///< Unique type of a certain color pixel format
118 } color_space_pixel_format_t;
119 
120 /*---------------------------------------------------------------
121                       Color Conversion
122 ---------------------------------------------------------------*/
123 /**
124  * @brief Color range
125  * @note The difference between a full range color and a limited range color is
126  *       the amount of shades of black and white that they can display.
127  */
128 typedef enum {
129     COLOR_RANGE_LIMIT, /*!< Limited color range, 16 is the darkest black and 235 is the brightest white */
130     COLOR_RANGE_FULL,  /*!< Full color range, 0 is the darkest black and 255 is the brightest white */
131 } color_range_t;
132 
133 /**
134  * @brief The standard used for conversion between RGB and YUV
135  */
136 typedef enum {
137     COLOR_CONV_STD_RGB_YUV_BT601, /*!< YUV<->RGB conversion standard: BT.601 */
138     COLOR_CONV_STD_RGB_YUV_BT709, /*!< YUV<->RGB conversion standard: BT.709 */
139 } color_conv_std_rgb_yuv_t;
140 
141 /*---------------------------------------------------------------
142                       Color Endian
143 ---------------------------------------------------------------*/
144 
145 /**
146  * @brief RGB element order
147  */
148 typedef enum {
149     COLOR_RGB_ELEMENT_ORDER_RGB, /*!< RGB element order: RGB */
150     COLOR_RGB_ELEMENT_ORDER_BGR, /*!< RGB element order: BGR */
151 } color_rgb_element_order_t;
152 
153 /*---------------------------------------------------------------
154                 Data Structure for Color Pixel Unit
155 ---------------------------------------------------------------*/
156 
157 /**
158  * @brief Data structure for ARGB8888 pixel unit
159  */
160 typedef union {
161     struct {
162         uint32_t b: 8;      /*!< B component [0, 255] */
163         uint32_t g: 8;      /*!< G component [0, 255] */
164         uint32_t r: 8;      /*!< R component [0, 255] */
165         uint32_t a: 8;      /*!< A component [0, 255] */
166     };
167     uint32_t val;           /*!< 32-bit ARGB8888 value */
168 } color_pixel_argb8888_data_t;
169 
170 /**
171  * @brief Data structure for RGB888 pixel unit
172  */
173 typedef struct {
174     uint8_t b;      /*!< B component [0, 255] */
175     uint8_t g;      /*!< G component [0, 255] */
176     uint8_t r;      /*!< R component [0, 255] */
177 } color_pixel_rgb888_data_t;
178 
179 /**
180  * @brief Data structure for RGB565 pixel unit
181  */
182 typedef union {
183     struct {
184         uint16_t b: 5;      /*!< B component [0, 31] */
185         uint16_t g: 6;      /*!< G component [0, 63] */
186         uint16_t r: 5;      /*!< R component [0, 31] */
187     };
188     uint16_t val;           /*!< 16-bit RGB565 value */
189 } color_pixel_rgb565_data_t;
190 
191 #ifdef __cplusplus
192 }
193 #endif
194