lamp_type.hpp

Go to the documentation of this file.

 
#ifndef MODES_HARDWARE_LAMP_TYPE_HPP
#define MODES_HARDWARE_LAMP_TYPE_HPP
 
#include <cstdint>
#include <cstring>
 
#include "src/compile.h"
#include "src/user/constants.h"
 
#include "src/system/physical/output_power.h"
#include "src/system/physical/sound.h"
 
#ifdef LMBD_LAMP_TYPE__INDEXABLE
#include "src/system/physical/strip.h"
#endif
 
#include "src/system/platform/time.h"
 
#include "src/system/logic/brightness_handle.h"
 
#include "src/system/utils/assert.h"
#include "src/system/utils/print.h"
#include "src/system/utils/curves.h"
#include "src/system/utils/constants.h"
#include "src/system/utils/utils.h"
 
#include "src/system/ext/math8.h"
 
#include "src/modes/include/compile.hpp"
#include "src/modes/include/colors/utils.hpp"
#include "src/modes/include/hardware/coordinates.hpp"
 
namespace lampda::modes {
 
struct XYTy
{
  uint16_t x; 
  uint16_t y; 
};
 
static constexpr uint16_t to_strip(uint16_t, uint16_t);
static constexpr XYTy strip_to_XY(uint16_t n);
 
struct HelixXYZTy
{
  float x; 
  float y; 
  float z; 
};
 
static constexpr HelixXYZTy strip_to_helix(int16_t n);
 
static constexpr HelixXYZTy strip_to_helix_unconstraint(const int16_t n);
static constexpr bool is_led_index_valid(const int16_t ledIndex);
static constexpr bool is_lamp_coordinate_out_of_bounds(const float angle_rad, const float z);
 
static constexpr uint16_t to_led_index(const float angle_rad, const float z);
 
static constexpr int16_t to_led_index_no_bounds(const float angle_rad, const float z);
 
} // namespace lampda::modes
 
namespace lampda::modes::hardware {
 
enum class LampTypes : uint8_t
{
  simple,    
  cct,       
  indexable, 
};
 
#ifdef LMBD_LAMP_TYPE__SIMPLE
static constexpr LampTypes _lampType = LampTypes::simple;
#endif
 
#ifdef LMBD_LAMP_TYPE__CCT
static constexpr LampTypes _lampType = LampTypes::cct;
#endif
 
#ifdef LMBD_LAMP_TYPE__INDEXABLE
static constexpr LampTypes _lampType = LampTypes::indexable;
#endif
 
static constexpr LampTypes lampType = _lampType;
 
struct LampTy
{
  //
  // state managed by manager
  //
 
  struct LampConfig
  {
    uint16_t skipFirstLedsForEffect = 0; 
    uint16_t skipFirstLedsForAmount = 0; 
  };
 
  LampConfig config;
 
  //
  // private constructors
  //
 
#ifdef LMBD_LAMP_TYPE__INDEXABLE
private:
  static constexpr float _fwidth = stripXCoordinates;                    
  static constexpr float _fheight = stripYCoordinates;                   
  static constexpr uint16_t _width = floor(_fwidth);                     
  static constexpr uint16_t _height = floor(_fheight);                   
  static constexpr uint16_t _ledCount = LED_COUNT;                       
  static constexpr uint16_t _nbBuffers = stripNbBuffers;                 
  static constexpr float _lampBodyRadius_mm = lampda::lampBodyRadius_mm; 
  static constexpr float _ledStripWidth_mm = lampda::ledStripWidth_mm;   
  static constexpr float _ledStripLength_mm = lampda::ledStripLength_mm; 
  static constexpr float _ledByMeter = lampda::ledByMeter;               
  physical::LedStrip& strip;                                             
 
  static constexpr uint16_t _safeBufSize = (_width + 1) * (_height + 1);
 
  using BufferTy = std::array<uint32_t, _ledCount>;
  // using BufferTy = std::array<uint32_t, _safeBufSize>;
 
