flowfield.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/stdint.h"
 
#include "crgb.h"
#include "fl/math/filter/filter.h"
#include "fl/math/math.h"
#include "fl/stl/shared_ptr.h"
#include "fl/fx/fx2d.h"
#include "fl/fx/time.h"
#include "fl/math/xymap.h"
#include "fl/stl/align.h"
#include "fl/stl/vector.h"
#include "fl/math/fixed_point/s16x16.h"
#include "fl/stl/noexcept.h"
 
namespace fl {

enum class BumpShape : u8 {
    HalfSine, 
    Gaussian   
};

class NoiseBias1D {
  public:
    NoiseBias1D(u16 size, float attackTau, float decayTau)
        FL_NO_EXCEPT : mSize(size) {
        mFilters.reserve(size);
        for (u16 i = 0; i < size; ++i) {
            mFilters.push_back(
                AttackDecayFilter<float>(attackTau, decayTau, 0.0f));
        }
        mPending.resize(size);
        for (u16 i = 0; i < size; ++i) {
            mPending[i] = 0.0f;
        }
    }

    void trigger(float center, float width, float amplitude,
                 BumpShape shape = BumpShape::HalfSine) FL_NO_EXCEPT {
        if (width <= 0.0f || amplitude == 0.0f || mSize == 0) {
            return;
        }
        const float halfWidth = width * 0.5f;
        int iStart = fl::max(0, static_cast<int>(fl::floorf(center - halfWidth)));
        int iEnd = fl::min(static_cast<int>(mSize) - 1,
                           static_cast<int>(fl::ceilf(center + halfWidth)));
        for (int i = iStart; i <= iEnd; ++i) {
            float t = (static_cast<float>(i) - (center - halfWidth)) / width;
            t = fl::clamp(t, 0.0f, 1.0f);
            float shaped = 0.0f;
            switch (shape) {
            case BumpShape::HalfSine:
                shaped = fl::sinf(static_cast<float>(FL_PI) * t);
                break;
            case BumpShape::Gaussian: {
                float u = (t - 0.5f) / 0.2f;
                shaped = fl::expf(-0.5f * u * u);
                break;
            }
            }
            mPending[i] += amplitude * shaped;
        }
    }

    void update(float dtSeconds) FL_NO_EXCEPT {
        for (u16 i = 0; i < mSize; ++i) {
            mFilters[i].update(mPending[i], dtSeconds);
            mPending[i] = 0.0f;
        }
    }
 
    float get(u16 i) const FL_NO_EXCEPT { return mFilters[i].value(); }
    u16 size() const FL_NO_EXCEPT { return mSize; }
 
    void reset() FL_NO_EXCEPT {
        for (u16 i = 0; i < mSize; ++i) {
            mFilters[i].reset(0.0f);
            mPending[i] = 0.0f;
        }
    }
 
  private:
    fl::vector<AttackDecayFilter<float>> mFilters;
    fl::vector<float> mPending;
    u16 mSize;
};

class NoiseBias2D {
  public:
    NoiseBias2D(u16 width, u16 height, float attackTau, float decayTau)
        FL_NO_EXCEPT : mXBias(width, attackTau, decayTau),
          mYBias(height, attackTau, decayTau) {}
 
    void triggerX(float center, float width, float amplitude,
                  BumpShape shape = BumpShape::HalfSine) FL_NO_EXCEPT {
        mXBias.trigger(center, width, amplitude, shape);
    }
 
    void triggerY(float center, float width, float amplitude,
                  BumpShape shape = BumpShape::HalfSine) FL_NO_EXCEPT {
        mYBias.trigger(center, width, amplitude, shape);
    }
 
    void update(float dtSeconds) FL_NO_EXCEPT {
        mXBias.update(dtSeconds);
        mYBias.update(dtSeconds);
    }
 
