wave.h

Go to the documentation of this file.

 
#pragma once
 
#include "fl/stl/stdint.h"
 
#include "fl/gfx/blur.h"
#include "fl/gfx/gradient.h"
#include "fl/stl/shared_ptr.h"  // For FASTLED_SHARED_PTR macros and shared_ptr
#include "fl/math/wave/wave_simulation.h"
#include "fl/math/xymap.h"
#include "fl/fx/fx2d.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
 
FASTLED_SHARED_PTR(WaveFx);
FASTLED_SHARED_PTR(WaveCrgbMap);
FASTLED_SHARED_PTR(WaveCrgbMapDefault);
FASTLED_SHARED_PTR(WaveCrgbGradientMap);

class WaveCrgbMap {
  public:
    virtual ~WaveCrgbMap() FL_NO_EXCEPT = default;

    virtual void mapWaveToLEDs(const XYMap &xymap, WaveSimulation2D &waveSim,
                               fl::span<CRGB> leds) FL_NO_EXCEPT = 0;
};

class WaveCrgbMapDefault : public WaveCrgbMap {
  public:
    void mapWaveToLEDs(const XYMap &xymap, WaveSimulation2D &waveSim,
                       fl::span<CRGB> leds) FL_NO_EXCEPT override {
        const fl::u32 width = waveSim.getWidth();
        const fl::u32 height = waveSim.getHeight();
        for (fl::u32 y = 0; y < height; y++) {
            for (fl::u32 x = 0; x < width; x++) {
                fl::u32 idx = xymap(x, y);
                u8 value8 = waveSim.getu8(x, y);
                leds[idx] = CRGB(value8, value8, value8);
            }
        }
    }
};

class WaveCrgbGradientMap : public WaveCrgbMap {
  public:
    using Gradient = fl::GradientInlined;

    WaveCrgbGradientMap(const CRGBPalette16 &palette) FL_NO_EXCEPT : mGradient(palette) {}

    WaveCrgbGradientMap() FL_NO_EXCEPT = default;

    void mapWaveToLEDs(const XYMap &xymap, WaveSimulation2D &waveSim,
                       fl::span<CRGB> leds) FL_NO_EXCEPT override;

    void setGradient(const Gradient &gradient) FL_NO_EXCEPT { mGradient = gradient; }
 
  private:
    Gradient mGradient;
};

struct WaveFxArgs {
    WaveFxArgs() FL_NO_EXCEPT = default;

    WaveFxArgs(SuperSample factor, bool half_duplex, bool auto_updates,
               float speed, float dampening, WaveCrgbMapPtr crgbMap)
        FL_NO_EXCEPT : factor(factor), half_duplex(half_duplex), auto_updates(auto_updates),
          speed(speed), dampening(dampening), crgbMap(crgbMap) {}
    WaveFxArgs(const WaveFxArgs &) FL_NO_EXCEPT = default;
    WaveFxArgs &operator=(const WaveFxArgs &) FL_NO_EXCEPT = default;

    SuperSample factor = SuperSample::SUPER_SAMPLE_2X;
    bool half_duplex = true;
    bool auto_updates = true;
    float speed = 0.16f;
    float dampening = 6.0f;
    bool x_cyclical = false;
    bool use_change_grid = false;
    fl::u8 output_blur_amount = 0;
    fl::u8 output_blur_passes = 1;
    WaveCrgbMapPtr crgbMap;
};

class WaveFx : public Fx2d {
  public:
    using Args = WaveFxArgs;

    WaveFx(const XYMap& xymap, Args args = Args())
        FL_NO_EXCEPT : Fx2d(xymap), mWaveSim(xymap.getWidth(), xymap.getHeight(),
                                args.factor, args.speed, args.dampening) {
        // Initialize the wave simulation with the given parameters.
        if (args.crgbMap == nullptr) {
            // Use the default CRGB mapping function.
            mCrgbMap = fl::make_shared<WaveCrgbMapDefault>();
        } else {
            // Set a custom CRGB mapping function.
            mCrgbMap = args.crgbMap;
        }
        setAutoUpdate(args.auto_updates);
        setXCylindrical(args.x_cyclical);
        setUseChangeGrid(args.use_change_grid);
        setOutputBlur(args.output_blur_amount, args.output_blur_passes);
    }