  LampTy() = delete;                         
  LampTy(const LampTy&) = delete;            
  LampTy& operator=(const LampTy&) = delete; 
 
public:
  LMBD_INLINE LampTy(physical::LedStrip& strip) : config {}, strip {strip}, now {0}, tick {0}, raw_frame_count {0} {}
#else
private:
  // (placeholder values to avoid bad fails on misuse)
  static constexpr float _fwidth = 23.5451;          
  static constexpr float _fheight = 22.51;           
  static constexpr uint16_t _width = 23;             
  static constexpr uint16_t _height = 22;            
  static constexpr uint16_t _ledCount = 530;         
  static constexpr uint16_t _nbBuffers = 3;          
  static constexpr float _lampBodyRadius_mm = 25.0f; 
  static constexpr float _ledStripWidth_mm = 5.2f;   
  static constexpr float _ledStripLength_mm = 25.0f; 
  static constexpr float _ledByMeter = 160.0f;       
 
  static constexpr uint16_t _safeBufSize = (_width + 1) * (_height + 1);
 
  using BufferTy = std::array<uint32_t, _ledCount>;
  // using BufferTy = std::array<uint32_t, _safeBufSize>;
 
  LampTy(const LampTy&) = delete;            
  LampTy& operator=(const LampTy&) = delete; 
 
  struct LedStrip 
  {
    BufferTy _buffers[_nbBuffers];
    COLOR _colors[_ledCount]; // !! slighly smaller than buffers in _buffers !!
 
    void begin();
    void show();
    void show_now();
    void signal_display();
    void setBrightness(brightness_t);
    uint8_t getBrightness();
    void setPixelColor(uint16_t, uint32_t);
    uint32_t getPixelColor(uint16_t);
  };
  LedStrip fakeStrip; 
  LedStrip& strip;    
 
public:
  LMBD_INLINE LampTy() : config {}, fakeStrip {}, strip {fakeStrip}, now {0}, tick {0}, raw_frame_count {0} {}
#endif
 
  //
  // private API
  //
 
  void LMBD_INLINE refresh_tick_value()
  {
    uint32_t* writeable_now = const_cast<uint32_t*>(&now);
    *writeable_now = platform::time_ms();
 
    uint32_t* writable_tick = const_cast<uint32_t*>(&tick);
    *writable_tick = now / frameDurationMs;
 
    uint32_t* writable_frame_count = const_cast<uint32_t*>(&raw_frame_count);
    *writable_frame_count += 1; // monotonous
  }
 
  void LMBD_INLINE startup()
  {
    // set output voltage for leds that will not change voltage
    if (stripInputMinVoltage_mV == stripInputMaxVoltage_mV)
      physical::outputPower::write_voltage(stripInputMaxVoltage_mV);
 
    begin();
    clear();
    show_now();
    setBrightness(logic::brightness::get_saved_brightness(), true, true);
    align_internal_to_system_brightness();
  }
 
  void LMBD_INLINE begin()
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      strip.begin();
    }
    else
    {
      // (this is optimized out, and is essentially no-op for other flavors)
      assert(true);
    }
  }
 
  void LMBD_INLINE show()
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      strip.show();
    }
    else
    {
      // (this is optimized out, and is essentially no-op for other flavors)
      assert(true);
    }
  }
 
  void LMBD_INLINE show_now()
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      strip.show_now();
    }
    else
    {
      // (this is optimized out, and is essentially no-op for other flavors)
      assert(true);
    }
  }
 
  void LMBD_INLINE signal_display()
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      strip.signal_display();
    }
    else
    {
      // (this is optimized out, and is essentially no-op for other flavors)
      assert(true);
    }
  }
 
  //
  // public constants
  //
 
  static constexpr LampTypes flavor = lampType;
 
  static constexpr uint32_t frameDurationMs = MAIN_LOOP_UPDATE_PERIOD_MS;
 
#ifndef LMBD_LAMP_TYPE__INDEXABLE_IS_HD
  // (we have 12ms and 83.3fps values to be updated in this file)
  static_assert(frameDurationMs == 12, "Update the documentation of .tick :)");