    float getX(u16 x) const FL_NO_EXCEPT { return mXBias.get(x); }
    float getY(u16 y) const FL_NO_EXCEPT { return mYBias.get(y); }
    float get(u16 x, u16 y) const FL_NO_EXCEPT { return mXBias.get(x) + mYBias.get(y); }
 
    NoiseBias1D &x() FL_NO_EXCEPT { return mXBias; }
    const NoiseBias1D &x() const FL_NO_EXCEPT { return mXBias; }
    NoiseBias1D &y() FL_NO_EXCEPT { return mYBias; }
    const NoiseBias1D &y() const FL_NO_EXCEPT { return mYBias; }
 
    u16 width() const FL_NO_EXCEPT { return mXBias.size(); }
    u16 height() const FL_NO_EXCEPT { return mYBias.size(); }
 
    void reset() FL_NO_EXCEPT {
        mXBias.reset();
        mYBias.reset();
    }
 
  private:
    NoiseBias1D mXBias;
    NoiseBias1D mYBias;
};

struct FlowFieldFPState {
    // Color grids — raw s16x16 values
    fl::vector<fl::i32> r, g, b;        // Main RGB grid
    fl::vector<fl::i32> tr, tg, tb;     // Temp grid for advection pass 1
 
    // Flow profiles — raw s16x16 values in [-1.0, 1.0] range
    fl::vector<fl::i32> x_prof;          // Per-column vertical shift driver
    fl::vector<fl::i32> y_prof;          // Per-row horizontal shift driver
 
    // Perlin fade LUT (257 entries, Q8.24 format)
    FL_ALIGNAS(16) fl::i32 fade_lut[257] = {};
    bool fade_lut_initialized = false;
 
    int count = 0;   // W*H pixel count (padded to multiple of 4)
    int width = 0;
    int height = 0;
 
    FlowFieldFPState() FL_NO_EXCEPT {}
 
    void init(int w, int h) FL_NO_EXCEPT {
        width = w;
        height = h;
        count = (w * h + 3) & ~3;  // Pad to multiple of 4
 
        r.resize(count, 0);
        g.resize(count, 0);
        b.resize(count, 0);
        tr.resize(count, 0);
        tg.resize(count, 0);
        tb.resize(count, 0);
        x_prof.resize(w, 0);
        y_prof.resize(h, 0);
    }
};
 
FASTLED_SHARED_PTR(FlowField);
FASTLED_SHARED_PTR(FlowFieldFloat);
FASTLED_SHARED_PTR(FlowFieldFP);

struct FlowFieldParams {
    float persistence = 0.86f;       
    float color_shift = 0.04f;       
    float flow_amp_x = 1.0f;        
    float flow_amp_y = 1.0f;        
    float flow_shift = 1.8f;        
    float flow_speed_x = 0.10f;     
    float flow_speed_y = 0.10f;     
    float noise_freq_x = 0.33f;     
    float noise_freq_y = 0.32f;     
    int dot_count = 3;               
    int emitter_mode = 0;            
    float endpoint_speed = 0.80f;    
    bool reverse_x_profile = true;   
    bool show_flow_vectors = false;  
};

class FlowField : public Fx2d {
  public:
    using Params = FlowFieldParams;
 
    ~FlowField() FL_NO_EXCEPT override = default;

    void draw(DrawContext context) FL_NO_EXCEPT override;
 
