Update README.md

Author: danewhero

usermods/user_fx/README.md

@@ -242,6 +242,135 @@ The string format WLED uses is semicolon-separated sections, with commas used fo
 Let’s split this into logical sections (delimited by semicolons ;):
 **TODO**
 
+
+
+## Understanding 1D WLED Effects
+
+Next, we will look at a 1D WLED effect called `Sinelon`.  This one is an especially interesting example because it shows how a single effect function can be used to create several different selectable effects in the UI.
+we will break this effect down tep by step.
+(This effect was originally one of the FastLED example effects; more information on FastLED can be found [here](https://fastled.io/).)
+
+```cpp
+static uint16_t sinelon_base(bool dual, bool rainbow=false) {
+```
+* The first line of code defines `sinelon base` as static helper function.  This is how all effects are initially defined.
+* Notice that it has some optional flags; these parameters will allow us to easily define the effect in different ways in the UI.
+
+```cpp
+  if (SEGLEN <= 1) return mode_static();
+```
+* If segment length ≤ 1, there’s nothing to animate. Just show static mode.
+
+The line of code helps create the "Fade Out" Trail:
+```cpp
+  SEGMENT.fade_out(SEGMENT.intensity);
+```
+* Gradually dims all LEDs each frame using SEGMENT.intensity as fade amount.
+* Creates the trailing "comet" effect by leaving a fading path behind the moving dot.
+
+Next, the effect computes some position information for the actively changing pixel, and the rest of the pixels as well:
+```cpp
+  unsigned pos = beatsin16_t(SEGMENT.speed/10, 0, SEGLEN-1);
+  if (SEGENV.call == 0) SEGENV.aux0 = pos;
+```
+* Calculates a sine-based oscillation to move the dot smoothly back and forth.
+  * `beatsin16_t` is a variant of FastLED’s beatsin16 function, generating smooth oscillations
+  * SEGMENT.speed / 10: affects oscillation speed. Higher = faster.
+  * 0: minimum position.
+  * SEGLEN-1: maximum position.
+* On first call `(SEGENV.call == 0)`, stores initial position in `SEGENV.aux0`. (`SEGENV.aux0` is a temporary state variable to keep track of last position.)
+
+The next lines of code help determine the colors to be used:
+```cpp
+  uint32_t color1 = SEGMENT.color_from_palette(pos, true, false, 0);
+  uint32_t color2 = SEGCOLOR(2);
+```
+* `color1`: main moving dot color, chosen from palette using the current position as index.
+* `color2`: secondary color from user-configured color slot 2.
+
+The next part taked into account the optional argument for if a Rainbow colored palette is in use:
+```cpp
+  if (rainbow) {
+    color1 = SEGMENT.color_wheel((pos & 0x07) * 32);
+  }
+```
+* If `rainbow` is true, override color1 using a rainbow wheel, producing rainbow cycling colors.
+* `(pos & 0x07) * 32` ensures the color changes gradually with position.
+
+```cpp
+    SEGMENT.setPixelColor(pos, color1);
+```
+* Lights up the computed position with the selected color.
+
+The next line takes into account another one of the optional arguments for the effect to potentially handle dual mirrored dots which create the animation:
+```cpp
+  if (dual) {
+    if (!color2) color2 = SEGMENT.color_from_palette(pos, true, false, 0);
+    if (rainbow) color2 = color1; // share rainbow color
+    SEGMENT.setPixelColor(SEGLEN-1-pos, color2);
+  }
+```
+* If dual is true:
+  * Uses `color2` for mirrored dot on opposite side.
+  * If `color2` is not set (0), fallback to same palette color as `color1`.
+  * In `rainbow` mode, force both dots to share the rainbow color.
+  * Sets pixel at `SEGLEN-1-pos` to `color2`.
+
+This final part of the effect function will fill in the 'trailing' pixels to complete the animation:
+```cpp
+    if (SEGENV.aux0 < pos) {
+      for (unsigned i = SEGENV.aux0; i < pos ; i++) {
+        SEGMENT.setPixelColor(i, color1);
+        if (dual) SEGMENT.setPixelColor(SEGLEN-1-i, color2);
+      }
+    } else {
+      for (unsigned i = SEGENV.aux0; i > pos ; i--) {
+        SEGMENT.setPixelColor(i, color1);
+        if (dual) SEGMENT.setPixelColor(SEGLEN-1-i, color2);
+      }
+    }
+    SEGENV.aux0 = pos;
+  }
+```
+* The first line checks if current position has changed since last frame.  (Prevents holes if the dot moves quickly and "skips" pixels.)  If the position has changed, then it will implement the logic to update the rest of the pixels.
+* Fills in all pixels between previous position (SEGENV.aux0) and new position (pos) to ensure smooth continuous trail.
+  * Works in both directions: Forward (if new pos > old pos), and Backward (if new pos < old pos).
+* Updates `SEGENV.aux0` to current position at the end.
+
+Finally, we return the `FRAMETIME`, as with all effect functions:
+```cpp
+  return FRAMETIME;
+}
+```
+* Returns `FRAMETIME` constant to set effect update rate (usually ~16 ms).
+
+The last part of this effect has the Wrapper functions for different Sinelon modes.
+Notice that there are three different modes that we can define from the single effect definition by leveraging the arguments in the function:
+```cpp
+uint16_t mode_sinelon(void) {
+  return sinelon_base(false);
+}
+# Calls sinelon_base with dual = false and rainbow = false 
+
+uint16_t mode_sinelon_dual(void) {
+  return sinelon_base(true);
+}
+# Calls sinelon_base with dual = true and rainbow = false 
+
+uint16_t mode_sinelon_rainbow(void) {
+  return sinelon_base(false, true);
+}
+# Calls sinelon_base with dual = false and rainbow = true 
+```
+
+And then the last part defines the metadata strings for each effect to speicfy how it will be portrayed in the UI:
+```cpp
+static const char _data_FX_MODE_SINELON[] PROGMEM = "Sinelon@!,Trail;!,!,!;!";
+static const char _data_FX_MODE_SINELON_DUAL[] PROGMEM = "Sinelon Dual@!,Trail;!,!,!;!";
+static const char _data_FX_MODE_SINELON_RAINBOW[] PROGMEM = "Sinelon Rainbow@!,Trail;,,!;!";
+```
+
+
 ### The UserFxUsermod Class
 
 The `UserFxUsermod` class registers the `mode_diffusionfire` effect with WLED. This section starts right after the effect function and metadata string, and is responsible for making the effect usable in the WLED interface:
@@ -290,9 +419,6 @@ REGISTER_USERMOD(user_fx);
 * The last line is a macro that tells WLED: “This is a valid usermod — load it during startup.”
   * WLED adds it to the list of active usermods, calls `setup()` and `loop()`, and lets it interact with the system.
 
-## Understanding 1D WLED Effects
-
-**TODO**
 
 ## Combining Multiple Effects in this Usermod