#endif
 
  static constexpr uint32_t brightnessDurationMs = frameDurationMs * 2;
 
  static constexpr uint16_t ledCount = _ledCount;
 
  static constexpr uint16_t maxWidth = _width;
 
  static constexpr float maxWidthFloat = _fwidth;
 
  static constexpr uint16_t maxOverflowWidth = maxWidth + 1;
 
  static constexpr uint16_t maxHeight = _height;
 
  static constexpr float maxHeightFloat = _fheight;
 
  static constexpr uint16_t maxOverflowHeight = maxHeight + 1;
 
  static constexpr float shiftPerTurn = _fwidth - floor(_fwidth - 0.0001);
 
  static constexpr uint16_t shiftPeriod = 2;
 
  static constexpr float _invShiftResidue = shiftPeriod * (_fwidth - floor(_fwidth - 0.0001));
 
  static constexpr uint16_t shiftResidue = 100.0 / abs(100.0 * _invShiftResidue - 100.0);
 
  static constexpr auto allResiduesY = details::computeResidues<maxOverflowHeight>(_fwidth);
 
  static constexpr auto allDeltaResiduesY = details::computeDeltaResidues<maxOverflowHeight>(_fwidth);
 
  static constexpr auto extraShiftResiduesY = details::computeExtraShiftResidues<maxOverflowHeight>(_fwidth);
 
  static constexpr int extraShiftTotal = extraShiftResiduesY[maxOverflowHeight - 1];
 
  static constexpr float lampBodyRadius_mm = _lampBodyRadius_mm;
 
  static constexpr float ledStripWidth_mm = _ledStripWidth_mm;
  static constexpr float ledStripLength_mm = _ledStripLength_mm;
 
  static constexpr float ledByMeter = _ledByMeter;
 
  static constexpr float ledSize_mm = 1000.0f / ledByMeter;
  static constexpr float lampBodyCircumpherence_mm = c_TWO_PI * lampBodyRadius_mm;
  static constexpr float ledPerTurns = lampBodyCircumpherence_mm / ledSize_mm;
  static constexpr float lampHeight_mm = ledStripWidth_mm * ledCount / ledPerTurns;
 
  static constexpr uint8_t nbBuffers = _nbBuffers;
 
  //
  // public helpers
  //
 
  template<typename T> static constexpr LMBD_INLINE uint16_t toLedCount(T scale)
  {
    if constexpr (std::is_same_v<T, float>)
    {
      assert(scale <= 1.0 && "scale is 0-1");
      return ledCount * scale;
    }
    else if constexpr (std::is_same_v<T, uint8_t>)
    {
      uint32_t scaled = ledCount * scale;
      return scaled / 256;
    }
    else
    {
      static_assert(std::is_same_v<T, std::false_type>, "Invalid type, either float or uint8_t required!");
      return 0;
    }
  }
 
  //
  // public API
  //
 
  void LMBD_INLINE clear()
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      for (uint16_t i = 0; i < ledCount; ++i)
      {
        setPixelColor(i, colors::Black);
      }
    }
    else
    {
      // (this is optimized out, and is essentially no-op for other flavors)
      assert(true);
    }
  }
 
  void LMBD_INLINE blip(const uint32_t duration)
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      // disable strip temporarily
      // should be reactivated by the manager
      tempBrightness(0);
    }
    else
    {
      physical::outputPower::blip(duration);
    }
  }
 
  void LMBD_INLINE cancel_blip() const { return physical::outputPower::cancel_blip(); }
 
  bool LMBD_INLINE is_bliping() const { return physical::outputPower::is_bliping(); }
 
  void LMBD_INLINE setBrightness(const brightness_t newBrightness,
                                 const bool skipCallbacks = true,
                                 const bool skipUpdateBrightness = false,
                                 const bool updateSavedBrightess = false)
  {
    assert((skipCallbacks || !skipUpdateBrightness) && "implicit callback skip!");
 
    // invalid call, fallback to enforcing
    if (newBrightness > ::lampda::brightness::absoluteMaximumBrightness)
    {
      enforce_internal_brightness_limits();
      return;
    }
 
    // force update if we are getting lower and lower
    if (!skipUpdateBrightness or newBrightness > getMaxBrightness())
    {
      // store the new temporary
      temporary_brightness = min<brightness_t>(newBrightness, getMaxBrightness());
 
      uint32_t last = logic::brightness::when_last_update_brightness();
      if ((this->now - last) > brightnessDurationMs)
        logic::brightness::update_brightness(temporary_brightness, skipCallbacks);
    }
    // if necessary, update the saved version
    if (updateSavedBrightess)
    {
      saved_brightness = min<brightness_t>(static_cast<brightness_t>(temporary_brightness), getMaxBrightness());
    }
 
    // USE THE BRIGHTNESS VALUE AFTER THE UPDATE
    // brightness can be limited by the system, so do not use the raw brightness
    const auto trueNewBrightness = logic::brightness::get_brightness();
 
    if constexpr (flavor == LampTypes::indexable)
    {
#ifndef LMBD_LAMP_TYPE__INDEXABLE
      static constexpr uint8_t minimumAllowedBrightness = 5;
#else
      static constexpr uint8_t minimumAllowedBrightness = ::lampda::minimumAllowedBrightness_8;
#endif
      using curve_t = utils::curves::LinearCurve<brightness_t, uint8_t>;
      static curve_t brightnessCurve({curve_t::point_t {0, minimumAllowedBrightness},
                                      curve_t::point_t {::lampda::brightness::absoluteMaximumBrightness, 255}});
 
      strip.setBrightness(brightnessCurve.sample(trueNewBrightness));
    }
 
    if constexpr (flavor == LampTypes::simple)
    {
      const auto trueMaxBrightness = logic::brightness::get_max_brightness();
 
      // This is kind of a hack to detect that the user did this call
      // using the known user call signature
      const bool isUserCall = skipCallbacks and skipUpdateBrightness and not updateSavedBrightess;
 
      // display an output blip on max brightness reached
      if (isUserCall and trueNewBrightness >= trueMaxBrightness)
      {
        physical::outputPower::blip(50); // blip
      }
 
      using curve_t = utils::curves::ExponentialCurve<brightness_t, uint16_t>;
      static curve_t brightnessCurve(
              curve_t::point_t {0, stripInputMinVoltage_mV},
              curve_t::point_t {::lampda::brightness::absoluteMaximumBrightness, stripInputMaxVoltage_mV},
              1.0);
 
      physical::outputPower::write_voltage(round(brightnessCurve.sample(trueNewBrightness)));
    }
  }
 
  void align_internal_to_system_brightness()
  {
    saved_brightness = min<brightness_t>(logic::brightness::get_saved_brightness(), getMaxBrightness());
    temporary_brightness = saved_brightness;
  }
 
  void enforce_internal_brightness_limits()
  {
    const auto maxAllowedBrightness = getMaxBrightness();
    const brightness_t new_saved_brightness =
            min<brightness_t>(static_cast<brightness_t>(saved_brightness), maxAllowedBrightness);
    const brightness_t new_temporary_brightness =
            min<brightness_t>(static_cast<brightness_t>(temporary_brightness), maxAllowedBrightness);
 
    const bool isChanged = new_saved_brightness != saved_brightness or new_temporary_brightness != temporary_brightness;
    if (isChanged)
    {
      saved_brightness = new_saved_brightness;
      temporary_brightness = new_temporary_brightness;
 
      setBrightness(temporary_brightness);
    }
  }
 
  brightness_t LMBD_INLINE getMaxBrightness() const { return logic::brightness::get_max_user_brightness(); }
 
  void LMBD_INLINE tempBrightness(const brightness_t brightness)
  {
    brightness_t current = getBrightness();
    if (current != brightness)
      setBrightness(brightness, true, false, false);
  }
 
  void LMBD_INLINE jumpBrightness(const brightness_t brightness) { setBrightness(brightness, true, false, true); }
 
  brightness_t LMBD_INLINE getBrightness(const bool readPreviousBrightness = false)
  {
    if (readPreviousBrightness)
      return saved_brightness;
    else
      return temporary_brightness;
  }
 
  brightness_t LMBD_INLINE getSavedBrightness() { return getBrightness(true); }
 
  void LMBD_INLINE restoreBrightness()
  {
    const brightness_t current = getBrightness();
    const brightness_t saved = getSavedBrightness();
 
    if (current != saved)
      setBrightness(saved, true, false, false);
  }
 
  void LMBD_INLINE fadeToBlackBy(uint8_t fadeBy)
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      if (fadeBy == 0)
        return; // optimization - no scaling to apply
 
      for (uint16_t i = 0; i < ledCount; ++i)
      {
        const uint32_t c = getPixelColor(i);
        setPixelColor(i, colors::fade(c, 255 - fadeBy));
      }
    }
    else
    {
      uint8_t brightness = getBrightness();
      brightness = (brightness < fadeBy) ? 0 : brightness - fadeBy;
      setBrightness(brightness);
    }
  }
 
  void LMBD_INLINE blur(uint8_t blurBy)
  {
    if (blurBy == 0)
      return; // optimization: 0 means "don't blur"
    uint8_t keep = 255 - blurBy;
    uint8_t seep = blurBy >> 1;
 
    uint32_t carryover = 0;
    for (unsigned i = 0; i < ledCount; i++)
    {
      uint32_t cur = getPixelColor(i);
      uint32_t c = cur;
      uint32_t part = colors::fade<false>(c, seep);
      cur = colors::add<true>(colors::fade<false>(c, keep), carryover);
      if (i > 0)
      {
        c = getPixelColor(i - 1);
        setPixelColor(i - 1, colors::add<true>(c, part));
      }
      setPixelColor(i, cur);
      carryover = part;
    }
  }
 
  //
  // public API (indexable-only)
  //
 
  void LMBD_INLINE fill(uint32_t color, uint16_t start, uint16_t end)
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      assert(start <= ledCount && "invalid start parameter");
      assert(end <= ledCount && "invalid end parameter");
 
      for (uint16_t I = start; I < end; ++I)
      {
        setPixelColor(I, color);
      }
    }
    else
    {
      assert(false && "unsupported");
    }
  }
 
  void LMBD_INLINE fill(uint32_t color, uint16_t start, uint16_t end, const BufferTy& shouldDisplay)
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      assert(start <= ledCount && "invalid start parameter");
      assert(end <= ledCount && "invalid end parameter");
 
      for (uint16_t I = start; I < end; ++I)
      {
        const uint8_t blendValue = min<uint32_t>(shouldDisplay[I], UINT8_MAX);
        setPixelColor(I, colors::blend(0, color, blendValue));
      }
    }
    else
    {
      assert(false && "unsupported");
    }
  }
 
  void LMBD_INLINE fill(uint32_t color) { fill(color, 0, ledCount); }
 
  void LMBD_INLINE fill(uint32_t color, const BufferTy& shouldDisplay) { fill(color, 0, ledCount, shouldDisplay); }
 
  void LMBD_INLINE fill(const colors::PaletteTy& palette, uint16_t start, uint16_t end)
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      assert(start < ledCount && "invalid start parameter");
      assert(end <= ledCount && "invalid end parameter");
 
      for (uint16_t I = start; I < end; ++I)
      {
        // map index to [0; 255]
        const auto color = colors::from_palette<false, uint8_t>(I / static_cast<float>(ledCount) * 255, palette);
        setPixelColor(I, color);
      }
    }
    else
    {
      assert(false && "unsupported");
    }
  }
 
  void LMBD_INLINE fill(const colors::PaletteTy& palette) { fill(palette, 0, ledCount); }
 
  void LMBD_INLINE setPixelColor(uint16_t n, uint32_t color)
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      if (config.skipFirstLedsForEffect && n < config.skipFirstLedsForAmount)
      {
        return;
      }
 
      assert(n < ledCount && "invalid LED index");
      strip.setPixelColor(n, color);
    }
    else
    {
      assert(false && "unsupported");
    }
  }
 
  uint32_t LMBD_INLINE getPixelColor(uint16_t n)
  {
    if constexpr (flavor == LampTypes::indexable)
    {
      if (config.skipFirstLedsForEffect && n < config.skipFirstLedsForAmount)
      {
        return 0;
      }
 
      assert(n < ledCount && "invalid LED index");
      return strip.getPixelColor(n);
    }
    else
    {
      assert(false && "unsupported");
    }
  }
 
  void LMBD_INLINE setPixelColorXY(uint16_t X, uint16_t Y, uint32_t color) { setPixelColor(to_strip(X, Y), color); }
 
  static uint16_t LMBD_INLINE fromXYtoStripIndex(uint16_t X, uint16_t Y) { return to_strip(X, Y); }
 
  static XYTy LMBD_INLINE fromStripIndexToXY(uint16_t N) { return strip_to_XY(N); }
 
  template<uint8_t bufIdx = 0> BufferTy& LMBD_INLINE getTempBuffer()
  {
    static_assert(bufIdx < nbBuffers, "bufIdx must be lower than nbBuffers");
    BufferTy& buffer = strip._buffers[bufIdx];
    return buffer;
  }
 
  template<uint8_t dstBufIdx, uint8_t srcBufIdx> void LMBD_INLINE copyBuffer()
  {
    static_assert(srcBufIdx < nbBuffers, "srcBufIdx must be lower than nbBuffers");
    static_assert(dstBufIdx < nbBuffers, "dstBufIdx must be lower than nbBuffers");
 
    strip._buffers[dstBufIdx] = strip._buffers[srcBufIdx];
  }
 
  template<uint8_t bufIdx = 0, typename T> void LMBD_INLINE fillTempBuffer(const T& value)
  {
    getTempBuffer<bufIdx>().fill(value);
  }
 
  template<uint8_t bufIdx = 0> void setColorsFromBuffer()
  {
    static_assert(sizeof(BufferTy) == sizeof(strip._colors));
    const BufferTy& buffer = getTempBuffer<bufIdx>();
    if (config.skipFirstLedsForEffect)
    {
      uint16_t Idx = config.skipFirstLedsForAmount;
      uint16_t Sz = sizeof(strip._colors) - Idx * sizeof(uint32_t);
      memcpy(&strip._colors[Idx], &buffer[Idx], Sz);
    }
    else
    {
      memcpy(strip._colors, buffer.data(), sizeof(strip._colors));
    }
  }
 
  template<uint8_t dstBufIdx = 0, uint8_t srcBufIdx = 1> void setColorsFromMixedBuffers(float phase)
  {
    static_assert(sizeof(BufferTy) == sizeof(strip._colors));
    const BufferTy& dstBuf = getTempBuffer<dstBufIdx>();
    const BufferTy& srcBuf = getTempBuffer<srcBufIdx>();
 
    uint16_t start = 0, end = srcBuf.size();
    if (config.skipFirstLedsForEffect)
    {
      start = config.skipFirstLedsForAmount;
    }
 
    for (uint16_t I = start; I < end; ++I)
    {
      COLOR src, dst;
      src.color = srcBuf[I];
      dst.color = dstBuf[I];
      strip._colors[I].color = utils::get_gradient(src.color, dst.color, phase);
    }
  }
 
  template<uint8_t bufIdx = 0> void setColorsFromBufferReversed(bool skipLastLine)
  {
    static_assert(sizeof(BufferTy) == sizeof(strip._colors));
    const BufferTy& buffer = getTempBuffer<bufIdx>();
 
    uint16_t start = 0, end = buffer.size();
    if (config.skipFirstLedsForEffect)
    {
      start = config.skipFirstLedsForAmount;
    }
 
    if (skipLastLine)
    {
      end = maxWidth * maxHeight;
    }
 
    for (uint16_t I = 0, J = start; I < end - start; ++I, ++J)
    {
      strip._colors[J].color = buffer[end - start - I - 1];
    }
  }
 
  template<uint8_t bufIdx = 0, bool forceFullRead = false> void getColorsToBuffer()
  {
    static_assert(sizeof(BufferTy) == sizeof(strip._colors));
 
    BufferTy& buffer = getTempBuffer<bufIdx>();
    if (!forceFullRead && config.skipFirstLedsForEffect)
    {
      uint16_t Idx = config.skipFirstLedsForAmount;
      uint16_t Sz = sizeof(strip._colors) - Idx * sizeof(uint32_t);
 
      buffer.fill(0);
      memcpy(&buffer[Idx], &strip._colors[Idx], Sz);
    }
    else
    {
      memcpy(buffer.data(), strip._colors, sizeof(strip._colors));
    }
  }
 
  physical::microphone::SoundStruct& LMBD_INLINE get_sound_struct()
  {
    return physical::microphone::get_sound_characteristics();
  }
 
  volatile brightness_t saved_brightness;
  volatile brightness_t temporary_brightness;
 
  volatile const uint32_t now;
 
  volatile const uint32_t tick;
 
  volatile const uint32_t raw_frame_count;
};
 
} // namespace lampda::modes::hardware
 
