Feature: RGBLight layers (#7768)

* New feature: RGBLIGHT_LAYERS

This feature allows users to define multiple independent layers of lighting
that can be toggled on and off individually, making it easy to use your
RGB lighting to indicate things like active keyboard layer & modifier state.

* Demonstrate built in functions for layer state checking

Also link the video in the docs.

* Follow existing pattern for setting rgblight_status flags

* Eliminate rgblight_is_static_mode since it's not needed

Just check to see if the timer is enabled directly.

1 files changed, 62 insertions, 0 deletions

diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md
index 69a6aaaed..a000241f8 100644
--- a/docs/feature_rgblight.md
+++ b/docs/feature_rgblight.md
@@ -172,6 +172,62 @@ const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31};
 const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64};
 ```
 
+## Lighting Layers
+
+By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make
+it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do. 
+
+To define a layer, we modify `keymap.c` to list out LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently:
+
+```c
+// Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore!
+const rgblight_segment_t PROGMEM my_capslock_layer[] = RGBLIGHT_LAYER_SEGMENTS(
+	{6, 4, HSV_RED},       // Light 4 LEDs, starting with LED 6
+	{12, 4, HSV_RED}       // Light 4 LEDs, starting with LED 12
+);
+// Light LEDs 9 & 10 in cyan when keyboard layer 1 is active
+const rgblight_segment_t PROGMEM my_layer1_layer[] = RGBLIGHT_LAYER_SEGMENTS(
+	{9, 2, HSV_CYAN}
+);
+// Light LEDs 11 & 12 in purple when keyboard layer 2 is active
+const rgblight_segment_t PROGMEM my_layer2_layer[] = RGBLIGHT_LAYER_SEGMENTS(
+	{11, 2, HSV_PURPLE}, 
+);
+// etc..
+```
+
+We combine these layers into an array using the `RGBLIGHT_LAYERS_LIST` macro, and assign it to the `rgblight_layers` variable during keyboard setup. Note that you can only define up to 8 lighting layers. Any extra layers will be ignored. Since the different lighting layers overlap, the order matters in the array, with later layers taking precedence:
+
+```c
+// Now define the array of layers. Later layers take precedence
+const rgblight_segment_t* const PROGMEM my_rgb_layers[] = RGBLIGHT_LAYERS_LIST(
+	my_capslock_layer,
+	my_layer1_layer,    // Overrides caps lock layer
+	my_layer2_layer     // Overrides other layers
+);
+
+void keyboard_post_init_user(void) {
+	// Enable the LED layers
+	rgblight_layers = my_rgb_layers;
+}
+```
+
+Finally, we enable and disable the lighting layers whenever the state of the keyboard changes:
+
+```c
+layer_state_t layer_state_set_user(layer_state_t state) {
+	// Both layers will light up if both kb layers are active
+	rgblight_set_layer_state(1, layer_state_cmp(state, 1));
+	rgblight_set_layer_state(2, layer_state_cmp(state, 2));
+	return state;
+}
+
+bool led_update_user(led_t led_state) {
+	rgblight_set_layer_state(0, led_state.caps_lock);
+	return true;
+}
+```
+
 ## Functions
 
 If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight.h) for the full list, but the most commonly used functions include:
@@ -263,6 +319,12 @@ rgblight_sethsv(HSV_GREEN, 2); // led 2
 |`rgblight_sethsv(h, s, v)`                  |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 |
 |`rgblight_sethsv_noeeprom(h, s, v)`         |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) |
 
+#### layer functions
+|Function                                    |Description  |
+|--------------------------------------------|-------------|
+|`rgblight_get_layer_state(i)`               |Returns `true` if lighting layer `i` is enabled |
+|`rgblight_set_layer_state(i, is_on)`        |Enable or disable lighting layer `i` based on value of `bool is_on` |
+
 #### query
 |Function               |Description      |
 |-----------------------|-----------------|