From 9056b5ee1bfea6796307bdf983a4a00ea47fe9f0 Mon Sep 17 00:00:00 2001 From: Gabor Kiss-Vamosi Date: Mon, 7 Jun 2021 13:21:00 +0200 Subject: [PATCH] docs(color) update colors' docs --- docs/overview/color.md | 155 +++++++++++++++++++++++++++++++++++++++++ docs/overview/index.md | 1 + 2 files changed, 156 insertions(+) create mode 100644 docs/overview/color.md diff --git a/docs/overview/color.md b/docs/overview/color.md new file mode 100644 index 0000000000..7c19f23d6f --- /dev/null +++ b/docs/overview/color.md @@ -0,0 +1,155 @@ +```eval_rst +.. include:: /header.rst +:github_url: |github_link_base|/overview/color.md +``` +# Colors + +The color module handles all color-related functions like changing color depth, creating colors from hex code, converting between color depths, mixing colors, etc. + +`lv_color_t` is used to store a color. Its fileds are set according to `LV_COLOR_DEPTH` in `lv_conf.h`. (See below) + +You may set `LV_COLOR_16_SWAP` in `lv_conf.h` to swap the bytes of *RGB565* colors. It's useful if you send the 16-bit colors via a byte-oriented interface like SPI. +As 16-bit numbers are stored in Little Endian format (lower byte on 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. + +## Creating colors + +### RGB +Create colors from Red, Green and Blue channel values +```c +//All channels are 0-255 +lv_color_t c = lv_color_make(red, green, blue); + +//From hex code 0x000000..0xFFFFFF interpreted as RED + GREEN + BLUE +lv_color_t c = lv_color_hex(0x123456); + +//From 3 digits. Same as lv_color_hex(0x112233) +lv_color_t c = lv_color_hex3(0x123); +``` + +### HSV +Create colors from Hue, Saturation and Value values + +```c +//h = 0..359, s = 0..100, v = 0..100 +lv_color_t c = lv_color_hsv_to_rgb(h, s, v); + +//All channels are 0-255 +lv_color_hsv_t c_hsv = lv_color_rgb_to_hsv(r, g, b); + + +//From lv_color_t variable +lv_color_hsv_t c_hsv = lv_color_to_hsv(color); + +### Palette +LVGL includes [material design's palette](https://vuetifyjs.com/en/styles/colors/#material-colors). In this all color has a main, 4 darker and 5 lighter variants. + +The name of the palettes are the follwings: +- `LV_PALETTE_RED` +- `LV_PALETTE_PINK` +- `LV_PALETTE_PURPLE` +- `LV_PALETTE_DEEP_PURPLE` +- `LV_PALETTE_INDIGO` +- `LV_PALETTE_BLUE` +- `LV_PALETTE_LIGHT_BLUE` +- `LV_PALETTE_CYAN` +- `LV_PALETTE_TEAL` +- `LV_PALETTE_GREEN` +- `LV_PALETTE_LIGHT_GREEN` +- `LV_PALETTE_LIME` +- `LV_PALETTE_YELLOW` +- `LV_PALETTE_AMBER` +- `LV_PALETTE_ORANGE` +- `LV_PALETTE_DEEP_ORANGE` +- `LV_PALETTE_BROWN` +- `LV_PALETTE_BLUE_GREY` +- `LV_PALETTE_GREY` + + +To get the main color use `lv_color_t c = lv_palette_main(LV_PALETTE_...)`. + +For the lighter variants of a palette color use `lv_color_t c = lv_palette_lighten(LV_PALETTE_..., v)`. `v` can be 1..5. +For the darker variants of a palette color use `lv_color_t c = lv_palette_darken(LV_PALETTE_..., v)`. `v` can be 1..4. + +### Modify and mix colors +The following functions can modify a color: +```c +//Lighten a color. 0: no change, 255: white +lv_color_t c = lv_color_lighten(c, lvl); + +//Darken a color. 0: no change, 255: black +lv_color_t c = lv_color_darken(lv_color_t c, lv_opa_t lvl); + +//Lighten or darken a color. 0: black, 128: no change 255: black +lv_color_t c = lv_color_change_lightness(lv_color_t c, lv_opa_t lvl); + + +Mix 2 color with a given ratio 0: full c2, 255: full c1, 128: half c1 and half c2 +lv_color_t c = lv_color_mix(c1, c2, ratio); +``` + +## Opacity +To describe opacity the `lv_opa_t` type is created as a wrapper to `uint8_t`. Some defines are also introduced: + +- `LV_OPA_TRANSP` Value: 0, means the opacity makes the color completely transparent +- `LV_OPA_10` Value: 25, means the color covers only a little +- `LV_OPA_20 ... OPA_80` come logically +- `LV_OPA_90` Value: 229, means the color near completely covers +- `LV_OPA_COVER` Value: 255, means the color completely covers + +You can also use the `LV_OPA_*` defines in `lv_color_mix()` as a *ratio*. + + +## Color types +The following variable types are defined by the color module: + +- `lv_color1_t` Store monochrome color. For compatibility, it also has R, G, B fields but they are always the same value (1 byte) +- `lv_color8_t` A structure to store R (3 bit),G (3 bit),B (2 bit) components for 8-bit colors (1 byte) +- `lv_color16_t` A structure to store R (5 bit),G (6 bit),B (5 bit) components for 16-bit colors (2 byte) +- `lv_color32_t` A structure to store R (8 bit),G (8 bit), B (8 bit) components for 24-bit colors (4 byte) +- `lv_color_t` Equal to `lv_color1/8/16/24_t` according to color depth settings +- `lv_color_int_t` `uint8_t`, `uint16_t` or `uint32_t` according to color depth setting. Used to build color arrays from plain numbers. +- `lv_opa_t` A simple `uint8_`t type to describe opacity. + +The `lv_color_t`, `lv_color1_t`, `lv_color8_t`, `lv_color16_t` and `lv_color32_t` types have got four fields: + +- `ch.red` red channel +- `ch.green` green channel +- `ch.blue` blue channel +- `full*` red + green + blue as one number + +You can set the current color depth in *lv_conf.h*, by setting the `LV_COLOR_DEPTH` define to 1 (monochrome), 8, 16 or 32. + + +### Convert color +You 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: + +```c +lv_color_t c; +c.red = 0x38; +c.green = 0x70; +c.blue = 0xCC; + +lv_color1_t c1; +c1.full = lv_color_to1(c); /*Return 1 for light colors, 0 for dark colors*/ + +lv_color8_t c8; +c8.full = lv_color_to8(c); /*Give a 8 bit number with the converted color*/ + +lv_color16_t c16; +c16.full = lv_color_to16(c); /*Give a 16 bit number with the converted color*/ + +lv_color32_t c24; +c32.full = lv_color_to32(c); /*Give a 32 bit number with the converted color*/ +``` + + +## API + + +```eval_rst + +.. doxygenfile:: lv_color.h + :project: lvgl + +``` diff --git a/docs/overview/index.md b/docs/overview/index.md index 93126fa346..b0d806f4d8 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -20,6 +20,7 @@ event indev display + color font image file-system