FastLED FX Library (src/fx)

The FX library adds optional, higher‑level visual effects and a small runtime around FastLED. It includes ready‑to‑use animations for strips (1D) and matrices (2D), utilities to layer/up‑scale/blend effects, and a simple video playback pipeline.

If you’re new to FastLED and C++: an effect is an object that you construct once and call draw(...) on every frame, passing time and your LED buffer. Start with the 1D/2D examples, then explore composition and video as needed.

What’s included

• 1d/: Strip effects like Cylon, DemoReel100, Fire2012, NoiseWave, Pacifica, Pride2015, and TwinkleFox.
• 2d/: Matrix effects including NoisePalette, WaveFx, ScaleUp, Blend2d (compositing effects), and Animartrix integrations.
• video/: Read frames from files/streams, buffer, and interpolate for smooth playback on your LEDs.
• detail/: Internal helpers for draw context, layering, transitions, and compositing.

Core concepts and types

• Base classes:
  • fl::Fx: abstract base with a single method to implement: void draw(DrawContext ctx).
  • fl::Fx1d: base for strip effects; holds LED count and (optionally) an XMap.
  • fl::Fx2d: base for matrix effects; holds an XYMap to convert (x,y) to LED indices.
• DrawContext: Fx::DrawContext carries per‑frame data: now (ms), CRGB* leds, optional frame_time, and a speed hint.
• Palettes and helpers: Many effects use FastLED’s CRGB, CHSV, CRGBPalette16, and timing helpers like beatsin*.

Basic usage (1D example)

#include "fx/1d/cylon.h"

fl::Cylon fx(num_leds);
...
fx.draw(fl::Fx::DrawContext(millis(), leds));

Basic usage (2D example)

#include "fx/2d/noisepalette.h"

fl::XYMap xy(width, height, /* your mapper */);
fl::NoisePalette fx(xy);
...
fx.draw(fl::Fx::DrawContext(millis(), leds));

Composition and transitions

• Use Blend2d to stack multiple 2D effects and blur/blend them.
• The detail/ components (FxLayer, FxCompositor, Transition) support cross‑fading between effects over time.

Video playback

• The video/ pipeline reads frames from a FileHandle or ByteStream, keeps a small buffer, and interpolates between frames to match your output rate.

Performance and targets

• FX components may use more memory/CPU than the FastLED core. They are designed for more capable MCUs (e.g., ESP32/Teensy/RP2040), but many examples will still run on modest hardware at smaller sizes.

Licensing

• Most code follows the standard FastLED license. Animartrix is free for non‑commercial use and paid otherwise. See src/fx/readme and headers for details.

Explore each subfolder’s README to find the effect you want, then copy the corresponding header into your project and call draw(...) every frame.

Examples (from examples/Fx*)

• 1D strip effects:
  • Cylon: examples/FxCylon/FxCylon.ino
  • DemoReel100: examples/FxDemoReel100/FxDemoReel100.ino
  • Fire2012: examples/FxFire2012/FxFire2012.ino
  • Pacifica: examples/FxPacifica/FxPacifica.ino
  • Pride2015: examples/FxPride2015/FxPride2015.ino
  • TwinkleFox: examples/FxTwinkleFox/FxTwinkleFox.ino
• 2D matrix effects:
  • NoisePalette: examples/FxNoisePlusPalette/FxNoisePlusPalette.ino
  • WaveFx layered: examples/FxWave2d/
• Video pipeline:
  • Memory stream: examples/FxGfx2Video/FxGfx2Video.ino
  • SD card playback: examples/FxSdCard/FxSdCard.ino

Minimal 1D call pattern:

fx.draw(fl::Fx::DrawContext(millis(), leds));
FastLED.show();

Minimal 2D call pattern (requires XYMap):

fl::NoisePalette fx(xyMap);
fx.draw(fl::Fx::DrawContext(millis(), leds));
FastLED.show();