summaryrefslogtreecommitdiff
path: root/docs/feature_rgblight.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/feature_rgblight.md')
-rw-r--r--docs/feature_rgblight.md62
1 files changed, 62 insertions, 0 deletions
diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md
index 69a6aaaed6..a000241f8b 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 |
|-----------------------|-----------------|