1# Colors
2
3The color module handles all color-related functions like changing color depth, creating colors from hex code, converting between color depths, mixing colors, etc.
4
5The type `lv_color_t` is used to store a color. Its fields are set according to `LV_COLOR_DEPTH` in `lv_conf.h`. (See below)
6
7You may set `LV_COLOR_16_SWAP` in `lv_conf.h` to swap bytes of *RGB565* colors. You may need this when sending 16-bit colors via a byte-oriented interface like SPI. As 16-bit numbers are stored in little-endian format (lower byte at the lower address), the interface will send the lower byte first. However, displays usually need the higher byte first. A mismatch in the byte order will result in highly distorted colors.
8
9## Creating colors
10
11### RGB
12Create colors from Red, Green and Blue channel values:
13```c
14//All channels are 0-255
15lv_color_t c = lv_color_make(red, green, blue);
16
17//From hex code 0x000000..0xFFFFFF interpreted as RED + GREEN + BLUE
18lv_color_t c = lv_color_hex(0x123456);
19
20//From 3 digits. Same as lv_color_hex(0x112233)
21lv_color_t c = lv_color_hex3(0x123);
22```
23
24### HSV
25Create colors from Hue, Saturation and Value values:
26
27```c
28//h = 0..359, s = 0..100, v = 0..100
29lv_color_t c = lv_color_hsv_to_rgb(h, s, v);
30
31//All channels are 0-255
32lv_color_hsv_t c_hsv = lv_color_rgb_to_hsv(r, g, b);
33
34
35//From lv_color_t variable
36lv_color_hsv_t c_hsv = lv_color_to_hsv(color);
37```
38
39### Palette
40LVGL includes [Material Design's palette](https://vuetifyjs.com/en/styles/colors/#material-colors) of colors. In this system all named colors have a nominal main color as well as four darker and five lighter variants.
41
42The names of the colors are as follows:
43- `LV_PALETTE_RED`
44- `LV_PALETTE_PINK`
45- `LV_PALETTE_PURPLE`
46- `LV_PALETTE_DEEP_PURPLE`
47- `LV_PALETTE_INDIGO`
48- `LV_PALETTE_BLUE`
49- `LV_PALETTE_LIGHT_BLUE`
50- `LV_PALETTE_CYAN`
51- `LV_PALETTE_TEAL`
52- `LV_PALETTE_GREEN`
53- `LV_PALETTE_LIGHT_GREEN`
54- `LV_PALETTE_LIME`
55- `LV_PALETTE_YELLOW`
56- `LV_PALETTE_AMBER`
57- `LV_PALETTE_ORANGE`
58- `LV_PALETTE_DEEP_ORANGE`
59- `LV_PALETTE_BROWN`
60- `LV_PALETTE_BLUE_GREY`
61- `LV_PALETTE_GREY`
62
63
64To get the main color use `lv_color_t c = lv_palette_main(LV_PALETTE_...)`.
65
66For the lighter variants of a palette color use `lv_color_t c = lv_palette_lighten(LV_PALETTE_..., v)`. `v` can be 1..5.
67For the darker variants of a palette color use `lv_color_t c = lv_palette_darken(LV_PALETTE_..., v)`. `v` can be 1..4.
68
69### Modify and mix colors
70The following functions can modify a color:
71```c
72// Lighten a color. 0: no change, 255: white
73lv_color_t c = lv_color_lighten(c, lvl);
74
75// Darken a color. 0: no change, 255: black
76lv_color_t c = lv_color_darken(lv_color_t c, lv_opa_t lvl);
77
78// Lighten or darken a color. 0: black, 128: no change 255: white
79lv_color_t c = lv_color_change_lightness(lv_color_t c, lv_opa_t lvl);
80
81
82// Mix two colors with a given ratio 0: full c2, 255: full c1, 128: half c1 and half c2
83lv_color_t c = lv_color_mix(c1, c2, ratio);
84```
85
86### Built-in colors
87`lv_color_white()` and `lv_color_black()` return `0xFFFFFF` and `0x000000` respectively.
88
89## Opacity
90To describe opacity the `lv_opa_t` type is created from `uint8_t`. Some special purpose defines are also introduced:
91
92- `LV_OPA_TRANSP` Value: 0, means no opacity making the color completely transparent
93- `LV_OPA_10` Value: 25, means the color covers only a little
94- `LV_OPA_20 ... OPA_80` follow logically
95- `LV_OPA_90` Value: 229, means the color near completely covers
96- `LV_OPA_COVER` Value: 255, means the color completely covers (full opacity)
97
98You can also use the `LV_OPA_*` defines in `lv_color_mix()` as a mixing *ratio*.
99
100
101## Color types
102The following variable types are defined by the color module:
103
104- `lv_color1_t` Monochrome color. Also has R, G, B fields for compatibility but they are always the same value (1 byte)
105- `lv_color8_t` A structure to store R (3 bit),G (3 bit),B (2 bit) components for 8-bit colors (1 byte)
106- `lv_color16_t` A structure to store R (5 bit),G (6 bit),B (5 bit) components for 16-bit colors (2 byte)
107- `lv_color32_t` A structure to store R (8 bit),G (8 bit), B (8 bit) components for 24-bit colors (4 byte)
108- `lv_color_t` Equal to `lv_color1/8/16/24_t` depending on the configured color depth setting
109- `lv_color_int_t` `uint8_t`, `uint16_t` or `uint32_t` depending on the color depth setting. Used to build color arrays from plain numbers.
110- `lv_opa_t` A simple `uint8_t` type to describe opacity.
111
112The `lv_color_t`, `lv_color1_t`, `lv_color8_t`, `lv_color16_t` and `lv_color32_t` types have four fields:
113
114- `ch.red` red channel
115- `ch.green` green channel
116- `ch.blue` blue channel
117- `full*` red + green + blue as one number
118
119You can set the current color depth in *lv_conf.h*, by setting the `LV_COLOR_DEPTH` define to 1 (monochrome), 8, 16 or 32.
120
121
122### Convert color
123You can convert a color from the current color depth to another. The converter functions return with a number, so you have to use the `full` field to map a converted color back into a structure:
124
125```c
126lv_color_t c;
127c.red   = 0x38;
128c.green = 0x70;
129c.blue  = 0xCC;
130
131lv_color1_t c1;
132c1.full = lv_color_to1(c);	/*Return 1 for light colors, 0 for dark colors*/
133
134lv_color8_t c8;
135c8.full = lv_color_to8(c);	/*Give a 8 bit number with the converted color*/
136
137lv_color16_t c16;
138c16.full = lv_color_to16(c); /*Give a 16 bit number with the converted color*/
139
140lv_color32_t c24;
141c32.full = lv_color_to32(c);	/*Give a 32 bit number with the converted color*/
142```
143
144
145## API
146
147
148```eval_rst
149
150.. doxygenfile:: lv_color.h
151  :project: lvgl
152
153```
154