pixel_iterator_adapters.h

Go to the documentation of this file.

#pragma once

 
#include "fl/stl/stdint.h"
#include "fl/stl/array.h"
#include "fl/stl/pair.h"
#include "fl/stl/iterator.h"
#include "fl/stl/noexcept.h"
#include "crgb.h"  // FASTLED_HD_COLOR_MIXING
 
namespace fl {
 
class PixelIterator;  // Forward declaration
 
namespace detail {

class ScaledPixelIteratorRGB {
public:
    // Iterator traits
    using iterator_category = input_iterator_tag;
    using value_type = array<u8, 3>;
    using difference_type = ptrdiff_t;
    using pointer = const array<u8, 3>*;
    using reference = const array<u8, 3>&;

    explicit ScaledPixelIteratorRGB(PixelIterator* pixels) FL_NO_EXCEPT
        : mPixels(pixels), mCurrent(), mHasValue(false) {
        advance();  // Preload first pixel
    }

    ScaledPixelIteratorRGB() FL_NO_EXCEPT
        : mPixels(nullptr), mCurrent(), mHasValue(false) {}

    const array<u8, 3>& operator*() const FL_NO_EXCEPT {
        return mCurrent;
    }

    const array<u8, 3>* operator->() const FL_NO_EXCEPT {
        return &mCurrent;
    }

    ScaledPixelIteratorRGB& operator++() FL_NO_EXCEPT {
        advance();
        return *this;
    }

    ScaledPixelIteratorRGB operator++(int) FL_NO_EXCEPT {
        ScaledPixelIteratorRGB tmp = *this;
        advance();
        return tmp;
    }

    bool operator==(const ScaledPixelIteratorRGB& other) const FL_NO_EXCEPT {
        // Two end iterators are equal
        if (!mHasValue && !other.mHasValue) {
            return true;
        }
        // End iterator vs valid iterator
        if (mHasValue != other.mHasValue) {
            return false;
        }
        // Two valid iterators - compare underlying pixel iterators
        return mPixels == other.mPixels;
    }

    bool operator!=(const ScaledPixelIteratorRGB& other) const FL_NO_EXCEPT {
        return !(*this == other);
    }
 
private:
    void advance() FL_NO_EXCEPT;
 
    PixelIterator* mPixels;      
    array<u8, 3> mCurrent;       
    bool mHasValue;              
};

class ScaledPixelIteratorRGBW {
public:
    // Iterator traits
    using iterator_category = input_iterator_tag;
    using value_type = array<u8, 4>;
    using difference_type = ptrdiff_t;
    using pointer = const array<u8, 4>*;
    using reference = const array<u8, 4>&;

    explicit ScaledPixelIteratorRGBW(PixelIterator* pixels) FL_NO_EXCEPT
        : mPixels(pixels), mCurrent(), mHasValue(false) {
        advance();  // Preload first pixel
    }

    ScaledPixelIteratorRGBW() FL_NO_EXCEPT
        : mPixels(nullptr), mCurrent(), mHasValue(false) {}

    const array<u8, 4>& operator*() const FL_NO_EXCEPT {
        return mCurrent;
    }

    const array<u8, 4>* operator->() const FL_NO_EXCEPT {
        return &mCurrent;
    }

    ScaledPixelIteratorRGBW& operator++() FL_NO_EXCEPT {
        advance();
        return *this;
    }

    ScaledPixelIteratorRGBW operator++(int) FL_NO_EXCEPT {
        ScaledPixelIteratorRGBW tmp = *this;
        advance();
        return tmp;
    }

    bool operator==(const ScaledPixelIteratorRGBW& other) const FL_NO_EXCEPT {
        if (!mHasValue && !other.mHasValue) {
            return true;
        }
        if (mHasValue != other.mHasValue) {
            return false;
        }
        return mPixels == other.mPixels;
    }

