Spirals, Pinwheels, and Documentation....Oh My! RGB Matrix Effects (#5877)

* Spirals, Pinwheels, and Documentation....Oh My!

* Spiral effect band thickness adjustments

* Fixing animation spin directions

9 files changed, 178 insertions, 0 deletions

diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md
index df124ea0f..18636776c 100644
--- a/docs/feature_rgb_matrix.md
+++ b/docs/feature_rgb_matrix.md
@@ -196,12 +196,18 @@ enum rgb_matrix_effects {
     RGB_MATRIX_BREATHING,           // Single hue brightness cycling animation
     RGB_MATRIX_BAND_SAT,        // Single hue band fading saturation scrolling left to right
     RGB_MATRIX_BAND_VAL,        // Single hue band fading brightness scrolling left to right
+    RGB_MATRIX_BAND_PINWHEEL_SAT,   // Single hue 3 blade spinning pinwheel fades saturation
+    RGB_MATRIX_BAND_PINWHEEL_VAL,   // Single hue 3 blade spinning pinwheel fades brightness
+    RGB_MATRIX_BAND_SPIRAL_SAT,     // Single hue spinning spiral fades saturation
+    RGB_MATRIX_BAND_SPIRAL_VAL,     // Single hue spinning spiral fades brightness
     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_UP_DOWN,       // Full gradient scrolling top to bottom
     RGB_MATRIX_CYCLE_OUT_IN,        // Full gradient scrolling out to in
     RGB_MATRIX_CYCLE_OUT_IN_DUAL,   // Full dual gradients scrolling out to in
     RGB_MATRIX_RAINBOW_MOVING_CHEVRON,  // Full gradent Chevron shapped scrolling left to right
+    RGB_MATRIX_CYCLE_PINWHEEL,      // Full gradient spinning pinwheel around center of keyboard
+    RGB_MATRIX_CYCLE_SPIRAL,        // Full gradient spinning spiral around center of keyboard
     RGB_MATRIX_DUAL_BEACON,         // Full gradient spinning around center of keyboard
     RGB_MATRIX_RAINBOW_BEACON,      // Full tighter gradient spinning around center of keyboard
     RGB_MATRIX_RAINBOW_PINWHEELS,   // Full dual gradients spinning two halfs of keyboard
@@ -239,6 +245,10 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
 |`#define DISABLE_RGB_MATRIX_BREATHING`                 |Disables `RGB_MATRIX_BREATHING`                |
 |`#define DISABLE_RGB_MATRIX_BAND_SAT`                  |Disables `RGB_MATRIX_BAND_SAT`                 |
 |`#define DISABLE_RGB_MATRIX_BAND_VAL`                  |Disables `RGB_MATRIX_BAND_VAL`                 |
+|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_SAT`         |Disables `RGB_MATRIX_BAND_PINWHEEL_SAT`        |
+|`#define DISABLE_RGB_MATRIX_BAND_PINWHEEL_VAL`         |Disables `RGB_MATRIX_BAND_PINWHEEL_VAL`        |
+|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_SAT`           |Disables `RGB_MATRIX_BAND_SPIRAL_SAT`          |
+|`#define DISABLE_RGB_MATRIX_BAND_SPIRAL_VAL`           |Disables `RGB_MATRIX_BAND_SPIRAL_VAL`          |
 |`#define DISABLE_RGB_MATRIX_CYCLE_ALL`                 |Disables `RGB_MATRIX_CYCLE_ALL`                |
 |`#define DISABLE_RGB_MATRIX_CYCLE_LEFT_RIGHT`          |Disables `RGB_MATRIX_CYCLE_LEFT_RIGHT`         |
 |`#define DISABLE_RGB_MATRIX_CYCLE_UP_DOWN`             |Disables `RGB_MATRIX_CYCLE_UP_DOWN`            |
@@ -246,6 +256,8 @@ You can disable a single effect by defining `DISABLE_[EFFECT_NAME]` in your `con
 |`#define DISABLE_RGB_MATRIX_CYCLE_OUT_IN_DUAL`         |Disables `RGB_MATRIX_CYCLE_OUT_IN_DUAL`        |
 |`#define DISABLE_RGB_MATRIX_RAINBOW_MOVING_CHEVRON`    |Disables `RGB_MATRIX_RAINBOW_MOVING_CHEVRON`   |
 |`#define DISABLE_RGB_MATRIX_DUAL_BEACON`               |Disables `RGB_MATRIX_DUAL_BEACON`              |
+|`#define DISABLE_RGB_MATRIX_CYCLE_PINWHEEL`            |Disables `RGB_MATRIX_CYCLE_PINWHEEL`           |
+|`#define DISABLE_RGB_MATRIX_CYCLE_SPIRAL`              |Disables `RGB_MATRIX_CYCLE_SPIRAL`             |
 |`#define DISABLE_RGB_MATRIX_RAINBOW_BEACON`            |Disables `RGB_MATRIX_RAINBOW_BEACON`           |
 |`#define DISABLE_RGB_MATRIX_RAINBOW_PINWHEELS`         |Disables `RGB_MATRIX_RAINBOW_PINWHEELS`        |
 |`#define DISABLE_RGB_MATRIX_RAINDROPS`                 |Disables `RGB_MATRIX_RAINDROPS`                |
diff --git a/lib/lib8tion/trig8.h b/lib/lib8tion/trig8.h
index 6ef3ce625..cfba6373f 100644
--- a/lib/lib8tion/trig8.h
+++ b/lib/lib8tion/trig8.h
@@ -255,5 +255,30 @@ LIB8STATIC uint8_t cos8( uint8_t theta)
     return sin8( theta + 64);
 }
 
+/// Fast 16-bit approximation of atan2(x).
+/// @returns atan2, value between 0 and 255
+LIB8STATIC uint8_t atan2_8(int16_t dy, int16_t dx)
+{
+    if (dy == 0)
+    {
+        if (dx >= 0)
+            return 0;
+        else
+            return 128;
+    }
+
+    int16_t abs_y = dy > 0 ? dy : -dy;
+    int8_t a;
+
+    if (dx >= 0)
+        a = 32 - (32 * (dx - abs_y) / (dx + abs_y));
+    else
+        a = 96 - (32 * (dx + abs_y) / (abs_y - dx));
+
+    if (dy < 0)
+        return -a;     // negate if in quad III or IV
+    return a;
+}
+
 ///@}
 #endif
diff --git a/quantum/rgb_matrix_animations/colorband_pinwheel_sat_anim.h b/quantum/rgb_matrix_animations/colorband_pinwheel_sat_anim.h
new file mode 100644
index 000000000..3e6df1fbe
--- /dev/null
+++ b/quantum/rgb_matrix_animations/colorband_pinwheel_sat_anim.h
@@ -0,0 +1,22 @@
+#ifndef DISABLE_RGB_MATRIX_BAND_PINWHEEL_SAT
+RGB_MATRIX_EFFECT(BAND_PINWHEEL_SAT)
+#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+
+bool BAND_PINWHEEL_SAT(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+
+  HSV hsv = { rgb_matrix_config.hue, 0, rgb_matrix_config.val };
+  uint8_t time = scale16by8(g_rgb_counters.tick, rgb_matrix_config.speed / 2);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    RGB_MATRIX_TEST_LED_FLAGS();
+    int16_t dx = g_led_config.point[i].x - 112;
+    int16_t dy = g_led_config.point[i].y - 32;
+    hsv.s = rgb_matrix_config.sat - time - atan2_8(dy, dx) * 3;
+    RGB rgb = hsv_to_rgb(hsv);
+    rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b);
+  }
+  return led_max < DRIVER_LED_TOTAL;
+}
+
+#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+#endif // DISABLE_RGB_MATRIX_BAND_PINWHEEL_SAT
diff --git a/quantum/rgb_matrix_animations/colorband_pinwheel_val_anim.h b/quantum/rgb_matrix_animations/colorband_pinwheel_val_anim.h
new file mode 100644
index 000000000..88cc7d1f2
--- /dev/null
+++ b/quantum/rgb_matrix_animations/colorband_pinwheel_val_anim.h
@@ -0,0 +1,22 @@
+#ifndef DISABLE_RGB_MATRIX_BAND_PINWHEEL_VAL
+RGB_MATRIX_EFFECT(BAND_PINWHEEL_VAL)
+#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+
+bool BAND_PINWHEEL_VAL(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+
+  HSV hsv = { rgb_matrix_config.hue, rgb_matrix_config.sat, 0 };
+  uint8_t time = scale16by8(g_rgb_counters.tick, rgb_matrix_config.speed / 2);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    RGB_MATRIX_TEST_LED_FLAGS();
+    int16_t dx = g_led_config.point[i].x - 112;
+    int16_t dy = g_led_config.point[i].y - 32;
+    hsv.v = rgb_matrix_config.val - time - atan2_8(dy, dx) * 3;
+    RGB rgb = hsv_to_rgb(hsv);
+    rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b);
+  }
+  return led_max < DRIVER_LED_TOTAL;
+}
+
+#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+#endif // DISABLE_RGB_MATRIX_BAND_PINWHEEL_VAL
diff --git a/quantum/rgb_matrix_animations/colorband_spiral_sat_anim.h b/quantum/rgb_matrix_animations/colorband_spiral_sat_anim.h
new file mode 100644
index 000000000..44955900a
--- /dev/null
+++ b/quantum/rgb_matrix_animations/colorband_spiral_sat_anim.h
@@ -0,0 +1,23 @@
+#ifndef DISABLE_RGB_MATRIX_BAND_SPIRAL_SAT
+RGB_MATRIX_EFFECT(BAND_SPIRAL_SAT)
+#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+
+bool BAND_SPIRAL_SAT(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+
+  HSV hsv = { rgb_matrix_config.hue, 0, rgb_matrix_config.val };
+  uint8_t time = scale16by8(g_rgb_counters.tick, rgb_matrix_config.speed / 2);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    RGB_MATRIX_TEST_LED_FLAGS();
+    int16_t dx = g_led_config.point[i].x - 112;
+    int16_t dy = g_led_config.point[i].y - 32;
+    uint8_t dist = sqrt16(dx * dx + dy * dy);
+    hsv.s = rgb_matrix_config.sat + dist - time - atan2_8(dy, dx);
+    RGB rgb = hsv_to_rgb(hsv);
+    rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b);
+  }
+  return led_max < DRIVER_LED_TOTAL;
+}
+
+#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+#endif // DISABLE_RGB_MATRIX_BAND_SPIRAL_SAT
diff --git a/quantum/rgb_matrix_animations/colorband_spiral_val_anim.h b/quantum/rgb_matrix_animations/colorband_spiral_val_anim.h
new file mode 100644
index 000000000..5aea0c8da
--- /dev/null
+++ b/quantum/rgb_matrix_animations/colorband_spiral_val_anim.h
@@ -0,0 +1,23 @@
+#ifndef DISABLE_RGB_MATRIX_BAND_SPIRAL_VAL
+RGB_MATRIX_EFFECT(BAND_SPIRAL_VAL)
+#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+
+bool BAND_SPIRAL_VAL(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+
+  HSV hsv = { rgb_matrix_config.hue, rgb_matrix_config.sat, 0 };
+  uint8_t time = scale16by8(g_rgb_counters.tick, rgb_matrix_config.speed / 2);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    RGB_MATRIX_TEST_LED_FLAGS();
+    int16_t dx = g_led_config.point[i].x - 112;
+    int16_t dy = g_led_config.point[i].y - 32;
+    uint8_t dist = sqrt16(dx * dx + dy * dy);
+    hsv.v = rgb_matrix_config.val + dist - time - atan2_8(dy, dx);
+    RGB rgb = hsv_to_rgb(hsv);
+    rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b);
+  }
+  return led_max < DRIVER_LED_TOTAL;
+}
+
+#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+#endif // DISABLE_RGB_MATRIX_BAND_SPIRAL_VAL
diff --git a/quantum/rgb_matrix_animations/cycle_pinwheel_anim.h b/quantum/rgb_matrix_animations/cycle_pinwheel_anim.h
new file mode 100644
index 000000000..59d60ac07
--- /dev/null
+++ b/quantum/rgb_matrix_animations/cycle_pinwheel_anim.h
@@ -0,0 +1,22 @@
+#ifndef DISABLE_RGB_MATRIX_CYCLE_PINWHEEL
+RGB_MATRIX_EFFECT(CYCLE_PINWHEEL)
+#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+
+bool CYCLE_PINWHEEL(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+
+  HSV hsv = { 0, rgb_matrix_config.sat, rgb_matrix_config.val };
+  uint8_t time = scale16by8(g_rgb_counters.tick, rgb_matrix_config.speed / 4);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    RGB_MATRIX_TEST_LED_FLAGS();
+    int16_t dx = g_led_config.point[i].x - 112;
+    int16_t dy = g_led_config.point[i].y - 32;
+    hsv.h = atan2_8(dy, dx) + time;
+    RGB rgb = hsv_to_rgb(hsv);
+    rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b);
+  }
+  return led_max < DRIVER_LED_TOTAL;
+}
+
+#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+#endif // DISABLE_RGB_MATRIX_CYCLE_PINWHEEL
diff --git a/quantum/rgb_matrix_animations/cycle_spiral_anim.h b/quantum/rgb_matrix_animations/cycle_spiral_anim.h
new file mode 100644
index 000000000..865309c25
--- /dev/null
+++ b/quantum/rgb_matrix_animations/cycle_spiral_anim.h
@@ -0,0 +1,23 @@
+#ifndef DISABLE_RGB_MATRIX_CYCLE_SPIRAL
+RGB_MATRIX_EFFECT(CYCLE_SPIRAL)
+#ifdef RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+
+bool CYCLE_SPIRAL(effect_params_t* params) {
+  RGB_MATRIX_USE_LIMITS(led_min, led_max);
+
+  HSV hsv = { 0, rgb_matrix_config.sat, rgb_matrix_config.val };
+  uint8_t time = scale16by8(g_rgb_counters.tick, rgb_matrix_config.speed / 2);
+  for (uint8_t i = led_min; i < led_max; i++) {
+    RGB_MATRIX_TEST_LED_FLAGS();
+    int16_t dx = g_led_config.point[i].x - 112;
+    int16_t dy = g_led_config.point[i].y - 32;
+    uint8_t dist = sqrt16(dx * dx + dy * dy);
+    hsv.h = dist - time - atan2_8(dy, dx);
+    RGB rgb = hsv_to_rgb(hsv);
+    rgb_matrix_set_color(i, rgb.r, rgb.g, rgb.b);
+  }
+  return led_max < DRIVER_LED_TOTAL;
+}
+
+#endif // RGB_MATRIX_CUSTOM_EFFECT_IMPLS
+#endif // DISABLE_RGB_MATRIX_CYCLE_SPIRAL
diff --git a/quantum/rgb_matrix_animations/rgb_matrix_effects.inc b/quantum/rgb_matrix_animations/rgb_matrix_effects.inc
index 4b01afaa3..01332ed0d 100644
--- a/quantum/rgb_matrix_animations/rgb_matrix_effects.inc
+++ b/quantum/rgb_matrix_animations/rgb_matrix_effects.inc
@@ -5,12 +5,18 @@
 #include "rgb_matrix_animations/breathing_anim.h"
 #include "rgb_matrix_animations/colorband_sat_anim.h"
 #include "rgb_matrix_animations/colorband_val_anim.h"
+#include "rgb_matrix_animations/colorband_pinwheel_sat_anim.h"
+#include "rgb_matrix_animations/colorband_pinwheel_val_anim.h"
+#include "rgb_matrix_animations/colorband_spiral_sat_anim.h"
+#include "rgb_matrix_animations/colorband_spiral_val_anim.h"
 #include "rgb_matrix_animations/cycle_all_anim.h"
 #include "rgb_matrix_animations/cycle_left_right_anim.h"
 #include "rgb_matrix_animations/cycle_up_down_anim.h"
 #include "rgb_matrix_animations/rainbow_moving_chevron_anim.h"
 #include "rgb_matrix_animations/cycle_out_in_anim.h"
 #include "rgb_matrix_animations/cycle_out_in_dual_anim.h"
+#include "rgb_matrix_animations/cycle_pinwheel_anim.h"
+#include "rgb_matrix_animations/cycle_spiral_anim.h"
 #include "rgb_matrix_animations/dual_beacon_anim.h"
 #include "rgb_matrix_animations/rainbow_beacon_anim.h"
 #include "rgb_matrix_animations/rainbow_pinwheels_anim.h"