diff options
author | Ryan <[email protected]> | 2024-10-13 03:43:50 +1100 |
---|---|---|
committer | GitHub <[email protected]> | 2024-10-12 18:43:50 +0200 |
commit | 6fa11bf21913b5ccb531acc3c2baec963f4d384a (patch) | |
tree | aaf6188a4579949cc1fbac61d0fee5234b97996a /docs | |
parent | 5c97a78ce6ab45643dcb420ba2ad20c30dcd5b8a (diff) | |
download | qmk_firmware-6fa11bf21913b5ccb531acc3c2baec963f4d384a.tar.gz qmk_firmware-6fa11bf21913b5ccb531acc3c2baec963f4d384a.zip |
Separate RGBLight/RGB Matrix keycode handling (#23679)
* 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
Diffstat (limited to 'docs')
-rw-r--r-- | docs/features/rgb_matrix.md | 50 | ||||
-rw-r--r-- | docs/features/rgblight.md | 6 | ||||
-rw-r--r-- | docs/keycodes.md | 36 |
3 files changed, 35 insertions, 57 deletions
diff --git a/docs/features/rgb_matrix.md b/docs/features/rgb_matrix.md index bc14bb6277..d87e5f6fdb 100644 --- a/docs/features/rgb_matrix.md +++ b/docs/features/rgb_matrix.md @@ -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 diff --git a/docs/features/rgblight.md b/docs/features/rgblight.md index 794398a0f9..2afc2eb7d0 100644 --- a/docs/features/rgblight.md +++ b/docs/features/rgblight.md @@ -87,11 +87,6 @@ Changing the **Value** sets the overall brightness.<br> These keycodes cannot be used with functions like `tap_code16()` as they are 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 and the [RGB Matrix](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. -::: - ## Configuration Your RGB lighting can be configured by placing these `#define`s in your `config.h`: @@ -104,7 +99,6 @@ Your RGB lighting can be configured by placing these `#define`s in your `config. |`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level | |`RGBLIGHT_SLEEP` |*Not defined* |If defined, the RGB lighting will be switched off when the host goes to sleep | |`RGBLIGHT_SPLIT` |*Not defined* |If defined, synchronization functionality for split keyboards is added | -|`RGBLIGHT_DISABLE_KEYCODES`|*Not defined* |If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature| |`RGBLIGHT_DEFAULT_MODE` |`RGBLIGHT_MODE_STATIC_LIGHT`|The default mode to use upon clearing the EEPROM | |`RGBLIGHT_DEFAULT_HUE` |`0` (red) |The default hue to use upon clearing the EEPROM | |`RGBLIGHT_DEFAULT_SAT` |`UINT8_MAX` (255) |The default saturation to use upon clearing the EEPROM | diff --git a/docs/keycodes.md b/docs/keycodes.md index 9107ca5eb8..1210390f54 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -728,23 +728,25 @@ See also: [RGB Lighting](features/rgblight) |`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode (deprecated) | |`RGB_MODE_TWINKLE` |`RGB_M_TW`|Twinkle animation mode (deprecated) | -## RGB Matrix Lighting {#rgb-matrix-lighting} - -See also: [RGB Matrix Lighting](features/rgb_matrix) - -|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 Matrix {#rgb-matrix} + +See also: [RGB Matrix](features/rgb_matrix) + +|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 | ## US ANSI Shifted Symbols {#us-ansi-shifted-symbols} |