lib8tion.h

Go to the documentation of this file.

#pragma once
 
#ifndef __INC_LIB8TION_H
#define __INC_LIB8TION_H
 
#include "fl/math/types.h"
#include "fl/stl/compiler_control.h"
 
#include "led_sysdefs.h"
#include "platforms/is_platform.h"
 

 
#include "fl/stl/stdint.h"
#include "fl/math/lib8static.h"
#include "fl/math/math8.h"
#include "fl/math/qfx.h"
#include "fl/math/memmove.h"
#include "platforms/math8_config.h"
#include "fl/math/ease.h"
#include "fl/math/squarewave.h"
#include "fl/math/beat.h"
#include "fl/math/time_functions.h"
#include "fl/stl/chrono.h"
 
 
#if !defined(FL_IS_AVR)
// memmove, memcpy, and memset are defined in lib8tion/memmove.h and fl/stl/cstring.h
#endif // end of !defined(FL_IS_AVR)

 
 
 
 
#include "fl/math/math8.h"
#include "fl/math/scale8.h"
#include "fl/math/random8.h"
#include "fl/math/trig8.h"
 
// Bring types and common math functions into global scope for backward compatibility.
// Only import names that are actually defined in namespace fl (via platforms/ headers).
// Functions defined with LIB8STATIC outside namespace fl (e.g., random8.h) are already global.
//
// On AVR, Arduino's USBAPI.h defines u8/u16/u32 at global scope with potentially
// different underlying types (e.g. unsigned short vs unsigned int for u16).
// Skip those to avoid redeclaration conflicts.
#if !defined(FL_IS_AVR)
using fl::u8;
// On AVR+Arduino, USBAPI.h (included via Arduino.h) already provides a global
// 'typedef unsigned short u16;'. fl::u16 on AVR is 'unsigned int' — same width
// but a different type — so 'using fl::u16;' would conflict. Skip it on AVR and
// let USBAPI.h's typedef provide the global u16 name instead.
#if !defined(FL_IS_AVR) || !defined(ARDUINO)
using fl::u16;
#endif
using fl::u32;
#endif
using fl::u64;
using fl::i8;
using fl::i16;
using fl::i32;
using fl::i64;
// scale8.h (namespace fl)
using fl::scale8;
using fl::scale8_video;
using fl::scale16;
using fl::scale16by8;
using fl::scale8_LEAVING_R1_DIRTY;
using fl::nscale8x3;
using fl::nscale8x3_video;
using fl::scale8_video_LEAVING_R1_DIRTY;
using fl::cleanup_R1;
// trig8.h (namespace fl)
using fl::sin8;
using fl::sin16;
using fl::cos8;
using fl::cos16;
// math8.h (namespace fl)
using fl::qadd8;
using fl::qsub8;
using fl::qadd7;
using fl::qmul8;
using fl::add8;
using fl::add8to16;
using fl::sub8;
using fl::avg8;
using fl::avg16;
using fl::avg8r;
using fl::avg16r;
using fl::avg7;
using fl::avg15;
using fl::mul8;
using fl::abs8;
using fl::blend8;
using fl::mod8;
using fl::addmod8;
using fl::submod8;
using fl::sqrt16;
using fl::sqrt8;
using fl::dim8_raw;
// qfx.h (namespace fl)
using fl::q44;
using fl::q62;
using fl::q88;
using fl::q124;
// squarewave.h (namespace fl)
using fl::squarewave8;
// beat.h (namespace fl)
using fl::beat88;
using fl::beat16;
using fl::beat8;
using fl::beatsin88;
using fl::beatsin16;
using fl::beatsin8;
// time_functions.h (namespace fl)
using fl::seconds16;
using fl::minutes16;
using fl::hours8;
using fl::div1024_32_16;
using fl::bseconds16;

 
 


LIB8STATIC float sfract15ToFloat( sfract15 y)
{
    return y / 32768.0f;
}