    bool operator!=(const ScaledPixelIteratorRGBW& other) const FL_NO_EXCEPT {
        return !(*this == other);
    }
 
private:
    void advance() FL_NO_EXCEPT;
 
    PixelIterator* mPixels;      
    array<u8, 4> mCurrent;       
    bool mHasValue;              
};

class ScaledPixelIteratorRGBWW {
public:
    using iterator_category = input_iterator_tag;
    using value_type = array<u8, 5>;
    using difference_type = ptrdiff_t;
    using pointer = const array<u8, 5>*;
    using reference = const array<u8, 5>&;
 
    explicit ScaledPixelIteratorRGBWW(PixelIterator* pixels) FL_NO_EXCEPT
        : mPixels(pixels), mCurrent(), mHasValue(false) {
        advance();
    }
 
    ScaledPixelIteratorRGBWW() FL_NO_EXCEPT
        : mPixels(nullptr), mCurrent(), mHasValue(false) {}
 
    const array<u8, 5>& operator*() const FL_NO_EXCEPT { return mCurrent; }
    const array<u8, 5>* operator->() const FL_NO_EXCEPT { return &mCurrent; }
 
    ScaledPixelIteratorRGBWW& operator++() FL_NO_EXCEPT { advance(); return *this; }
    ScaledPixelIteratorRGBWW operator++(int) FL_NO_EXCEPT {
        ScaledPixelIteratorRGBWW tmp = *this;
        advance();
        return tmp;
    }
 
    bool operator==(const ScaledPixelIteratorRGBWW& other) const FL_NO_EXCEPT {
        if (!mHasValue && !other.mHasValue) return true;
        if (mHasValue != other.mHasValue) return false;
        return mPixels == other.mPixels;
    }
 
    bool operator!=(const ScaledPixelIteratorRGBWW& other) const FL_NO_EXCEPT {
        return !(*this == other);
    }
 
private:
    void advance() FL_NO_EXCEPT;
 
    PixelIterator* mPixels;
    array<u8, 5> mCurrent;
    bool mHasValue;
};
 
#if FASTLED_HD_COLOR_MIXING
class ScaledPixelIteratorBrightness {
public:
    // Iterator traits
    using iterator_category = input_iterator_tag;
    using value_type = u8;
    using difference_type = ptrdiff_t;
    using pointer = const u8*;
    using reference = u8;

    explicit ScaledPixelIteratorBrightness(PixelIterator* pixels) FL_NO_EXCEPT
        : mPixels(pixels), mCurrent(0) {
        load();
    }

    u8 operator*() const FL_NO_EXCEPT {
        return mCurrent;
    }

    ScaledPixelIteratorBrightness& operator++() FL_NO_EXCEPT {
        load();
        return *this;
    }

    ScaledPixelIteratorBrightness operator++(int) FL_NO_EXCEPT {
        ScaledPixelIteratorBrightness tmp = *this;
        load();
        return tmp;
    }
 
    // No sentinel constructor and no comparisons, on purpose. This iterator
    // advances nothing, so it can never reach an end -- any loop written
    // against a sentinel here would spin forever. The encoders stop on the
    // RGB range they walk alongside, which is the only real termination.
 
private:
    void load() FL_NO_EXCEPT;
 
    PixelIterator* mPixels;  
    u8 mCurrent;             
};
#endif  // FASTLED_HD_COLOR_MIXING

class ScaledPixelIteratorRGB16 {
public:
    // Iterator traits
    using iterator_category = input_iterator_tag;
    using value_type = array<u16, 3>;
    using difference_type = ptrdiff_t;
    using pointer = const array<u16, 3>*;
    using reference = const array<u16, 3>&;

    explicit ScaledPixelIteratorRGB16(PixelIterator* pixels) FL_NO_EXCEPT
        : mPixels(pixels), mCurrent(), mHasValue(false) {
        advance();  // Preload first pixel
    }

    ScaledPixelIteratorRGB16() FL_NO_EXCEPT
        : mPixels(nullptr), mCurrent(), mHasValue(false) {}

