drashna/qmk_firmware
1
0
Fork 0
Code Activity Actions

Separate RGBLight/RGB Matrix keycode handling (#23679)

Browse source 
* Separate RGBLight/RGB Matrix keycode handling

* Remove `_DISABLE_KEYCODES` handling

* Update RGB Matrix keycode docs

* Update underglow keycodes for previously migrated boards

* Update keycodes for boards with custom handling

* Fix typos

* Fix bad merge
This commit is contained in:
Ryan 2024-10-13 03:43:50 +11:00 • committed by GitHub
parent 5c97a78ce6
commit 6fa11bf219
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
267 changed files with 1228 additions and 2276 deletions
Download patch file Download diff file Expand all files Collapse all files

50
docs/features/rgb_matrix.md
View file

@ -81,38 +81,21 @@ As mentioned earlier, the center of the keyboard by default is expected to be `{
## Keycodes {#keycodes}
All RGB keycodes are currently shared with the RGBLIGHT system:
|Key |Aliases |Description |
|-------------------|----------|--------------------------------------------------------------------------------------|
|`RGB_TOG` | |Toggle RGB lighting on or off |
|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held |
|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held |
|`RGB_HUI` | |Increase hue, decrease hue when Shift is held |
|`RGB_HUD` | |Decrease hue, increase hue when Shift is held |
|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held |
|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held |
|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held |
|`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held |
|`RGB_SPI` | |Increase effect speed (does not support eeprom yet), decrease speed when Shift is held|
|`RGB_SPD` | |Decrease effect speed (does not support eeprom yet), increase speed when Shift is held|
|`RGB_MODE_PLAIN` |`RGB_M_P` |Static (no animation) mode |
|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode |
|`RGB_MODE_RAINBOW` |`RGB_M_R` |Full gradient scrolling left to right (uses the `RGB_MATRIX_CYCLE_LEFT_RIGHT` mode) |
|`RGB_MODE_SWIRL` |`RGB_M_SW`|Full gradient spinning pinwheel around center of keyboard (uses `RGB_MATRIX_CYCLE_PINWHEEL` mode) |
* `RGB_MODE_*` keycodes will generally work, but not all of the modes are currently mapped to the correct effects for the RGB Matrix system.
`RGB_MODE_PLAIN`, `RGB_MODE_BREATHE`, `RGB_MODE_RAINBOW`, and `RGB_MODE_SWIRL` are the only ones that are mapped properly. The rest don't have a direct equivalent, and are not mapped.
::: tip
`RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUD)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead.
:::
::: warning
By default, if you have both the [RGB Light](rgblight) and the RGB Matrix feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature.
:::
|Key |Aliases |Description |
|-------------------------------|---------|-----------------------------------|
|`QK_RGB_MATRIX_ON` |`RM_ON` |Turn on RGB Matrix |
|`QK_RGB_MATRIX_OFF` |`RM_OFF` |Turn off RGB Matrix |
|`QK_RGB_MATRIX_TOGGLE` |`RM_TOGG`|Toggle RGB Matrix on or off |
|`QK_RGB_MATRIX_MODE_NEXT` |`RM_NEXT`|Cycle through animations |
|`QK_RGB_MATRIX_MODE_PREVIOUS` |`RM_PREV`|Cycle through animations in reverse|
|`QK_RGB_MATRIX_HUE_UP` |`RM_HUEU`|Cycle through hue |
|`QK_RGB_MATRIX_HUE_DOWN` |`RM_HUED`|Cycle through hue in reverse |
|`QK_RGB_MATRIX_SATURATION_UP` |`RM_SATU`|Increase the saturation |
|`QK_RGB_MATRIX_SATURATION_DOWN`|`RM_SATD`|Decrease the saturation |
|`QK_RGB_MATRIX_VALUE_UP` |`RM_VALU`|Increase the brightness level |
|`QK_RGB_MATRIX_VALUE_DOWN` |`RM_VALD`|Decrease the brightness level |
|`QK_RGB_MATRIX_SPEED_UP` |`RM_SPDU`|Increase the animation speed |
|`QK_RGB_MATRIX_SPEED_DOWN` |`RM_SPDD`|Decrease the animation speed |
## RGB Matrix Effects {#rgb-matrix-effects}
@ -289,7 +272,7 @@ Solid reactive effects will pulse RGB light on key presses with user configurabl
#define RGB_MATRIX_SOLID_REACTIVE_GRADIENT_MODE
```
Gradient mode will loop through the color wheel hues over time and its duration can be controlled with the effect speed keycodes (`RGB_SPI`/`RGB_SPD`).
Gradient mode will loop through the color wheel hues over time and its duration can be controlled with the effect speed keycodes (`RM_SPDU`/`RM_SPDD`).
## Custom RGB Matrix Effects {#custom-rgb-matrix-effects}
@ -396,7 +379,6 @@ These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master
#define RGB_MATRIX_DEFAULT_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set
#define RGB_MATRIX_DEFAULT_SPD 127 // Sets the default animation speed, if none has been set
#define RGB_MATRIX_DEFAULT_FLAGS LED_FLAG_ALL // Sets the default LED flags, if none has been set
#define RGB_MATRIX_DISABLE_KEYCODES // disables control of rgb matrix by keycodes (must use code functions to control the feature)
#define RGB_MATRIX_SPLIT { X, Y } // (Optional) For split keyboards, the number of LEDs connected on each half. X = left, Y = Right.
// If reactive effects are enabled, you also will want to enable SPLIT_TRANSPORT_MIRROR
#define RGB_TRIGGER_ON_KEYDOWN // Triggers RGB keypress events on key down. This makes RGB control feel more responsive. This may cause RGB to not function properly on some boards