LIB8STATIC sfract15 floatToSfract15( float f)
{
    return static_cast<sfract15>(f * 32768.0f);
}

 
 
 
 


LIB8STATIC fl::u8 lerp8by8( fl::u8 a, fl::u8 b, fract8 frac)
{
    fl::u8 result;
    if( b > a) {
        fl::u8 delta = b - a;
        fl::u8 scaled = scale8( delta, frac);
        result = a + scaled;
    } else {
        fl::u8 delta = a - b;
        fl::u8 scaled = scale8( delta, frac);
        result = a - scaled;
    }
    return result;
}

LIB8STATIC fl::u16 lerp16by16( fl::u16 a, fl::u16 b, fract16 frac)
{
    fl::u16 result;
    if( b > a ) {
        fl::u16 delta = b - a;
        fl::u16 scaled = scale16(delta, frac);
        result = a + scaled;
    } else {
        fl::u16 delta = a - b;
        fl::u16 scaled = scale16( delta, frac);
        result = a - scaled;
    }
    return result;
}

LIB8STATIC fl::u16 lerp16by8( fl::u16 a, fl::u16 b, fract8 frac)
{
    fl::u16 result;
    if( b > a) {
        fl::u16 delta = b - a;
        fl::u16 scaled = scale16by8( delta, frac);
        result = a + scaled;
    } else {
        fl::u16 delta = a - b;
        fl::u16 scaled = scale16by8( delta, frac);
        result = a - scaled;
    }
    return result;
}

LIB8STATIC fl::i16 lerp15by8( fl::i16 a, fl::i16 b, fract8 frac)
{
    fl::i16 result;
    if( b > a) {
        fl::u16 delta = b - a;
        fl::u16 scaled = scale16by8( delta, frac);
        result = a + scaled;
    } else {
        fl::u16 delta = a - b;
        fl::u16 scaled = scale16by8( delta, frac);
        result = a - scaled;
    }
    return result;
}

LIB8STATIC fl::i16 lerp15by16( fl::i16 a, fl::i16 b, fract16 frac)
{
    fl::i16 result;
    if( b > a) {
        fl::u16 delta = b - a;
        fl::u16 scaled = scale16( delta, frac);
        result = a + scaled;
    } else {
        fl::u16 delta = a - b;
        fl::u16 scaled = scale16( delta, frac);
        result = a - scaled;
    }
    return result;
}

LIB8STATIC fl::u8 map8( fl::u8 in, fl::u8 rangeStart, fl::u8 rangeEnd)
{
    fl::u8 rangeWidth = rangeEnd - rangeStart;
    fl::u8 out = scale8( in, rangeWidth);
    out += rangeStart;
    return out;
}

 


#if (EASE8_C == 1) || defined(FASTLED_DOXYGEN)
LIB8STATIC fl::u8 ease8InOutQuad(fl::u8 i)
{
    fl::u8 j = i;
    if( j & 0x80 ) {
        j = 255 - j;
    }
    fl::u8 jj  = scale8(  j, j);
    fl::u8 jj2 = jj << 1;
    if( i & 0x80 ) {
        jj2 = 255 - jj2;
    }
    return jj2;
}
 
#elif EASE8_AVRASM == 1
// This AVR asm version of ease8InOutQuad preserves one more
// low-bit of precision than the C version, and is also slightly
// smaller and faster.
LIB8STATIC fl::u8 ease8InOutQuad(fl::u8 val) {
    fl::u8 j=val;
    asm volatile (
      "sbrc %[val], 7 \n"
      "com %[j]       \n"
      "mul %[j], %[j] \n"
      "add r0, %[j]   \n"
      "ldi %[j], 0    \n"
      "adc %[j], r1   \n"
      "lsl r0         \n" // carry = high bit of low byte of mul product
      "rol %[j]       \n" // j = (j * 2) + carry // preserve add'l bit of precision
      "sbrc %[val], 7 \n"
      "com %[j]       \n"
      "clr __zero_reg__   \n"
      : [j] "+&a" (j)
      : [val] "a" (val)
      : "r0", "r1"
      );
    return j;
}
 