namespace lampda::modes {
 
static constexpr uint16_t to_strip(uint16_t x, uint16_t y)
{
  // maxHeight is the last "full" row and maxOverflowHeight is truncated row
  //  -> user max use to_strip(x, maxOverflowHeight) to set truncated row
  if (y >= hardware::LampTy::maxOverflowHeight)
  {
    y = hardware::LampTy::maxOverflowHeight - 1;
  }
 
  // if row is longer (because next row gets a shift) use maxOverflowWidth
  if (hardware::LampTy::allDeltaResiduesY[y])
  {
    if (x >= hardware::LampTy::maxOverflowWidth)
    {
      x = hardware::LampTy::maxOverflowWidth - 1;
    }
 
    // if row is aligned to XY maxWidth/maxHeight matrix, use maxWidth instead
  }
  else if (x >= hardware::LampTy::maxWidth)
  {
    x = hardware::LampTy::maxWidth - 1;
  }
 
  // final result is capped by the "real" LED count of the strip
  uint16_t n = x + y * hardware::LampTy::maxWidth + hardware::LampTy::allResiduesY[y];
  if (n >= hardware::LampTy::ledCount)
    n = hardware::LampTy::ledCount - 1;
  return n;
}
 
static constexpr XYTy strip_to_XY(uint16_t n)
{
  // (saturates N to ledCount)
  if (n >= hardware::LampTy::ledCount)
    n = hardware::LampTy::ledCount - 1;
 
  uint16_t y = 0;
  while (y * hardware::LampTy::maxWidth + hardware::LampTy::allResiduesY[y] <= n)
    y += 1;
 
  if (y == 0)
    return {0, 0};
  y -= 1;
 
  uint16_t x = n - y * hardware::LampTy::maxWidth - hardware::LampTy::allResiduesY[y];
  return {x, y};
}
 
static constexpr HelixXYZTy strip_to_helix(int16_t n)
{
  if (n > hardware::LampTy::ledCount)
    return HelixXYZTy {0.0, 0.0, 0.0};
 
  return strip_to_helix_unconstraint(n);
}
 
static constexpr float to_helix_z(const int16_t n)
{
  return -hardware::LampTy::ledStripWidth_mm * n / hardware::LampTy::ledPerTurns;
}
 
static constexpr HelixXYZTy strip_to_helix_unconstraint(const int16_t n)
{
  return HelixXYZTy {hardware::LampTy::maxWidthFloat * cos_t(n / hardware::LampTy::ledPerTurns * c_TWO_PI),
                     hardware::LampTy::maxWidthFloat * sin_t(n / hardware::LampTy::ledPerTurns * c_TWO_PI),
                     to_helix_z(n)};
}
 
static constexpr bool is_led_index_valid(const int16_t n) { return n >= 0 and n < hardware::LampTy::ledCount; }
 
static constexpr bool is_lamp_coordinate_out_of_bounds(const float angle_rad, const float z_mm)
{
  return not is_led_index_valid(to_led_index_no_bounds(angle_rad, z_mm));
}
 
static constexpr uint16_t to_led_index(const float angle_rad, const float z_mm)
{
  constexpr uint16_t maxZCoordinate =
          floor(-to_helix_z(hardware::LampTy::ledCount) / hardware::LampTy::ledStripWidth_mm);
 
  // snip Z per possible lines
  uint16_t zIndex = floor(-z_mm / hardware::LampTy::ledStripWidth_mm);
  if (zIndex < 0.0)
    zIndex = 0.0;
  if (zIndex > maxZCoordinate)
    zIndex = maxZCoordinate;
 
  // indexing around the led turn
  const float angularPosition = wrap_angle(angle_rad) / c_TWO_PI * hardware::LampTy::maxWidthFloat;
 
  // convert to led index (approx)
  int16_t ledIndex = round(angularPosition + zIndex * hardware::LampTy::maxWidthFloat);
  if (ledIndex < 0)
    ledIndex = round(angularPosition + (zIndex + 1) * hardware::LampTy::maxWidthFloat);
  if (ledIndex >= hardware::LampTy::ledCount)
    ledIndex = round(angularPosition + (zIndex - 1) * hardware::LampTy::maxWidthFloat);
 
  if (ledIndex < 0)
    return 0;
  if (ledIndex >= hardware::LampTy::ledCount)
    return hardware::LampTy::ledCount - 1;
  return ledIndex;
}
 
static constexpr int16_t to_led_index_no_bounds(const float angle_rad, const float z_mm)
{
  // snip Z per possible lines
  const int16_t zIndex = floor(-z_mm / hardware::LampTy::ledStripWidth_mm);
  // indexing around the led turn
  const float angularPosition = wrap_angle(angle_rad) / c_TWO_PI * hardware::LampTy::maxWidthFloat;
 
  // convert to led index (approx)
  return round(angularPosition + zIndex * hardware::LampTy::maxWidthFloat);
}
 
} // namespace lampda::modes
 
#endif