    // Parameter setters.
    void setPersistence(float halfLife) FL_NO_EXCEPT { mParams.persistence = halfLife; }
    void setColorShift(float speed) FL_NO_EXCEPT { mParams.color_shift = speed; }
    void setFlowAmplitudeX(float amp) FL_NO_EXCEPT { mParams.flow_amp_x = amp; }
    void setFlowAmplitudeY(float amp) FL_NO_EXCEPT { mParams.flow_amp_y = amp; }
    void setFlowShift(float shift) FL_NO_EXCEPT { mParams.flow_shift = shift; }
    void setFlowSpeedX(float speed) FL_NO_EXCEPT { mParams.flow_speed_x = speed; }
    void setFlowSpeedY(float speed) FL_NO_EXCEPT { mParams.flow_speed_y = speed; }
    void setNoiseFrequencyX(float freq) FL_NO_EXCEPT { mParams.noise_freq_x = freq; }
    void setNoiseFrequencyY(float freq) FL_NO_EXCEPT { mParams.noise_freq_y = freq; }
    void setNoiseFrequency(float freq) FL_NO_EXCEPT {
        mParams.noise_freq_x = freq;
        mParams.noise_freq_y = freq;
    }
    void setDotCount(int count) FL_NO_EXCEPT { mParams.dot_count = count; }
    void setEmitterMode(int mode) FL_NO_EXCEPT { mParams.emitter_mode = mode; }
    void setEndpointSpeed(float speed) FL_NO_EXCEPT { mParams.endpoint_speed = speed; }
    void setReverseXProfile(bool rev) FL_NO_EXCEPT { mParams.reverse_x_profile = rev; }
    void setShowFlowVectors(bool show) FL_NO_EXCEPT { mParams.show_flow_vectors = show; }

    void setSpeed(float speed) FL_NO_EXCEPT { mTimeWarp.setSpeed(speed); }
    float speed() const FL_NO_EXCEPT { return mTimeWarp.scale(); }

    void noisePunch(float amplitude = 1.0f,
                    BumpShape shape = BumpShape::HalfSine) FL_NO_EXCEPT;

    void noisePunchX(float center, float width, float amplitude = 1.0f,
                     BumpShape shape = BumpShape::HalfSine) FL_NO_EXCEPT;

    void noisePunchY(float center, float width, float amplitude = 1.0f,
                     BumpShape shape = BumpShape::HalfSine) FL_NO_EXCEPT;
 
    NoiseBias2D &noiseBias() FL_NO_EXCEPT { return mNoiseBias; }
    const NoiseBias2D &noiseBias() const FL_NO_EXCEPT { return mNoiseBias; }
 
    Params &getParams() FL_NO_EXCEPT { return mParams; }
    const Params &getParams() const FL_NO_EXCEPT { return mParams; }
 
  protected:
    explicit FlowField(const XYMap &xyMap, const Params &params = Params()) FL_NO_EXCEPT;

    virtual void drawImpl(DrawContext context, u32 dt_ms, u32 t_ms) FL_NO_EXCEPT = 0;
 
    Params mParams;
    NoiseBias2D mNoiseBias;
 
  private:
    TimeWarp mTimeWarp;
    u32 mLastWarpedMs = 0;
};

class FlowFieldFloat : public FlowField {
  public:
    explicit FlowFieldFloat(const XYMap &xyMap, const Params &params = Params()) FL_NO_EXCEPT;
 
    fl::string fxName() const FL_NO_EXCEPT override { return "FlowFieldFloat"; }
 
  protected:
    void drawImpl(DrawContext context, u32 dt_ms, u32 t_ms) FL_NO_EXCEPT override;
 
  private:
    // Seeded 2D Perlin noise generator.
    class Perlin2D {
      public:
        void init(u32 seed) FL_NO_EXCEPT;
        float noise(float x, float y) const FL_NO_EXCEPT;
 
      private:
        u8 perm[512];
        static float fade(float t) FL_NO_EXCEPT {
            return t * t * t * (t * (t * 6.0f - 15.0f) + 10.0f);
        }
        static float lerp(float a, float b, float t) FL_NO_EXCEPT {
            return a + t * (b - a);
        }
        static float grad(int h, float x, float y) FL_NO_EXCEPT;
    };
 
    // Grid access helpers (row-major layout).
    int idx(int y, int x) const FL_NO_EXCEPT {
        return y * (int)getWidth() + x;
    }
 