#else
#error "No implementation for ease8InOutQuad available."
#endif
 
LIB8STATIC fl::u16 ease16InOutQuad(fl::u16 i)
{
    // This is the legacy version, there is a slightly more accurate version in fl/ease.cpp
    // with fl::easeInOutQuad16. However the difference is minimal.
    //
    // 16-bit quadratic ease-in / ease-out function
    fl::u16 j = i;
    if (j & 0x8000) {
        j = 65535 - j;
    }
    fl::u16 jj = scale16(j, j);
    fl::u16 jj2 = jj << 1;
    if (i & 0x8000) {
        jj2 = 65535 - jj2;
    }
    return jj2;
}
 
LIB8STATIC fl::u16 ease16InOutCubic(fl::u16 i)  {
    // This function produces wrong results, use fl::easeInOutCubic16 instead
    //
    // 16-bit cubic ease-in / ease-out function
    // Equivalent to ease8InOutCubic() but for 16-bit values
    // Formula: 3(x^2) - 2(x^3) applied with proper ease-in-out curve
 
    // Apply the cubic formula directly, similar to the 8-bit version
    // scale16(a, b) computes (a * b) / 65536
    fl::u32 ii = scale16(i, i);   // i^2 scaled to 16-bit
    fl::u32 iii = scale16(ii, i); // i^3 scaled to 16-bit
 
    // Apply cubic formula: 3x^2 - 2x^3
    fl::u32 r1 = (3 * ii) - (2 * iii);
 
    // Clamp result to 16-bit range
    if (r1 > 65535) {
        return 65535;
    }
    return (fl::u16)r1;
}
 

LIB8STATIC fract8 ease8InOutCubic( fract8 i)
{
    fl::u8 ii  = scale8_LEAVING_R1_DIRTY(  i, i);
    fl::u8 iii = scale8_LEAVING_R1_DIRTY( ii, i);
 
    fl::u16 r1 = (3 * (fl::u16)(ii)) - ( 2 * (fl::u16)(iii));
 
    /* the code generated for the above *'s automatically
       cleans up R1, so there's no need to explicitily call
       cleanup_R1(); */
 
    fl::u8 result = r1;
 
    // if we got "256", return 255:
    if( r1 & 0x100 ) {
        result = 255;
    }
    return result;
}
 

#if (EASE8_C == 1) || defined(FASTLED_DOXYGEN)
LIB8STATIC fract8 ease8InOutApprox( fract8 i)
{
    if( i < 64) {
        // start with slope 0.5
        i /= 2;
    } else if( i > (255 - 64)) {
        // end with slope 0.5
        i = 255 - i;
        i /= 2;
        i = 255 - i;
    } else {
        // in the middle, use slope 192/128 = 1.5
        i -= 64;
        i += (i / 2);
        i += 32;
    }
 
    return i;
}
 
#elif EASE8_AVRASM == 1
LIB8STATIC fl::u8 ease8InOutApprox( fract8 i)
{
    // takes around 7 cycles on AVR
    asm volatile (
        "  subi %[i], 64         \n\t"
        "  cpi  %[i], 128        \n\t"
        "  brcc Lshift_%=        \n\t"
 
        // middle case
        "  mov __tmp_reg__, %[i] \n\t"
        "  lsr __tmp_reg__       \n\t"
        "  add %[i], __tmp_reg__ \n\t"
        "  subi %[i], 224        \n\t"
        "  rjmp Ldone_%=         \n\t"
 
        // start or end case
        "Lshift_%=:              \n\t"
        "  lsr %[i]              \n\t"
        "  subi %[i], 96         \n\t"
 
        "Ldone_%=:               \n\t"
 
        : [i] "+a" (i)
        :
        : "r0"
        );
    return i;
}
#else
#error "No implementation for ease8 available."
#endif

 

 

