1.. _color:
2
3================
4Color (lv_color)
5================
6
7The color module handles all color-related functions like changing color
8depth, creating colors from hex code, converting between color depths,
9mixing colors, etc.
10
11The type :cpp:type:`lv_color_t` is used to store a color in RGB888 format.
12This type and format is used in almost all APIs regardless of :cpp:expr:`LV_COLOR_DEPTH`.
13
14
15
16.. _color_create:
17
18Creating Colors
19***************
20
21RGB
22---
23
24Create colors from Red, Green and Blue channel values:
25
26.. code-block:: c
27
28   /* All channels are 0-255 */
29   lv_color_t c = lv_color_make(red, green, blue);
30
31
32   /* Same but can be used for const initialization as well */
33   lv_color_t c = LV_COLOR_MAKE(red, green, blue);
34
35   /* From hex code 0x000000..0xFFFFFF interpreted as RED + GREEN + BLUE */
36   lv_color_t c = lv_color_hex(0x123456);
37
38   /* From 3 digits. Same as lv_color_hex(0x112233) */
39   lv_color_t c = lv_color_hex3(0x123);
40
41HSV
42---
43
44Create colors from Hue, Saturation and Value values:
45
46.. code-block:: c
47
48   //h = 0..359, s = 0..100, v = 0..100
49   lv_color_t c = lv_color_hsv_to_rgb(h, s, v);
50
51   //All channels are 0-255
52   lv_color_hsv_t c_hsv = lv_color_rgb_to_hsv(r, g, b);
53
54
55   //From lv_color_t variable
56   lv_color_hsv_t c_hsv = lv_color_to_hsv(color);
57
58.. _color_palette:
59
60Palette
61-------
62
63LVGL includes `Material Design's palette <https://vuetifyjs.com/en/styles/colors/#material-colors>`__ of
64colors. In this system all named colors have a nominal main color as
65well as four darker and five lighter variants.
66
67The names of the colors are as follows:
68
69- :c:macro:`LV_PALETTE_RED`
70- :c:macro:`LV_PALETTE_PINK`
71- :c:macro:`LV_PALETTE_PURPLE`
72- :c:macro:`LV_PALETTE_DEEP_PURPLE`
73- :c:macro:`LV_PALETTE_INDIGO`
74- :c:macro:`LV_PALETTE_BLUE`
75- :c:macro:`LV_PALETTE_LIGHT_BLUE`
76- :c:macro:`LV_PALETTE_CYAN`
77- :c:macro:`LV_PALETTE_TEAL`
78- :c:macro:`LV_PALETTE_GREEN`
79- :c:macro:`LV_PALETTE_LIGHT_GREEN`
80- :c:macro:`LV_PALETTE_LIME`
81- :c:macro:`LV_PALETTE_YELLOW`
82- :c:macro:`LV_PALETTE_AMBER`
83- :c:macro:`LV_PALETTE_ORANGE`
84- :c:macro:`LV_PALETTE_DEEP_ORANGE`
85- :c:macro:`LV_PALETTE_BROWN`
86- :c:macro:`LV_PALETTE_BLUE_GREY`
87- :c:macro:`LV_PALETTE_GREY`
88
89To get the main color use
90:cpp:expr:`lv_color_t` ``c =`` :cpp:expr:`lv_palette_main(LV_PALETTE_...)`.
91
92For the lighter variants of a palette color use
93:cpp:expr:`lv_color_t` ``c =`` :cpp:expr:`lv_palette_lighten(LV_PALETTE_..., v)`. ``v`` can be
941..5. For the darker variants of a palette color use
95:cpp:expr:`lv_color_t` ``c =`` :cpp:expr:`lv_palette_darken(LV_PALETTE_..., v)`. ``v`` can be
961..4.
97
98.. _color_modify_and_mix:
99
100Modify and mix colors
101---------------------
102
103The following functions can modify a color:
104
105.. code-block:: c
106
107   // Lighten a color. 0: no change, 255: white
108   lv_color_t c = lv_color_lighten(c, lvl);
109
110   // Darken a color. 0: no change, 255: black
111   lv_color_t c = lv_color_darken(lv_color_t c, lv_opa_t lvl);
112
113   // Lighten or darken a color. 0: black, 128: no change 255: white
114   lv_color_t c = lv_color_change_lightness(lv_color_t c, lv_opa_t lvl);
115
116
117   // Mix two colors with a given ratio 0: full c2, 255: full c1, 128: half c1 and half c2
118   lv_color_t c = lv_color_mix(c1, c2, ratio);
119
120.. _color_builtin:
121
122Built-in colors
123---------------
124
125:cpp:func:`lv_color_white` and :cpp:func:`lv_color_black` return ``0xFFFFFF`` and
126``0x000000`` respectively.
127
128
129
130.. _color_opacity:
131
132Opacity
133*******
134
135To describe opacity the :cpp:type:`lv_opa_t` type is created from ``uint8_t``.
136Some special purpose defines are also introduced:
137
138-  :cpp:enumerator:`LV_OPA_TRANSP` Value: 0, means no opacity making the color
139   completely transparent
140-  :cpp:enumerator:`LV_OPA_10` Value: 25, means the color covers only a little
141-  ``LV_OPA_20 ... OPA_80`` follow logically
142-  :cpp:enumerator:`LV_OPA_90` Value: 229, means the color nearly completely covers
143-  :cpp:enumerator:`LV_OPA_COVER` Value: 255, means the color completely covers (full
144   opacity)
145
146You can also use the ``LV_OPA_*`` defines in :cpp:func:`lv_color_mix` as a
147mixing *ratio*.
148
149
150
151.. _color_api:
152
153API
154***
155