diff options
author | Daniel Prilik <danielprilik@gmail.com> | 2019-04-29 17:48:41 -0400 |
---|---|---|
committer | Drashna Jaelre <drashna@live.com> | 2019-04-29 14:48:41 -0700 |
commit | 1d784f0f9575b70e35c9c8338b0ff80dc7316d7e (patch) | |
tree | f1617c0a36ccb3bf6c1b881b6f1b9caad2678e2e /docs | |
parent | e337bb82a3b418dfd6c60b8c615322c854e5995d (diff) | |
download | qmk_firmware-1d784f0f9575b70e35c9c8338b0ff80dc7316d7e.tar.gz |
RGB Matrix: Custom effects on a kb/user level (#5338)
* Revamped custom effects approach
See docs for example usage
* push-up RGB Matrix default mode
Override default effect using RGB_MATRIX_STARTUP_MODE.
Useful on boards without EEPROM support
(*cough* Massdrop ALT/CTRL *cough*)
* update docs
Diffstat (limited to 'docs')
-rw-r--r-- | docs/feature_rgb_matrix.md | 57 |
1 files changed, 50 insertions, 7 deletions
diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index f2168ab16..4ce9d15f0 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -177,7 +177,7 @@ enum rgb_matrix_effects { RGB_MATRIX_GRADIENT_UP_DOWN, // Static gradient top to bottom, speed controls how much gradient changes RGB_MATRIX_BREATHING, // Single hue brightness cycling animation RGB_MATRIX_CYCLE_ALL, // Full keyboard solid hue cycling through full gradient - RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right + RGB_MATRIX_CYCLE_LEFT_RIGHT, // Full gradient scrolling left to right RGB_MATRIX_CYCLE_UP_DOWN, // Full gradient scrolling top to bottom RGB_MATRIX_RAINBOW_MOVING_CHEVRON, // Full gradent Chevron shapped scrolling left to right RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard @@ -203,7 +203,7 @@ enum rgb_matrix_effects { RGB_MATRIX_EFFECT_MAX }; ``` - + You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`: @@ -236,17 +236,60 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con |`#define DISABLE_RGB_MATRIX_SOLID_MULTISPLASH` |Disables `RGB_MATRIX_SOLID_MULTISPLASH` | -## Custom layer effects +## Custom RGB Matrix Effects + +By setting `RGB_MATRIX_CUSTOM_USER` (and/or `RGB_MATRIX_CUSTOM_KB`) in `rule.mk`, new effects can be defined directly from userspace, without having to edit any QMK core files. + +To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this: -Custom layer effects can be done by defining this in your `<keyboard>.c`: +`rgb_matrix_user.inc` should go in the root of the keymap directory. +`rgb_matrix_kb.inc` should go in the root of the keyboard directory. ```C -void rgb_matrix_indicators_kb(void) { - rgb_matrix_set_color(index, red, green, blue); +// !!! DO NOT ADD #pragma once !!! // + +// Step 1. +// Declare custom effects using the RGB_MATRIX_EFFECT macro +// (note the lack of semicolon after the macro!) +RGB_MATRIX_EFFECT(my_cool_effect) +RGB_MATRIX_EFFECT(my_cool_effect2) + +// Step 2. +// Define effects inside the `RGB_MATRIX_CUSTOM_EFFECT_IMPLS` ifdef block +#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS + +// e.g: A simple effect, self-contained within a single method +static bool my_cool_effect(effect_params_t* params) { + RGB_MATRIX_USE_LIMITS(led_min, led_max); + for (uint8_t i = led_min; i < led_max; i++) { + rgb_matrix_set_color(i, 0xff, 0xff, 0x00); + } + return led_max < DRIVER_LED_TOTAL; +} + +// e.g: A more complex effect, relying on external methods and state, with +// dedicated init and run methods +static uint8_t some_global_state; +static void my_cool_effect2_complex_init(effect_params_t* params) { + some_global_state = 1; } +static bool my_cool_effect2_complex_run(effect_params_t* params) { + RGB_MATRIX_USE_LIMITS(led_min, led_max); + for (uint8_t i = led_min; i < led_max; i++) { + rgb_matrix_set_color(i, 0xff, some_global_state++, 0xff); + } + + return led_max < DRIVER_LED_TOTAL; +} +static bool my_cool_effect2(effect_params_t* params) { + if (params->init) my_cool_effect2_complex_init(params); + return my_cool_effect2_complex_run(params); +} + +#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS ``` -A similar function works in the keymap as `rgb_matrix_indicators_user`. +For inspiration and examples, check out the built-in effects under `quantum/rgb_matrix_animation/` ## Colors |