LIB8STATIC fl::u8 triwave8(fl::u8 in)
{
    if( in & 0x80) {
        in = 255 - in;
    }
    fl::u8 out = in << 1;
    return out;
}

LIB8STATIC fl::u8 quadwave8(fl::u8 in)
{
    return ease8InOutQuad( triwave8( in));
}

LIB8STATIC fl::u8 cubicwave8(fl::u8 in)
{
    return ease8InOutCubic( triwave8( in));
}
 
 
// squarewave8 is now in fl/math/squarewave.h (namespace fl),
// brought into global scope via 'using fl::squarewave8' above.


 

 
#if ((defined(ARDUINO) || defined(FL_IS_STM32_F2) || defined(FASTLED_HAS_MILLIS)) && !defined(USE_GET_MILLISECOND_TIMER)) || defined(FASTLED_DOXYGEN)
// Forward declaration of Arduino function 'millis'.
//uint32_t millis();

#define GET_MILLIS fl::millis
#else
fl::u32 get_millisecond_timer();
#define GET_MILLIS get_millisecond_timer
#endif

 

 
 
// Beat generators (beat88, beat16, beat8, beatsin88, beatsin16, beatsin8) are now
// in fl/math/beat.h (namespace fl), brought into global scope via 'using' above.
 
// Time functions (seconds16, minutes16, hours8, div1024_32_16, bseconds16) are now
// in fl/math/time_functions.h (namespace fl), brought into global scope via 'using' above.

#if 1
#define INSTANTIATE_EVERY_N_TIME_PERIODS(NAME,TIMETYPE,TIMEGETTER) \
class NAME {    \
public: \
    TIMETYPE mPrevTrigger;  \
    TIMETYPE mPeriod;   \
    \
    NAME() { reset(); mPeriod = 1; }; \
    NAME(TIMETYPE period) { reset(); setPeriod(period); };    \
    void setPeriod( TIMETYPE period) { mPeriod = period; }; \
    TIMETYPE getTime() { return (TIMETYPE)(TIMEGETTER()); };    \
    TIMETYPE getPeriod() { return mPeriod; };   \
    TIMETYPE getElapsed() { return getTime() - mPrevTrigger; }  \
    TIMETYPE getRemaining() { return mPeriod - getElapsed(); }  \
    TIMETYPE getLastTriggerTime() { return mPrevTrigger; }  \
    bool ready() { \
        bool isReady = (getElapsed() >= mPeriod);   \
        if( isReady ) { reset(); }  \
        return isReady; \
    }   \
    void reset() { mPrevTrigger = getTime(); }; \
    void trigger() { mPrevTrigger = getTime() - mPeriod; }; \
        \
    operator bool() { return ready(); } \
};

 
#if defined(FASTLED_DOXYGEN)
class CEveryNTime {
public:
    TIMETYPE mPrevTrigger;  
    TIMETYPE mPeriod;       

    CEveryNTime() { reset(); mPeriod = 1; };
    CEveryNTime(TIMETYPE period) { reset(); setPeriod(period); };

    void setPeriod( TIMETYPE period) { mPeriod = period; };

    TIMETYPE getTime() { return (TIMETYPE)(TIMEGETTER()); };

    TIMETYPE getPeriod() { return mPeriod; };

    TIMETYPE getElapsed() { return getTime() - mPrevTrigger; }

    TIMETYPE getRemaining() { return mPeriod - getElapsed(); }

    TIMETYPE getLastTriggerTime() { return mPrevTrigger; }

    bool ready() {
        bool isReady = (getElapsed() >= mPeriod);
        if( isReady ) { reset(); }
        return isReady;
    }

    void reset() { mPrevTrigger = getTime(); };

    void trigger() { mPrevTrigger = getTime() - mPeriod; };

