Revamped custom effects approach

See docs for example usage
qmk · Apr 4, 2019 · ced4c96 · ced4c96
1 parent 852d125
commit ced4c96
Show file tree

Hide file tree

Showing 4 changed files with 95 additions and 8 deletions.
diff --git a/common_features.mk b/common_features.mk
@@ -164,6 +164,14 @@ ifeq ($(strip $(RGB_MATRIX_ENABLE)), IS31FL3733)
     SRC += i2c_master.c
 endif
 
+ifeq ($(strip $(RGB_MATRIX_CUSTOM_KB)), yes)
+    OPT_DEFS += -DRGB_MATRIX_CUSTOM_KB
+endif
+
+ifeq ($(strip $(RGB_MATRIX_CUSTOM_USER)), yes)
+    OPT_DEFS += -DRGB_MATRIX_CUSTOM_USER
+endif
+
 ifeq ($(strip $(TAP_DANCE_ENABLE)), yes)
     OPT_DEFS += -DTAP_DANCE_ENABLE
     SRC += $(QUANTUM_DIR)/process_keycode/process_tap_dance.c

diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
@@ -100,7 +100,7 @@ const is31_led g_is31_leds[DRIVER_LED_TOTAL] = {
 
 Where `X_Y` is the location of the LED in the matrix defined by [the datasheet](http://www.issi.com/WW/pdf/31FL3733.pdf) and the header file `drivers/issi/is31fl3733.h`. The `driver` is the index of the driver you defined in your `config.h` (Only `0` right now).
 
-From this point forward the configuration is the same for all the drivers. 
+From this point forward the configuration is the same for all the drivers.
 
 ```C
 const rgb_led g_rgb_leds[DRIVER_LED_TOTAL] = {
@@ -153,7 +153,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
@@ -173,7 +173,7 @@ enum rgb_matrix_effects {
     RGB_MATRIX_EFFECT_MAX
 };
 ```
-    
+
 You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `config.h`:
 
 
@@ -200,17 +200,57 @@ 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.
 
-Custom layer effects can be done by defining this in your `<keyboard>.c`:
+To declare new effects, create a new `rgb_matrix_user/kb.inc` that looks something like this:
 
 ```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/`
 
 ## Additional `config.h` Options
 

diff --git a/quantum/rgb_matrix.c b/quantum/rgb_matrix.c
@@ -45,6 +45,19 @@
 #include "rgb_matrix_animations/solid_splash_anim.h"
 #include "rgb_matrix_animations/breathing_anim.h"
 
+#if defined(RGB_MATRIX_CUSTOM_KB) || defined(RGB_MATRIX_CUSTOM_USER)
+  #define RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+    #define RGB_MATRIX_EFFECT(name, ...)
+    #ifdef RGB_MATRIX_CUSTOM_KB
+      #include "rgb_matrix_kb.inc"
+    #endif
+    #ifdef RGB_MATRIX_CUSTOM_USER
+      #include "rgb_matrix_user.inc"
+    #endif
+    #undef RGB_MATRIX_EFFECT
+  #undef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+#endif
+
 #ifndef RGB_DISABLE_AFTER_TIMEOUT
   #define RGB_DISABLE_AFTER_TIMEOUT 0
 #endif
@@ -402,6 +415,20 @@ static void rgb_task_render(uint8_t effect) {
 #endif // DISABLE_RGB_MATRIX_SOLID_MULTISPLASH
 #endif // RGB_MATRIX_KEYREACTIVE_ENABLED
 
+#if defined(RGB_MATRIX_CUSTOM_KB) || defined(RGB_MATRIX_CUSTOM_USER)
+  #define RGB_MATRIX_EFFECT(name, ...) \
+    case RGB_MATRIX_CUSTOM_##name: \
+      rendering = name(&rgb_effect_params); \
+      break;
+  #ifdef RGB_MATRIX_CUSTOM_KB
+    #include "rgb_matrix_kb.inc"
+  #endif
+  #ifdef RGB_MATRIX_CUSTOM_USER
+    #include "rgb_matrix_user.inc"
+  #endif
+  #undef RGB_MATRIX_EFFECT
+#endif
+
     // Factory default magic value
     case UINT8_MAX: {
         rgb_matrix_test();

diff --git a/quantum/rgb_matrix.h b/quantum/rgb_matrix.h
@@ -119,6 +119,18 @@ enum rgb_matrix_effects {
   RGB_MATRIX_SOLID_MULTISPLASH,
 #endif // DISABLE_RGB_MATRIX_SOLID_MULTISPLASH
 #endif // RGB_MATRIX_KEYREACTIVE_ENABLED
+
+#if defined(RGB_MATRIX_CUSTOM_KB) || defined(RGB_MATRIX_CUSTOM_USER)
+  #define RGB_MATRIX_EFFECT(name, ...) RGB_MATRIX_CUSTOM_##name,
+  #ifdef RGB_MATRIX_CUSTOM_KB
+    #include "rgb_matrix_kb.inc"
+  #endif
+  #ifdef RGB_MATRIX_CUSTOM_USER
+    #include "rgb_matrix_user.inc"
+  #endif
+  #undef RGB_MATRIX_EFFECT
+#endif
+
   RGB_MATRIX_EFFECT_MAX
 };