corkscrew.h

Go to the documentation of this file.

#pragma once

 
#include "fl/stl/allocator.h"
#include "fl/math/geometry.h"
#include "fl/math/math.h"
#include "fl/gfx/tile2x2.h"
#include "fl/stl/vector.h"
#include "fl/stl/shared_ptr.h"
#include "fl/stl/variant.h"
#include "fl/stl/span.h"
#include "fl/stl/int.h"
#include "fl/stl/noexcept.h"
 
namespace fl {
 
// Forward declarations
class Leds;
class ScreenMap;
template<typename T> class Grid;
 
// Simple constexpr functions for compile-time corkscrew dimension calculation
constexpr fl::u16 calculateCorkscrewWidth(float totalTurns, fl::u16 numLeds) {
    return static_cast<fl::u16>(ceil_constexpr(static_cast<float>(numLeds) / totalTurns));
}
 
constexpr fl::u16 calculateCorkscrewHeight(float totalTurns, fl::u16 numLeds) {
    return (calculateCorkscrewWidth(totalTurns, numLeds) * static_cast<int>(ceil_constexpr(totalTurns)) > numLeds) ?
        static_cast<fl::u16>(ceil_constexpr(static_cast<float>(numLeds) / static_cast<float>(calculateCorkscrewWidth(totalTurns, numLeds)))) :
        static_cast<fl::u16>(ceil_constexpr(totalTurns));
}

struct Gap {
    int num_leds = 0;   // Number of LEDs after which gap is activated, 0 = no gap
    float gap = 0.0f;   // Gap value from 0 to 1, represents percentage of width unit to add
    
    Gap() FL_NOEXCEPT = default;
    Gap(float g) : num_leds(0), gap(g) {} // Backwards compatibility constructor
    Gap(int n, float g) : num_leds(n), gap(g) {} // New constructor with num_leds
    
    // Rule of 5 for POD data
    Gap(const Gap &other) FL_NOEXCEPT = default;
    Gap &operator=(const Gap &other) = default;
    Gap(Gap &&other) FL_NOEXCEPT = default;
    Gap &operator=(Gap &&other) FL_NOEXCEPT = default;
};
 
// Maps a Corkscrew defined by the input to a cylindrical mapping for rendering
// a densly wrapped LED corkscrew.
class Corkscrew {
  public:
    
    // Pixel storage variants - can hold either external span or owned vector
    using PixelStorage = fl::variant<fl::span<CRGB>, fl::vector_psram<CRGB>>;
 
    // Iterator class moved from CorkscrewState
    class iterator {
      public:
        using value_type = vec2f;
        using difference_type = fl::i32;
        using pointer = vec2f *;
        using reference = vec2f &;
        using iterator_category = fl::bidirectional_iterator_tag;
 
        iterator(const Corkscrew *corkscrew, fl::size position)
            : mCorkscrew(corkscrew), mPosition(position) {}
 
        vec2f operator*() const;
 
        iterator &operator++() {
            ++mPosition;
            return *this;
        }
 
        iterator operator++(int) {
            iterator temp = *this;
            ++mPosition;
            return temp;
        }
 
        iterator &operator--() {
            --mPosition;
            return *this;
        }
 
        iterator operator--(int) {
            iterator temp = *this;
            --mPosition;
            return temp;
        }
 
        bool operator==(const iterator &other) const {
            return mPosition == other.mPosition;
        }
 
        bool operator!=(const iterator &other) const {
            return mPosition != other.mPosition;
        }
 
        difference_type operator-(const iterator &other) const {
            return static_cast<difference_type>(mPosition) -
                   static_cast<difference_type>(other.mPosition);
        }
 
      private:
        const Corkscrew *mCorkscrew;
        fl::size mPosition;
    };
 
    // Constructors that integrate input parameters directly
    // Primary constructor with default values for invert and gapParams
    Corkscrew(float totalTurns, fl::u16 numLeds, bool invert = false, const Gap& gapParams = Gap());
    
    // Constructor with external pixel buffer - these pixels will be drawn to directly
    Corkscrew(float totalTurns, fl::span<CRGB> dstPixels, bool invert = false, const Gap& gapParams = Gap());
    
