Add `{rgb|led}_matrix_get_mode_name()`. (#25344)

docs/features/led_matrix.md

@@ -214,9 +214,30 @@ led_matrix_mode(LED_MATRIX_CUSTOM_my_cool_effect);
 For inspiration and examples, check out the built-in effects under `quantum/led_matrix/animations/`.
 
 
+## Naming
+
+If you wish to be able to use the name of an effect in your code -- say for a display indicator -- then you can enable the function `led_matrix_get_mode_name` in the following manner:
+
+In your keymap's `config.h`:
+```c
+#define LED_MATRIX_MODE_NAME_ENABLE
+```
+
+In your `keymap.c`
+```c
+const char* effect_name = led_matrix_get_mode_name(led_matrix_get_mode());
+// do something with `effect_name`, like `oled_write_ln(effect_name, false);`
+```
+
+::: info
+`led_matrix_get_mode_name()` is not enabled by default as it increases the amount of flash memory used by the firmware based on the number of effects enabled.
+:::
+
+
 ## Additional `config.h` Options {#additional-configh-options}
 
 ```c
+#define LED_MATRIX_MODE_NAME_ENABLE // enables led_matrix_get_mode_name()
 #define LED_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses)
 #define LED_MATRIX_TIMEOUT 0 // number of milliseconds to wait until led automatically turns off
 #define LED_MATRIX_SLEEP // turn off effects when suspended

docs/features/rgb_matrix.md

@@ -365,9 +365,30 @@ These are shorthands to popular colors. The `RGB` ones can be passed to the `set
 These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list!
 
 
+## Naming
+
+If you wish to be able to use the name of an effect in your code -- say for a display indicator -- then you can enable the function `rgb_matrix_get_mode_name` in the following manner:
+
+In your keymap's `config.h`:
+```c
+#define RGB_MATRIX_MODE_NAME_ENABLE
+```
+
+In your `keymap.c`
+```c
+const char* effect_name = rgb_matrix_get_mode_name(rgb_matrix_get_mode());
+// do something with `effect_name`, like `oled_write_ln(effect_name, false);`
+```
+
+::: info
+`rgb_matrix_get_mode_name()` is not enabled by default as it increases the amount of flash memory used by the firmware based on the number of effects enabled.
+:::
+
+
 ## Additional `config.h` Options {#additional-configh-options}
 
 ```c
+#define RGB_MATRIX_MODE_NAME_ENABLE // enables rgb_matrix_get_mode_name()
 #define RGB_MATRIX_KEYRELEASES // reactive effects respond to keyreleases (instead of keypresses)
 #define RGB_MATRIX_TIMEOUT 0 // number of milliseconds to wait until rgb automatically turns off
 #define RGB_MATRIX_SLEEP // turn off effects when suspended

keyboards/1upkeyboards/pi50/config.h

@@ -8,3 +8,4 @@
 #define I2C_DRIVER I2CD1
 #define OLED_BRIGHTNESS 128
 #define OLED_FONT_H "keyboards/1upkeyboards/pi50/lib/glcdfont.c"
+#define RGB_MATRIX_MODE_NAME_ENABLE

keyboards/1upkeyboards/pi50/pi50.c

@@ -18,49 +18,6 @@
 #include <ctype.h>
 #include <stdio.h>
 
-#if defined(RGB_MATRIX_EFFECT)
-#    undef RGB_MATRIX_EFFECT
-#endif // defined(RGB_MATRIX_EFFECT)
-
-#define RGB_MATRIX_EFFECT(x) RGB_MATRIX_EFFECT_##x,
-enum {
-    RGB_MATRIX_EFFECT_NONE,
-#include "rgb_matrix_effects.inc"
-#undef RGB_MATRIX_EFFECT
-#ifdef RGB_MATRIX_CUSTOM_KB
-#    include "rgb_matrix_kb.inc"
-#endif
-#ifdef RGB_MATRIX_CUSTOM_USER
-#    include "rgb_matrix_user.inc"
-#endif
-#if defined(COMMUNITY_MODULES_ENABLE) && __has_include("rgb_matrix_community_modules.inc")
-#    include "rgb_matrix_community_modules.inc"
-#endif
-};
-
-#define RGB_MATRIX_EFFECT(x)    \
-    case RGB_MATRIX_EFFECT_##x: \
-        return #x;
-const char* rgb_matrix_name(uint8_t effect) {
-    switch (effect) {
-        case RGB_MATRIX_EFFECT_NONE:
-            return "NONE";
-#include "rgb_matrix_effects.inc"
-#undef RGB_MATRIX_EFFECT
-#ifdef RGB_MATRIX_CUSTOM_KB
-#    include "rgb_matrix_kb.inc"
-#endif
-#ifdef RGB_MATRIX_CUSTOM_USER
-#    include "rgb_matrix_user.inc"
-#endif
-#if defined(COMMUNITY_MODULES_ENABLE) && __has_include("rgb_matrix_community_modules.inc")
-#    include "rgb_matrix_community_modules.inc"
-#endif
-        default:
-            return "UNKNOWN";
-    }
-}
-
 #ifdef OLED_ENABLE
 
 static uint32_t oled_logo_timer = 0;
@@ -154,7 +111,7 @@ void user_oled_magic(void) {
     oled_write_P(led_state.num_lock ? PSTR("Num(x) ") : PSTR("Num( ) "), false);
     oled_write_P(led_state.scroll_lock ? PSTR("Scrl(x)") : PSTR("Scrl( )"), false);
 
-    char *mode_name = strdup(rgb_matrix_name(rgb_matrix_get_mode()));
+    char *mode_name = strdup(rgb_matrix_get_mode_name(rgb_matrix_get_mode()));
     if (mode_name != NULL) {
         int len = strlen(mode_name);
         bool capitalize_next = true;

keyboards/tzarc/djinn/config.h

@@ -50,3 +50,5 @@
 #ifndef STARTUP_SONG
 #    define STARTUP_SONG SONG(STARTUP_SOUND)
 #endif // STARTUP_SONG
+
+#define RGB_MATRIX_MODE_NAME_ENABLE

keyboards/tzarc/djinn/graphics/theme_djinn_default.c

@@ -30,55 +30,6 @@ static painter_image_handle_t lock_scrl_on;
 static painter_image_handle_t lock_scrl_off;
 static painter_font_handle_t  thintel;
 
-//----------------------------------------------------------
-// RGB Matrix naming
-#if defined(RGB_MATRIX_ENABLE)
-#    include <rgb_matrix.h>
-
-#    if defined(RGB_MATRIX_EFFECT)
-#        undef RGB_MATRIX_EFFECT
-#    endif // defined(RGB_MATRIX_EFFECT)
-
-#    define RGB_MATRIX_EFFECT(x) RGB_MATRIX_EFFECT_##x,
-enum {
-    RGB_MATRIX_EFFECT_NONE,
-#    include "rgb_matrix_effects.inc"
-#    ifdef RGB_MATRIX_CUSTOM_KB
-#        include "rgb_matrix_kb.inc"
-#    endif
-#    ifdef RGB_MATRIX_CUSTOM_USER
-#        include "rgb_matrix_user.inc"
-#    endif
-#    if defined(COMMUNITY_MODULES_ENABLE) && __has_include("rgb_matrix_community_modules.inc")
-#        include "rgb_matrix_community_modules.inc"
-#    endif
-#    undef RGB_MATRIX_EFFECT
-};
-
-#    define RGB_MATRIX_EFFECT(x)    \
-        case RGB_MATRIX_EFFECT_##x: \
-            return #x;
-const char *rgb_matrix_name(uint8_t effect) {
-    switch (effect) {
-        case RGB_MATRIX_EFFECT_NONE:
-            return "NONE";
-#    include "rgb_matrix_effects.inc"
-#    ifdef RGB_MATRIX_CUSTOM_KB
-#        include "rgb_matrix_kb.inc"
-#    endif
-#    ifdef RGB_MATRIX_CUSTOM_USER
-#        include "rgb_matrix_user.inc"
-#    endif
-#    if defined(COMMUNITY_MODULES_ENABLE) && __has_include("rgb_matrix_community_modules.inc")
-#        include "rgb_matrix_community_modules.inc"
-#    endif
-#    undef RGB_MATRIX_EFFECT
-        default:
-            return "UNKNOWN";
-    }
-}
-#endif // defined(RGB_MATRIX_ENABLE)
-
 //----------------------------------------------------------
 // UI Initialisation
 void keyboard_post_init_display(void) {
@@ -163,7 +114,7 @@ void draw_ui_user(bool force_redraw) {
         if (hue_redraw || rgb_effect_redraw) {
             static int max_rgb_xpos = 0;
             xpos                    = 16;
-            snprintf(buf, sizeof(buf), "rgb: %s", rgb_matrix_name(curr_effect));
+            snprintf(buf, sizeof(buf), "rgb: %s", rgb_matrix_get_mode_name(curr_effect));
 
             for (int i = 5; i < sizeof(buf); ++i) {
                 if (buf[i] == 0)

quantum/led_matrix/led_matrix.c

@@ -107,7 +107,11 @@ void eeconfig_update_led_matrix_default(void) {
 void eeconfig_debug_led_matrix(void) {
     dprintf("led_matrix_eeconfig EEPROM\n");
     dprintf("led_matrix_eeconfig.enable = %d\n", led_matrix_eeconfig.enable);
+#ifdef LED_MATRIX_MODE_NAME_ENABLE
+    dprintf("led_matrix_eeconfig.mode = %d (%s)\n", led_matrix_eeconfig.mode, led_matrix_get_mode_name(led_matrix_eeconfig.mode));
+#else
     dprintf("led_matrix_eeconfig.mode = %d\n", led_matrix_eeconfig.mode);
+#endif // LED_MATRIX_MODE_NAME_ENABLE
     dprintf("led_matrix_eeconfig.val = %d\n", led_matrix_eeconfig.val);
     dprintf("led_matrix_eeconfig.speed = %d\n", led_matrix_eeconfig.speed);
     dprintf("led_matrix_eeconfig.flags = %d\n", led_matrix_eeconfig.flags);
@@ -525,7 +529,11 @@ void led_matrix_mode_eeprom_helper(uint8_t mode, bool write_to_eeprom) {
     }
     led_task_state = STARTING;
     eeconfig_flag_led_matrix(write_to_eeprom);
-    dprintf("led matrix mode [%s]: %u\n", (write_to_eeprom) ? "EEPROM" : "NOEEPROM", led_matrix_eeconfig.mode);
+#ifdef LED_MATRIX_MODE_NAME_ENABLE
+    dprintf("led matrix mode [%s]: %u (%s)\n", (write_to_eeprom) ? "EEPROM" : "NOEEPROM", (unsigned)led_matrix_eeconfig.mode, led_matrix_get_mode_name(led_matrix_eeconfig.mode));
+#else
+    dprintf("led matrix mode [%s]: %u\n", (write_to_eeprom) ? "EEPROM" : "NOEEPROM", (unsigned)led_matrix_eeconfig.mode);
+#endif // LED_MATRIX_MODE_NAME_ENABLE
 }
 void led_matrix_mode_noeeprom(uint8_t mode) {
     led_matrix_mode_eeprom_helper(mode, false);
@@ -652,3 +660,48 @@ void led_matrix_set_flags(led_flags_t flags) {
 void led_matrix_set_flags_noeeprom(led_flags_t flags) {
     led_matrix_set_flags_eeprom_helper(flags, false);
 }
+
+// LED Matrix naming
+#undef LED_MATRIX_EFFECT
+#ifdef LED_MATRIX_MODE_NAME_ENABLE
+const char *led_matrix_get_mode_name(uint8_t mode) {
+    switch (mode) {
+        case LED_MATRIX_NONE:
+            return "NONE";
+
+#    define LED_MATRIX_EFFECT(name, ...) \
+        case LED_MATRIX_##name:          \
+            return #name;
+#    include "led_matrix_effects.inc"
+#    undef LED_MATRIX_EFFECT
+
+#    ifdef COMMUNITY_MODULES_ENABLE
+#        define LED_MATRIX_EFFECT(name, ...)         \
+            case LED_MATRIX_COMMUNITY_MODULE_##name: \
+                return #name;
+#        include "led_matrix_community_modules.inc"
+#        undef LED_MATRIX_EFFECT
+#    endif // COMMUNITY_MODULES_ENABLE
+
+#    if defined(LED_MATRIX_CUSTOM_KB) || defined(LED_MATRIX_CUSTOM_USER)
+#        define LED_MATRIX_EFFECT(name, ...) \
+            case LED_MATRIX_CUSTOM_##name:   \
+                return #name;
+
+#        ifdef LED_MATRIX_CUSTOM_KB
+#            include "led_matrix_kb.inc"
+#        endif // LED_MATRIX_CUSTOM_KB
+
+#        ifdef LED_MATRIX_CUSTOM_USER
+#            include "led_matrix_user.inc"
+#        endif // LED_MATRIX_CUSTOM_USER
+
+#        undef LED_MATRIX_EFFECT
+#    endif // LED_MATRIX_CUSTOM_KB || LED_MATRIX_CUSTOM_USER
+
+        default:
+            return "UNKNOWN";
+    }
+}
+#    undef LED_MATRIX_EFFECT
+#endif // LED_MATRIX_MODE_NAME_ENABLE

quantum/led_matrix/led_matrix.h

@@ -184,6 +184,10 @@ led_flags_t led_matrix_get_flags(void);
 void        led_matrix_set_flags(led_flags_t flags);
 void        led_matrix_set_flags_noeeprom(led_flags_t flags);
 
+#ifdef LED_MATRIX_MODE_NAME_ENABLE
+const char *led_matrix_get_mode_name(uint8_t mode);
+#endif // LED_MATRIX_MODE_NAME_ENABLE
+
 static inline bool led_matrix_check_finished_leds(uint8_t led_idx) {
 #if defined(LED_MATRIX_SPLIT)
     if (is_keyboard_left()) {

quantum/rgb_matrix/rgb_matrix.c

@@ -109,7 +109,11 @@ void eeconfig_update_rgb_matrix_default(void) {
 void eeconfig_debug_rgb_matrix(void) {
     dprintf("rgb_matrix_config EEPROM\n");
     dprintf("rgb_matrix_config.enable = %d\n", rgb_matrix_config.enable);
+#ifdef RGB_MATRIX_MODE_NAME_ENABLE
+    dprintf("rgb_matrix_config.mode = %d (%s)\n", rgb_matrix_config.mode, rgb_matrix_get_mode_name(rgb_matrix_config.mode));
+#else
     dprintf("rgb_matrix_config.mode = %d\n", rgb_matrix_config.mode);
+#endif // RGB_MATRIX_MODE_NAME_ENABLE
     dprintf("rgb_matrix_config.hsv.h = %d\n", rgb_matrix_config.hsv.h);
     dprintf("rgb_matrix_config.hsv.s = %d\n", rgb_matrix_config.hsv.s);
     dprintf("rgb_matrix_config.hsv.v = %d\n", rgb_matrix_config.hsv.v);
@@ -560,7 +564,11 @@ void rgb_matrix_mode_eeprom_helper(uint8_t mode, bool write_to_eeprom) {
     }
     rgb_task_state = STARTING;
     eeconfig_flag_rgb_matrix(write_to_eeprom);
-    dprintf("rgb matrix mode [%s]: %u\n", (write_to_eeprom) ? "EEPROM" : "NOEEPROM", rgb_matrix_config.mode);
+#ifdef RGB_MATRIX_MODE_NAME_ENABLE
+    dprintf("rgb matrix mode [%s]: %u (%s)\n", (write_to_eeprom) ? "EEPROM" : "NOEEPROM", (unsigned)rgb_matrix_config.mode, rgb_matrix_get_mode_name(rgb_matrix_config.mode));
+#else
+    dprintf("rgb matrix mode [%s]: %u\n", (write_to_eeprom) ? "EEPROM" : "NOEEPROM", (unsigned)rgb_matrix_config.mode);
+#endif // RGB_MATRIX_MODE_NAME_ENABLE
 }
 void rgb_matrix_mode_noeeprom(uint8_t mode) {
     rgb_matrix_mode_eeprom_helper(mode, false);
@@ -738,3 +746,49 @@ void rgb_matrix_set_flags(led_flags_t flags) {
 void rgb_matrix_set_flags_noeeprom(led_flags_t flags) {
     rgb_matrix_set_flags_eeprom_helper(flags, false);
 }
+
+//----------------------------------------------------------
+// RGB Matrix naming
+#undef RGB_MATRIX_EFFECT
+#ifdef RGB_MATRIX_MODE_NAME_ENABLE
+const char *rgb_matrix_get_mode_name(uint8_t mode) {
+    switch (mode) {
+        case RGB_MATRIX_NONE:
+            return "NONE";
+
+#    define RGB_MATRIX_EFFECT(name, ...) \
+        case RGB_MATRIX_##name:          \
+            return #name;
+#    include "rgb_matrix_effects.inc"
+#    undef RGB_MATRIX_EFFECT
+
+#    ifdef COMMUNITY_MODULES_ENABLE
+#        define RGB_MATRIX_EFFECT(name, ...)         \
+            case RGB_MATRIX_COMMUNITY_MODULE_##name: \
+                return #name;
+#        include "rgb_matrix_community_modules.inc"
+#        undef RGB_MATRIX_EFFECT
+#    endif // COMMUNITY_MODULES_ENABLE
+
+#    if defined(RGB_MATRIX_CUSTOM_KB) || defined(RGB_MATRIX_CUSTOM_USER)
+#        define RGB_MATRIX_EFFECT(name, ...) \
+            case RGB_MATRIX_CUSTOM_##name:   \
+                return #name;
+
+#        ifdef RGB_MATRIX_CUSTOM_KB
+#            include "rgb_matrix_kb.inc"
+#        endif // RGB_MATRIX_CUSTOM_KB
+
+#        ifdef RGB_MATRIX_CUSTOM_USER
+#            include "rgb_matrix_user.inc"
+#        endif // RGB_MATRIX_CUSTOM_USER
+
+#        undef RGB_MATRIX_EFFECT
+#    endif // RGB_MATRIX_CUSTOM_KB || RGB_MATRIX_CUSTOM_USER
+
+        default:
+            return "UNKNOWN";
+    }
+}
+#    undef RGB_MATRIX_EFFECT
+#endif // RGB_MATRIX_MODE_NAME_ENABLE

quantum/rgb_matrix/rgb_matrix.h

@@ -220,6 +220,10 @@ void        rgb_matrix_set_flags(led_flags_t flags);
 void        rgb_matrix_set_flags_noeeprom(led_flags_t flags);
 void        rgb_matrix_update_pwm_buffers(void);
 
+#ifdef RGB_MATRIX_MODE_NAME_ENABLE
+const char *rgb_matrix_get_mode_name(uint8_t mode);
+#endif // RGB_MATRIX_MODE_NAME_ENABLE
+
 #ifndef RGBLIGHT_ENABLE
 #    define eeconfig_update_rgblight_current eeconfig_force_flush_rgb_matrix
 #    define rgblight_reload_from_eeprom rgb_matrix_reload_from_eeprom