fl::Particles1d Class Reference

Detailed Description

Power-based particle system for 1D LED strips creating organic light effects.

Core Concept: Power-Based Lifecycle

Each particle has a power level that decreases linearly from 1.0 (birth) to 0.0 (death). Power affects three properties simultaneously:

• Velocity: velocity = base_velocity × power (particle slows as it ages)
• Saturation: saturation = base_sat + (1-power) × (255-base_sat) (color intensifies)
• Brightness: brightness = base_brightness × power (dims toward death)

Visual Journey: Fast bright desaturated → Medium colorful → Crawling saturated ember

Technical Features

Sub-Pixel Rendering: Floating-point positions render across adjacent LEDs for smooth motion

Overdraw Technique: Multiple update/draw cycles per frame (default: 20x) create smooth motion blur trails by repeatedly fading and redrawing particles

Cyclical Wrapping: Particles wrap seamlessly at strip boundaries, perfect for LED rings

Usage Example

fl::Particles1d particles(NUM_LEDS, 10, 2);  // 10 particles, fade rate 2
particles.setLifetime(5000);  // 5 second lifespan
particles.setSpeed(1.5f);     // 1.5x speed multiplier
 
void loop() {
    if (millis() - lastSpawn >= 2000) {
        particles.spawnRandomParticle();
        lastSpawn = millis();
    }
    particles.draw(fl::Fx::DrawContext(millis(), leds));
}

Performance (ESP32 @ 240MHz, 210 LEDs)

• Memory: ~60 bytes base + ~20 bytes per particle
• CPU: ~15ms per frame with 20x overdraw (suitable for 30+ FPS)

Note

Spawning is externally controlled for flexibility (triggers, music-reactive, etc.)

Definition at line 52 of file particles.h.

#include <particles.h>

Inheritance diagram for fl::Particles1d:

Collaboration diagram for fl::Particles1d:

Classes
struct	Particle
	Individual particle with power-based lifecycle. More...

Public Member Functions
	Particles1d (u16 num_leds, u8 max_particles=10, u8 fade_rate=2)
	~Particles1d () FL_NOEXCEPT
void	draw (DrawContext context) override
	Update and render all particles with overdraw technique.
fl::string	fxName () const override
void	setCyclical (bool cyclical)
	Set cyclical mode (true = wrap around, false = stop at edges)
void	setFadeRate (u8 fade_rate)
	Set fade rate for trails (0-255, higher = shorter trails)
void	setLifetime (u16 lifetime_ms)
	Set average particle lifetime in milliseconds.
void	setOverdrawCount (u8 count)
	Set overdraw count (higher = smoother trails, more CPU)
void	setSpeed (float speed)
	Set speed multiplier (1.0 = normal, >1.0 = faster, <1.0 = slower)
void	spawnRandomParticle ()
	Spawn a particle with random position, velocity, color, and lifetime.
Public Member Functions inherited from fl::Fx1d
	Fx1d (u16 numLeds)
void	setXmap (const XMap &xMap)
u16	xyMap (u16 x) const
Public Member Functions inherited from fl::Fx
	Fx (u16 numLeds)
u16	getNumLeds () const
virtual bool	hasFixedFrameRate (float *fps) const
virtual void	pause (fl::u32 now)
virtual void	resume (fl::u32 now)

Private Attributes
bool	mCyclical
	Wrap mode: true = wrap around, false = stop at edges.
u8	mFadeRate
	Fade amount per frame (0-255, higher = shorter trails)
u16	mLifetimeMs = 4000
	Average particle lifetime in milliseconds.
u8	mOverdrawCount
	Number of update/draw cycles per frame (higher = smoother trails, more CPU)
fl::vector< Particle >	mParticles
	Particle pool (oldest particle reused when full)
float	mSpeedMultiplier
	Global speed multiplier (1.0 = normal, >1.0 = faster, <1.0 = slower)

Additional Inherited Members
Public Types inherited from fl::Fx
using	DrawContext = ::fl::DrawContext
Protected Member Functions inherited from fl::Fx
virtual	~Fx () FL_NOEXCEPT
Protected Attributes inherited from fl::Fx1d
XMap	mXMap
Protected Attributes inherited from fl::Fx
u16	mNumLeds

---

The documentation for this class was generated from the following files:

• fl/fx/1d/particles.h
• fl/fx/1d/particles.cpp.hpp