    Corkscrew(const Corkscrew &) FL_NOEXCEPT = default;
    Corkscrew(Corkscrew &&) FL_NOEXCEPT = default;
 
    // Caching control
    void setCachingEnabled(bool enabled);
 
    // Essential API - Core functionality
    fl::u16 cylinderWidth() const { return mWidth; }
    fl::u16 cylinderHeight() const { return mHeight; }
 
    // Enhanced surface handling with shared_ptr
    // Note: Input surface will be created on first call
    fl::shared_ptr<fl::Grid<CRGB>>& getOrCreateInputSurface();
    
    // Draw like a regular rectangle surface - access input surface directly
    fl::Grid<CRGB>& surface();
 
    // Draw the corkscrew by reading from the internal surface and populating LED pixels
    void draw(bool use_multi_sampling = true);
 
    // Pixel storage access - works with both external and owned pixels
    // This represents the pixels that will be drawn after draw() is called
    CRGB* rawData();
    
    // Returns span of pixels that will be written to when draw() is called
    fl::span<CRGB> data();
    
    fl::size pixelCount() const;
    // Create and return a fully constructed ScreenMap for this corkscrew
    // Each LED index will be mapped to its exact position on the cylindrical surface
    fl::ScreenMap toScreenMap(float diameter = 0.5f) const;
 
    // STL-style container interface
    fl::size size() const;
    iterator begin() { return iterator(this, 0); }
    iterator end() { return iterator(this, size()); }
 
    // Non-essential API - Lower level access
    vec2f at_no_wrap(fl::u16 i) const;
    vec2f at_exact(fl::u16 i) const;
    Tile2x2_u8_wrap at_wrap(float i) const;
 
    // Clear all buffers and free memory
    void clear();
    
    // Fill the input surface with a color
    void fillInputSurface(const CRGB& color);
 
  private:
    // For internal use. Splats the pixel on the surface which
    // extends past the width. This extended Tile2x2 is designed
    // to be wrapped around with a Tile2x2_u8_wrap.
    Tile2x2_u8 at_splat_extrapolate(float i) const;
 
    // Read from fl::Grid<CRGB> object and populate our internal rectangular buffer
    // by sampling from the XY coordinates mapped to each corkscrew LED position
    // use_multi_sampling = true will use multi-sampling to sample from the source grid,
    // this will give a little bit better accuracy and the screenmap will be more accurate.
    void readFrom(const fl::Grid<CRGB>& source_grid, bool use_multi_sampling = true);
    
    // Read from rectangular buffer using multi-sampling and store in target grid
    // Uses Tile2x2_u8_wrap for sub-pixel accurate sampling with proper blending
    void readFromMulti(const fl::Grid<CRGB>& target_grid) const;
    
    // Initialize the rectangular buffer if not already done
    void initializeBuffer() const;
    
    // Initialize the cache if not already done and caching is enabled
    void initializeCache() const;
    
    // Calculate the tile at position i without using cache
    Tile2x2_u8_wrap calculateTileAtWrap(float i) const;
 
    // Core corkscrew parameters (moved from CorkscrewInput)
    float mTotalTurns = 19.0f;   // Total turns of the corkscrew
    fl::u16 mNumLeds = 144;      // Number of LEDs
    Gap mGapParams;              // Gap parameters for gap accounting  
    bool mInvert = false;        // If true, reverse the mapping order
    
    // Cylindrical mapping dimensions (moved from CorkscrewState)
    fl::u16 mWidth = 0;          // Width of cylindrical map (circumference of one turn)
    fl::u16 mHeight = 0;         // Height of cylindrical map (total vertical segments)
    
    // Enhanced pixel storage - variant supports both external and owned pixels
    PixelStorage mPixelStorage;
    bool mOwnsPixels = false; // Track whether we own the pixel data
    
    // Input surface for drawing operations
    fl::shared_ptr<fl::Grid<CRGB>> mInputSurface;
    
    // Caching for Tile2x2_u8_wrap objects
    mutable fl::vector<Tile2x2_u8_wrap> mTileCache;
    mutable bool mCacheInitialized = false;
    bool mCachingEnabled = true; // Default to enabled
};
 
} // namespace fl