    // Helpers.
    static float fmodPos(float x, float m) FL_NO_EXCEPT;
    static float clampf(float v, float lo, float hi) FL_NO_EXCEPT;
    static u8 f2u8(float v) FL_NO_EXCEPT;
    static CRGB rainbow(float t, float speed, float phase) FL_NO_EXCEPT;
 
    // Sub-steps called from drawImpl().
    void flowPrepare(float t) FL_NO_EXCEPT;
    void emitOrbitalDots(float t) FL_NO_EXCEPT;
    void flowAdvect(float dt) FL_NO_EXCEPT;
    void drawDot(float cx, float cy, float diam,
                 u8 cr, u8 cg, u8 cb) FL_NO_EXCEPT;
    void drawAALine(float x0, float y0, float x1, float y1,
                    float t, float colorShift) FL_NO_EXCEPT;
    void emitLissajousLine(float t) FL_NO_EXCEPT;
 
    void drawFlowVectors(fl::span<CRGB> leds) FL_NO_EXCEPT;
 
    // Float-precision RGB grids (main + temp for advection).
    fl::vector<float> mR, mG, mB;
    fl::vector<float> mTR, mTG, mTB;
 
    // Noise generators and profiles.
    Perlin2D mNoiseGenX, mNoiseGenY;
    fl::vector<float> mXProf; 
    fl::vector<float> mYProf; 
};

class FlowFieldFP : public FlowField {
  public:
    explicit FlowFieldFP(const XYMap &xyMap, const Params &params = Params()) FL_NO_EXCEPT;
 
    fl::string fxName() const FL_NO_EXCEPT override { return "FlowFieldFP"; }
 
  protected:
    void drawImpl(DrawContext context, u32 dt_ms, u32 t_ms) FL_NO_EXCEPT override;
 
  private:
    friend struct FlowFieldFPProfiler;  // For per-phase profiling
 
    // Grid access helpers (row-major layout).
    int idx(int y, int x) const FL_NO_EXCEPT {
        return y * mState.width + x;
    }
 
    // Helpers.
    static i32 clamp_q16(i32 v, i32 lo, i32 hi) FL_NO_EXCEPT;
    static u8 q16_to_u8(i32 v) FL_NO_EXCEPT;
    static CRGB rainbow(s16x16 t, s16x16 speed, s16x16 phase) FL_NO_EXCEPT;
 
    // Sub-steps — all pure fixed-point.
    void flowPrepare(s16x16 t) FL_NO_EXCEPT;
    void emitOrbitalDots(s16x16 t) FL_NO_EXCEPT;
    void flowAdvect(i32 dt_raw) FL_NO_EXCEPT;
    void drawDot(s16x16 cx, s16x16 cy, s16x16 diam,
                 u8 cr, u8 cg, u8 cb) FL_NO_EXCEPT;
    void drawAALine(s16x16 x0, s16x16 y0, s16x16 x1, s16x16 y1,
                    s16x16 t, s16x16 colorShift) FL_NO_EXCEPT;
    void emitLissajousLine(s16x16 t) FL_NO_EXCEPT;
 
    void drawFlowVectors(fl::span<CRGB> leds) FL_NO_EXCEPT;
 
    // Convert float params to cached s16x16 values.
    void syncParams() FL_NO_EXCEPT;
 
    // Perm table initialization (Fisher-Yates shuffle).
    static void initPerm256(u8 *perm, u32 seed) FL_NO_EXCEPT;
 
    FlowFieldFPState mState;
    u8 mPermX[256] = {};
    u8 mPermY[256] = {};
 
    // Cached s16x16 versions of float params.
    s16x16 mColorShift_fp;
    s16x16 mFlowShift_fp;
    s16x16 mEndpointSpeed_fp;
    s16x16 mPersistence_fp;
    s16x16 mNoiseFreqX_fp, mNoiseFreqY_fp;
    s16x16 mFlowSpeedX_fp, mFlowSpeedY_fp;
    s16x16 mFlowAmpX_fp, mFlowAmpY_fp;
};
 
} // namespace fl