    operator bool() { return ready(); }
};
#endif  // FASTLED_DOXYGEN

INSTANTIATE_EVERY_N_TIME_PERIODS(CEveryNMillis,fl::u32,GET_MILLIS);

INSTANTIATE_EVERY_N_TIME_PERIODS(CEveryNSeconds,fl::u16,seconds16);

INSTANTIATE_EVERY_N_TIME_PERIODS(CEveryNBSeconds,fl::u16,bseconds16);

INSTANTIATE_EVERY_N_TIME_PERIODS(CEveryNMinutes,fl::u16,minutes16);

INSTANTIATE_EVERY_N_TIME_PERIODS(CEveryNHours,fl::u8,hours8);

#define CEveryNMilliseconds CEveryNMillis

class CEveryNMillisDynamic {
public:
    fl::u32 mPrevTrigger;
    fl::u32 mPeriod;
 
    CEveryNMillisDynamic(fl::u32 period) : mPeriod(period) { reset(); };
    fl::u32 getTime() { return GET_MILLIS(); };
    fl::u32 getPeriod() const { return mPeriod; };
    fl::u32 getElapsed() { return getTime() - mPrevTrigger; }
    fl::u32 getRemaining() { return getPeriod() - getElapsed(); }
    fl::u32 getLastTriggerTime() { return mPrevTrigger; }
    bool ready() {
        bool isReady = (getElapsed() >= getPeriod());
        if( isReady ) { reset(); }
        return isReady;
    }
    void reset() { mPrevTrigger = getTime(); };
    void trigger() { mPrevTrigger = getTime() - getPeriod(); };
    void setPeriod(fl::u32 period) { mPeriod = period; }
 
    operator bool() { return ready(); }
};

 
 
 
// ————————————————————————————————————————————————
// Random‐interval version of EVERY_N_MILLISECONDS:
// on each trigger, pick the next period randomly in [MIN..MAX].
// ————————————————————————————————————————————————
class CEveryNMillisRandom {
public:
    fl::u32 mPrevTrigger;
    fl::u32 mPeriod;
    fl::u32 mMinPeriod;
    fl::u32 mMaxPeriod;
 
    CEveryNMillisRandom(fl::u32 minPeriod, fl::u32 maxPeriod)
      : mMinPeriod(minPeriod), mMaxPeriod(maxPeriod)
    {
        computeNext();
        reset();
    }
 
    void computeNext() {
        // random16(x) returns [0..x-1], so this yields MIN..MAX
        fl::u32 range = mMaxPeriod - mMinPeriod + 1;
        mPeriod = mMinPeriod + random16(range);
    }
 
    fl::u32 getTime() const { return GET_MILLIS(); }
 
    bool ready() {
        fl::u32 now = getTime();
        if (now - mPrevTrigger >= mPeriod) {
            mPrevTrigger = now;
            computeNext();
            return true;
        }
        return false;
    }
 
    void reset() { mPrevTrigger = getTime(); }
};
 
#else
 
// Under C++11 rules, we would be allowed to use not-external
// -linkage-type symbols as template arguments,
// e.g., LIB8STATIC seconds16, and we'd be able to use these
// templates as shown below.
// However, under C++03 rules, we cannot do that, and thus we
// have to resort to the preprocessor to 'instantiate' 'templates',
// as handled above.
template<typename timeType,timeType (*timeGetter)()>
class CEveryNTimePeriods {
public:
    timeType mPrevTrigger;
    timeType mPeriod;
 
    CEveryNTimePeriods() { reset(); mPeriod = 1; };
    CEveryNTimePeriods(timeType period) { reset(); setPeriod(period); };
    void setPeriod( timeType period) { mPeriod = period; };
    timeType getTime() { return (timeType)(timeGetter()); };
    timeType getPeriod() { return mPeriod; };
    timeType getElapsed() { return getTime() - mPrevTrigger; }
    timeType getRemaining() { return mPeriod - getElapsed(); }
    timeType getLastTriggerTime() { return mPrevTrigger; }
    bool ready() {
        bool isReady = (getElapsed() >= mPeriod);
        if( isReady ) { reset(); }
        return isReady;
    }
    void reset() { mPrevTrigger = getTime(); };
    void trigger() { mPrevTrigger = getTime() - mPeriod; };
 
