rgb_led struct conversion (aka: Per led (key) type rgb matrix effects - part 2) ...

[qmk_firmware.git] / docs / feature_rgb_matrix.md

diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
index 91ec77ace086dfad67baa46c3b6f779025b1add0..5eb9d5536e1411cdec7af20253042abd0b671ede 100644 (file)
--- a/docs/feature_rgb_matrix.md
+++ b/docs/feature_rgb_matrix.md
@@ -124,21 +124,25 @@ Configure the hardware via your `config.h`:
 
 ---
 
-From this point forward the configuration is the same for all the drivers. The struct rgb_led array tells the system for each led, what key electrical matrix it represents, what the physical position is on the board, and if the led is for a modifier key or not. Here is a brief example:
+From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example:
 
 ```C
-rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = {
-/*  {row | col << 4}
-    *    |         {x=0..224, y=0..64}
-    *    |            |              flags
-    *    |            |                | */
-    {{0|(0<<4)},   {20.36*0, 21.33*0}, 1},
-    {{0|(1<<4)},   {20.36*1, 21.33*0}, 4},
-    ....
-}
+const led_config_t g_led_config = { {
+  // Key Matrix to LED Index
+  {   5, NO_LED, NO_LED,   0 },
+  { NO_LED, NO_LED, NO_LED, NO_LED },
+  {   4, NO_LED, NO_LED,   1 },
+  {   3, NO_LED, NO_LED,   2 }
+}, {
+  // LED Index to Physical Position
+  { 188,  16 }, { 187,  48 }, { 149,  64 }, { 112,  64 }, {  37,  48 }, {  38,  16 }
+}, {
+  // LED Index to Flag
+  1, 4, 4, 4, 4, 1
+} };
 ```
 
-The first part, `{row | col << 4}`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `{x=0..224, y=0..64}` represents the LED's physical position on the keyboard. The `x` is between (inclusive) 0-224, and `y` is between (inclusive) 0-64 as the effects are based on this range. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents x, y coordinate 0, 0 and the bottom right of your keyboard represents 224, 64. Using this as a basis, you can use the following formula to calculate the physical position:
+The first part, `// Key Matrix to LED Index`, tells the system what key this LED represents by using the key's electrical matrix row & col. The second part, `// LED Index to Physical Position` represents the LED's physical position on the keyboard. The first value, `x`, is between 0-224 (inclusive), and the second value, `y`, is between 0-64 (inclusive). This range is due to effect that calculate the center or halves for their animations. The easiest way to calculate these positions is imagine your keyboard is a grid, and the top left of the keyboard represents x, y coordinate 0, 0 and the bottom right of your keyboard represents 224, 64. Using this as a basis, you can use the following formula to calculate the physical position:
 
 ```C
 x = 224 / (NUMBER_OF_COLS - 1) * COL_POSITION
@@ -147,7 +151,7 @@ y =  64 / (NUMBER_OF_ROWS - 1) * ROW_POSITION
 
 Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based on the physical layout of your keyboard, not the electrical layout.
 
-`flags` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type.
+`// LED Index to Flag` is a bitmask, whether or not a certain LEDs is of a certain type. It is recommended that LEDs are set to only 1 type.
 
 ## Flags
 
@@ -155,8 +159,8 @@ Where NUMBER_OF_COLS, NUMBER_OF_ROWS, COL_POSITION, & ROW_POSITION are all based
 |------------------------------------|-------------------------------------------|
 |`#define HAS_FLAGS(bits, flags)`    |Returns true if `bits` has all `flags` set.|
 |`#define HAS_ANY_FLAGS(bits, flags)`|Returns true if `bits` has any `flags` set.|
-|`#define LED_FLAG_NONE      0x00`   |If thes LED has no flags.                  |
-|`#define LED_FLAG_ALL       0xFF`   |If thes LED has all flags.                 |
+|`#define LED_FLAG_NONE      0x00`   |If this LED has no flags.                  |
+|`#define LED_FLAG_ALL       0xFF`   |If this LED has all flags.                 |
 |`#define LED_FLAG_MODIFIER  0x01`   |If the Key for this LED is a modifier.     |
 |`#define LED_FLAG_UNDERGLOW 0x02`   |If the LED is for underglow.               |
 |`#define LED_FLAG_KEYLIGHT  0x04`   |If the LED is for key backlight.           |