    void setOutputBlur(fl::u8 amount, fl::u8 passes = 1) FL_NO_EXCEPT {
        mOutputBlurAmount = amount;
        mOutputBlurPasses = (passes < 1) ? 1 : passes;
    }
    fl::u8 getOutputBlurAmount() const FL_NO_EXCEPT { return mOutputBlurAmount; }
    fl::u8 getOutputBlurPasses() const FL_NO_EXCEPT { return mOutputBlurPasses; }

    void setXCylindrical(bool on) FL_NO_EXCEPT { mWaveSim.setXCylindrical(on); }

    void setSpeed(float speed) FL_NO_EXCEPT {
        // Set the speed of the wave simulation.
        mWaveSim.setSpeed(speed);
    }

    void setDampening(float dampening) FL_NO_EXCEPT {
        // Set the dampening of the wave simulation.
        mWaveSim.setDampening(dampening);
    }

    void setHalfDuplex(bool on) FL_NO_EXCEPT {
        // Set whether the wave simulation is half duplex.
        mWaveSim.setHalfDuplex(on);
    }

    void setSuperSample(SuperSample factor) FL_NO_EXCEPT {
        // Set the supersampling factor of the wave simulation.
        mWaveSim.setSuperSample(factor);
    }

    void setEasingMode(U8EasingFunction mode) FL_NO_EXCEPT {
        // Set the easing mode for the 8-bit value.
        mWaveSim.setEasingMode(mode);
    }

    void setStencil(LaplacianStencil s) FL_NO_EXCEPT {
        mWaveSim.setStencil(s);
    }

    LaplacianStencil getStencil() const FL_NO_EXCEPT {
        return mWaveSim.getStencil();
    }

    void setUseChangeGrid(bool enabled) FL_NO_EXCEPT {
        // Set whether to use the change grid tracking optimization.
        mWaveSim.setUseChangeGrid(enabled);
    }

    bool getUseChangeGrid() const FL_NO_EXCEPT {
        // Get the current change grid tracking setting.
        return mWaveSim.getUseChangeGrid();
    }

    void setf(size_t x, size_t y, float value) FL_NO_EXCEPT {
        // Set the value at the given coordinates in the wave simulation.
        mWaveSim.setf(x, y, value);
    }

    void addf(size_t x, size_t y, float value) FL_NO_EXCEPT {
        // Add a value at the given coordinates in the wave simulation.
        float sum = value + mWaveSim.getf(x, y);
        mWaveSim.setf(x, y, fl::min(1.0f, sum));
    }

    u8 getu8(size_t x, size_t y) const FL_NO_EXCEPT {
        // Get the 8-bit value at the given coordinates in the wave simulation.
        return mWaveSim.getu8(x, y);
    }

    void setCrgbMap(WaveCrgbMapPtr crgbMap) FL_NO_EXCEPT {
        // Set a custom CRGB mapping function.
        mCrgbMap = crgbMap;
    }

    void draw(DrawContext context) FL_NO_EXCEPT override {
        // Update the wave simulation.
        if (mAutoUpdates) {
            mWaveSim.update();
        }
        // Map the wave values to the LEDs.
        mCrgbMap->mapWaveToLEDs(mXyMap, mWaveSim, context.leds);
        // #3122 A4 — post-process output blur as a cheaper alternative
        // to SuperSample. Skipped entirely when amount == 0.
        if (mOutputBlurAmount > 0) {
            const fl::u32 w = mWaveSim.getWidth();
            const fl::u32 h = mWaveSim.getHeight();
            for (fl::u8 pass = 0; pass < mOutputBlurPasses; ++pass) {
                fl::blur2d(context.leds, static_cast<fl::u8>(w),
                           static_cast<fl::u8>(h), mOutputBlurAmount,
                           mXyMap);
            }
        }
    }

    void setAutoUpdate(bool autoUpdate) FL_NO_EXCEPT {
        // Set whether to automatically update the wave simulation.
        mAutoUpdates = autoUpdate;
    }

    void update() FL_NO_EXCEPT {
        // Called automatically in draw. Only invoke this if you want extra
        // simulation updates.
        // Update the wave simulation.
        mWaveSim.update();
    }

    fl::string fxName() const FL_NO_EXCEPT override { return "WaveFx"; }
 
    WaveSimulation2D mWaveSim;
    WaveCrgbMapPtr mCrgbMap;
    bool mAutoUpdates = true;
    fl::u8 mOutputBlurAmount = 0;  // #3122 A4 — 0 disables
    fl::u8 mOutputBlurPasses = 1;
};
 
} // namespace fl