    operator bool() { return ready(); }
};
typedef CEveryNTimePeriods<fl::u16,seconds16> CEveryNSeconds;
typedef CEveryNTimePeriods<fl::u16,bseconds16> CEveryNBSeconds;
typedef CEveryNTimePeriods<fl::u32,millis> CEveryNMillis;
typedef CEveryNTimePeriods<fl::u16,minutes16> CEveryNMinutes;
typedef CEveryNTimePeriods<fl::u8,hours8> CEveryNHours;
#endif
 


#define CONCAT_HELPER( x, y ) x##y
#define CONCAT_MACRO( x, y ) CONCAT_HELPER( x, y )
 

#define EVERY_N_MILLIS(N) EVERY_N_MILLIS_I(CONCAT_MACRO(PER, __COUNTER__ ),N)

#define EVERY_N_MILLIS_I(NAME,N) static CEveryNMillis NAME(N); if( NAME )
 

#define EVERY_N_SECONDS(N) EVERY_N_SECONDS_I(CONCAT_MACRO(PER, __COUNTER__ ),N)

#define EVERY_N_SECONDS_I(NAME,N) static CEveryNSeconds NAME(N); if( NAME )
 

#define EVERY_N_BSECONDS(N) EVERY_N_BSECONDS_I(CONCAT_MACRO(PER, __COUNTER__ ),N)

#define EVERY_N_BSECONDS_I(NAME,N) static CEveryNBSeconds NAME(N); if( NAME )
 

#define EVERY_N_MINUTES(N) EVERY_N_MINUTES_I(CONCAT_MACRO(PER, __COUNTER__ ),N)

#define EVERY_N_MINUTES_I(NAME,N) static CEveryNMinutes NAME(N); if( NAME )
 

#define EVERY_N_HOURS(N) EVERY_N_HOURS_I(CONCAT_MACRO(PER, __COUNTER__ ),N)

#define EVERY_N_HOURS_I(NAME,N) static CEveryNHours NAME(N); if( NAME )
 

#define EVERY_N_MILLISECONDS(N) EVERY_N_MILLIS(N)
#define EVERY_N_MILLISECONDS_I(NAME,N) EVERY_N_MILLIS_I(NAME,N)

#define EVERY_N_MILLISECONDS_DYNAMIC(PERIOD_FUNC) EVERY_N_MILLISECONDS_DYNAMIC_I(CONCAT_MACRO(__dynamic_millis_timer, __COUNTER__ ), (PERIOD_FUNC))

#define EVERY_N_MILLISECONDS_DYNAMIC_I(NAME, PERIOD_FUNC) \
    static CEveryNMillisDynamic NAME(1); \
    NAME.setPeriod(PERIOD_FUNC); \
    if( NAME )
 
 
#define EVERY_N_MILLISECONDS_RANDOM(MIN, MAX)                                 \
    EVERY_N_MILLISECONDS_RANDOM_I(                                           \
        CONCAT_MACRO(_permRand, __COUNTER__), MIN, MAX)
 
#define EVERY_N_MILLISECONDS_RANDOM_I(NAME, MIN, MAX)                        \
    static CEveryNMillisRandom NAME(MIN, MAX);                               \
    if (NAME.ready())

 
 
// These defines are used to declare hidden or commented symbols for the
// purposes of Doxygen documentation generation. They do not affect your program.
#ifdef FASTLED_DOXYGEN
#define USE_GET_MILLISECOND_TIMER
#endif
 
#endif
 
// Using declarations moved to top of file