    const array<u16, 3>& operator*() const FL_NO_EXCEPT {
        return mCurrent;
    }

    const array<u16, 3>* operator->() const FL_NO_EXCEPT {
        return &mCurrent;
    }

    ScaledPixelIteratorRGB16& operator++() FL_NO_EXCEPT {
        advance();
        return *this;
    }

    ScaledPixelIteratorRGB16 operator++(int) FL_NO_EXCEPT {
        ScaledPixelIteratorRGB16 tmp = *this;
        advance();
        return tmp;
    }

    bool operator==(const ScaledPixelIteratorRGB16& other) const FL_NO_EXCEPT {
        // Two end iterators are equal
        if (!mHasValue && !other.mHasValue) {
            return true;
        }
        // End iterator vs valid iterator
        if (mHasValue != other.mHasValue) {
            return false;
        }
        // Two valid iterators - compare underlying pixel iterators
        return mPixels == other.mPixels;
    }

    bool operator!=(const ScaledPixelIteratorRGB16& other) const FL_NO_EXCEPT {
        return !(*this == other);
    }
 
private:
    void advance() FL_NO_EXCEPT;
 
    PixelIterator* mPixels;      
    array<u16, 3> mCurrent;      
    bool mHasValue;              
};
 
} // namespace detail

inline pair<detail::ScaledPixelIteratorRGB, detail::ScaledPixelIteratorRGB>
makeScaledPixelRangeRGB(PixelIterator* pixels) FL_NO_EXCEPT {
    return make_pair(
        detail::ScaledPixelIteratorRGB(pixels),
        detail::ScaledPixelIteratorRGB()  // End sentinel
    );
}

inline pair<detail::ScaledPixelIteratorRGBW, detail::ScaledPixelIteratorRGBW>
makeScaledPixelRangeRGBW(PixelIterator* pixels) FL_NO_EXCEPT {
    return make_pair(
        detail::ScaledPixelIteratorRGBW(pixels),
        detail::ScaledPixelIteratorRGBW()  // End sentinel
    );
}

inline pair<detail::ScaledPixelIteratorRGBWW, detail::ScaledPixelIteratorRGBWW>
makeScaledPixelRangeRGBWW(PixelIterator* pixels) FL_NO_EXCEPT {
    return make_pair(
        detail::ScaledPixelIteratorRGBWW(pixels),
        detail::ScaledPixelIteratorRGBWW()  // End sentinel
    );
}
 
#if FASTLED_HD_COLOR_MIXING
inline detail::ScaledPixelIteratorBrightness
makeScaledBrightness(PixelIterator* pixels) FL_NO_EXCEPT {
    return detail::ScaledPixelIteratorBrightness(pixels);
}
#endif  // FASTLED_HD_COLOR_MIXING

inline pair<detail::ScaledPixelIteratorRGB16, detail::ScaledPixelIteratorRGB16>
makeScaledPixelRangeRGB16(PixelIterator* pixels) FL_NO_EXCEPT {
    return make_pair(
        detail::ScaledPixelIteratorRGB16(pixels),
        detail::ScaledPixelIteratorRGB16()  // End sentinel
    );
}
 
// NOTE: For APA102 HD mode, the chipset-specific gamma correction (five_bit_hd_gamma_bitshift)
// needs to be applied. Since this is chipset-specific and not a general iterator adapter concern,
// the APA102 controller applies it inline in the showPixelsGammaBitShift() method.
// The controller uses getRawPixelData() to get raw RGB, applies gamma with loadRGBScaleAndBrightness(),
// then uses loadAndScaleRGB() to get wire-ordered output.
 
} // namespace fl
 
// ===========================================================================
// Implementation of adapter advance() methods
// ===========================================================================
// NOTE: These implementations are defined in pixel_iterator.h after the
//       PixelIterator class is fully defined, as they require complete type.