summaryrefslogtreecommitdiff
path: root/lib/lib8tion/lib8tion.h
diff options
context:
space:
mode:
Diffstat (limited to 'lib/lib8tion/lib8tion.h')
-rw-r--r--lib/lib8tion/lib8tion.h934
1 files changed, 934 insertions, 0 deletions
diff --git a/lib/lib8tion/lib8tion.h b/lib/lib8tion/lib8tion.h
new file mode 100644
index 0000000000..d93c748e6a
--- /dev/null
+++ b/lib/lib8tion/lib8tion.h
@@ -0,0 +1,934 @@
+#ifndef __INC_LIB8TION_H
+#define __INC_LIB8TION_H
+
+/*
+
+ Fast, efficient 8-bit math functions specifically
+ designed for high-performance LED programming.
+
+ Because of the AVR(Arduino) and ARM assembly language
+ implementations provided, using these functions often
+ results in smaller and faster code than the equivalent
+ program using plain "C" arithmetic and logic.
+
+
+ Included are:
+
+
+ - Saturating unsigned 8-bit add and subtract.
+ Instead of wrapping around if an overflow occurs,
+ these routines just 'clamp' the output at a maxumum
+ of 255, or a minimum of 0. Useful for adding pixel
+ values. E.g., qadd8( 200, 100) = 255.
+
+ qadd8( i, j) == MIN( (i + j), 0xFF )
+ qsub8( i, j) == MAX( (i - j), 0 )
+
+ - Saturating signed 8-bit ("7-bit") add.
+ qadd7( i, j) == MIN( (i + j), 0x7F)
+
+
+ - Scaling (down) of unsigned 8- and 16- bit values.
+ Scaledown value is specified in 1/256ths.
+ scale8( i, sc) == (i * sc) / 256
+ scale16by8( i, sc) == (i * sc) / 256
+
+ Example: scaling a 0-255 value down into a
+ range from 0-99:
+ downscaled = scale8( originalnumber, 100);
+
+ A special version of scale8 is provided for scaling
+ LED brightness values, to make sure that they don't
+ accidentally scale down to total black at low
+ dimming levels, since that would look wrong:
+ scale8_video( i, sc) = ((i * sc) / 256) +? 1
+
+ Example: reducing an LED brightness by a
+ dimming factor:
+ new_bright = scale8_video( orig_bright, dimming);
+
+
+ - Fast 8- and 16- bit unsigned random numbers.
+ Significantly faster than Arduino random(), but
+ also somewhat less random. You can add entropy.
+ random8() == random from 0..255
+ random8( n) == random from 0..(N-1)
+ random8( n, m) == random from N..(M-1)
+
+ random16() == random from 0..65535
+ random16( n) == random from 0..(N-1)
+ random16( n, m) == random from N..(M-1)
+
+ random16_set_seed( k) == seed = k
+ random16_add_entropy( k) == seed += k
+
+
+ - Absolute value of a signed 8-bit value.
+ abs8( i) == abs( i)
+
+
+ - 8-bit math operations which return 8-bit values.
+ These are provided mostly for completeness,
+ not particularly for performance.
+ mul8( i, j) == (i * j) & 0xFF
+ add8( i, j) == (i + j) & 0xFF
+ sub8( i, j) == (i - j) & 0xFF
+
+
+ - Fast 16-bit approximations of sin and cos.
+ Input angle is a uint16_t from 0-65535.
+ Output is a signed int16_t from -32767 to 32767.
+ sin16( x) == sin( (x/32768.0) * pi) * 32767
+ cos16( x) == cos( (x/32768.0) * pi) * 32767
+ Accurate to more than 99% in all cases.
+
+ - Fast 8-bit approximations of sin and cos.
+ Input angle is a uint8_t from 0-255.
+ Output is an UNsigned uint8_t from 0 to 255.
+ sin8( x) == (sin( (x/128.0) * pi) * 128) + 128
+ cos8( x) == (cos( (x/128.0) * pi) * 128) + 128
+ Accurate to within about 2%.
+
+
+ - Fast 8-bit "easing in/out" function.
+ ease8InOutCubic(x) == 3(x^i) - 2(x^3)
+ ease8InOutApprox(x) ==
+ faster, rougher, approximation of cubic easing
+ ease8InOutQuad(x) == quadratic (vs cubic) easing
+
+ - Cubic, Quadratic, and Triangle wave functions.
+ Input is a uint8_t representing phase withing the wave,
+ similar to how sin8 takes an angle 'theta'.
+ Output is a uint8_t representing the amplitude of
+ the wave at that point.
+ cubicwave8( x)
+ quadwave8( x)
+ triwave8( x)
+
+ - Square root for 16-bit integers. About three times
+ faster and five times smaller than Arduino's built-in
+ generic 32-bit sqrt routine.
+ sqrt16( uint16_t x ) == sqrt( x)
+
+ - Dimming and brightening functions for 8-bit
+ light values.
+ dim8_video( x) == scale8_video( x, x)
+ dim8_raw( x) == scale8( x, x)
+ dim8_lin( x) == (x<128) ? ((x+1)/2) : scale8(x,x)
+ brighten8_video( x) == 255 - dim8_video( 255 - x)
+ brighten8_raw( x) == 255 - dim8_raw( 255 - x)
+ brighten8_lin( x) == 255 - dim8_lin( 255 - x)
+ The dimming functions in particular are suitable
+ for making LED light output appear more 'linear'.
+
+
+ - Linear interpolation between two values, with the
+ fraction between them expressed as an 8- or 16-bit
+ fixed point fraction (fract8 or fract16).
+ lerp8by8( fromU8, toU8, fract8 )
+ lerp16by8( fromU16, toU16, fract8 )
+ lerp15by8( fromS16, toS16, fract8 )
+ == from + (( to - from ) * fract8) / 256)
+ lerp16by16( fromU16, toU16, fract16 )
+ == from + (( to - from ) * fract16) / 65536)
+ map8( in, rangeStart, rangeEnd)
+ == map( in, 0, 255, rangeStart, rangeEnd);
+
+ - Optimized memmove, memcpy, and memset, that are
+ faster than standard avr-libc 1.8.
+ memmove8( dest, src, bytecount)
+ memcpy8( dest, src, bytecount)
+ memset8( buf, value, bytecount)
+
+ - Beat generators which return sine or sawtooth
+ waves in a specified number of Beats Per Minute.
+ Sine wave beat generators can specify a low and
+ high range for the output. Sawtooth wave beat
+ generators always range 0-255 or 0-65535.
+ beatsin8( BPM, low8, high8)
+ = (sine(beatphase) * (high8-low8)) + low8
+ beatsin16( BPM, low16, high16)
+ = (sine(beatphase) * (high16-low16)) + low16
+ beatsin88( BPM88, low16, high16)
+ = (sine(beatphase) * (high16-low16)) + low16
+ beat8( BPM) = 8-bit repeating sawtooth wave
+ beat16( BPM) = 16-bit repeating sawtooth wave
+ beat88( BPM88) = 16-bit repeating sawtooth wave
+ BPM is beats per minute in either simple form
+ e.g. 120, or Q8.8 fixed-point form.
+ BPM88 is beats per minute in ONLY Q8.8 fixed-point
+ form.
+
+Lib8tion is pronounced like 'libation': lie-BAY-shun
+
+*/
+
+
+
+#include <stdint.h>
+
+#define LIB8STATIC __attribute__ ((unused)) static inline
+#define LIB8STATIC_ALWAYS_INLINE __attribute__ ((always_inline)) static inline
+
+#if !defined(__AVR__)
+#include <string.h>
+// for memmove, memcpy, and memset if not defined here
+#endif
+
+#if defined(__arm__)
+
+#if defined(FASTLED_TEENSY3)
+// Can use Cortex M4 DSP instructions
+#define QADD8_C 0
+#define QADD7_C 0
+#define QADD8_ARM_DSP_ASM 1
+#define QADD7_ARM_DSP_ASM 1
+#else
+// Generic ARM
+#define QADD8_C 1
+#define QADD7_C 1
+#endif
+
+#define QSUB8_C 1
+#define SCALE8_C 1
+#define SCALE16BY8_C 1
+#define SCALE16_C 1
+#define ABS8_C 1
+#define MUL8_C 1
+#define QMUL8_C 1
+#define ADD8_C 1
+#define SUB8_C 1
+#define EASE8_C 1
+#define AVG8_C 1
+#define AVG7_C 1
+#define AVG16_C 1
+#define AVG15_C 1
+#define BLEND8_C 1
+
+
+#elif defined(__AVR__)
+
+// AVR ATmega and friends Arduino
+
+#define QADD8_C 0
+#define QADD7_C 0
+#define QSUB8_C 0
+#define ABS8_C 0
+#define ADD8_C 0
+#define SUB8_C 0
+#define AVG8_C 0
+#define AVG7_C 0
+#define AVG16_C 0
+#define AVG15_C 0
+
+#define QADD8_AVRASM 1
+#define QADD7_AVRASM 1
+#define QSUB8_AVRASM 1
+#define ABS8_AVRASM 1
+#define ADD8_AVRASM 1
+#define SUB8_AVRASM 1
+#define AVG8_AVRASM 1
+#define AVG7_AVRASM 1
+#define AVG16_AVRASM 1
+#define AVG15_AVRASM 1
+
+// Note: these require hardware MUL instruction
+// -- sorry, ATtiny!
+#if !defined(LIB8_ATTINY)
+#define SCALE8_C 0
+#define SCALE16BY8_C 0
+#define SCALE16_C 0
+#define MUL8_C 0
+#define QMUL8_C 0
+#define EASE8_C 0
+#define BLEND8_C 0
+#define SCALE8_AVRASM 1
+#define SCALE16BY8_AVRASM 1
+#define SCALE16_AVRASM 1
+#define MUL8_AVRASM 1
+#define QMUL8_AVRASM 1
+#define EASE8_AVRASM 1
+#define CLEANUP_R1_AVRASM 1
+#define BLEND8_AVRASM 1
+#else
+// On ATtiny, we just use C implementations
+#define SCALE8_C 1
+#define SCALE16BY8_C 1
+#define SCALE16_C 1
+#define MUL8_C 1
+#define QMUL8_C 1
+#define EASE8_C 1
+#define BLEND8_C 1
+#define SCALE8_AVRASM 0
+#define SCALE16BY8_AVRASM 0
+#define SCALE16_AVRASM 0
+#define MUL8_AVRASM 0
+#define QMUL8_AVRASM 0
+#define EASE8_AVRASM 0
+#define BLEND8_AVRASM 0
+#endif
+
+#else
+
+// unspecified architecture, so
+// no ASM, everything in C
+#define QADD8_C 1
+#define QADD7_C 1
+#define QSUB8_C 1
+#define SCALE8_C 1
+#define SCALE16BY8_C 1
+#define SCALE16_C 1
+#define ABS8_C 1
+#define MUL8_C 1
+#define QMUL8_C 1
+#define ADD8_C 1
+#define SUB8_C 1
+#define EASE8_C 1
+#define AVG8_C 1
+#define AVG7_C 1
+#define AVG16_C 1
+#define AVG15_C 1
+#define BLEND8_C 1
+
+#endif
+
+///@defgroup lib8tion Fast math functions
+///A variety of functions for working with numbers.
+///@{
+
+
+///////////////////////////////////////////////////////////////////////
+//
+// typdefs for fixed-point fractional types.
+//
+// sfract7 should be interpreted as signed 128ths.
+// fract8 should be interpreted as unsigned 256ths.
+// sfract15 should be interpreted as signed 32768ths.
+// fract16 should be interpreted as unsigned 65536ths.
+//
+// Example: if a fract8 has the value "64", that should be interpreted
+// as 64/256ths, or one-quarter.
+//
+//
+// fract8 range is 0 to 0.99609375
+// in steps of 0.00390625
+//
+// sfract7 range is -0.9921875 to 0.9921875
+// in steps of 0.0078125
+//
+// fract16 range is 0 to 0.99998474121
+// in steps of 0.00001525878
+//
+// sfract15 range is -0.99996948242 to 0.99996948242
+// in steps of 0.00003051757
+//
+
+/// ANSI unsigned short _Fract. range is 0 to 0.99609375
+/// in steps of 0.00390625
+typedef uint8_t fract8; ///< ANSI: unsigned short _Fract
+
+/// ANSI: signed short _Fract. range is -0.9921875 to 0.9921875
+/// in steps of 0.0078125
+typedef int8_t sfract7; ///< ANSI: signed short _Fract
+
+/// ANSI: unsigned _Fract. range is 0 to 0.99998474121
+/// in steps of 0.00001525878
+typedef uint16_t fract16; ///< ANSI: unsigned _Fract
+
+/// ANSI: signed _Fract. range is -0.99996948242 to 0.99996948242
+/// in steps of 0.00003051757
+typedef int16_t sfract15; ///< ANSI: signed _Fract
+
+
+// accumXY types should be interpreted as X bits of integer,
+// and Y bits of fraction.
+// E.g., accum88 has 8 bits of int, 8 bits of fraction
+
+typedef uint16_t accum88; ///< ANSI: unsigned short _Accum. 8 bits int, 8 bits fraction
+typedef int16_t saccum78; ///< ANSI: signed short _Accum. 7 bits int, 8 bits fraction
+typedef uint32_t accum1616;///< ANSI: signed _Accum. 16 bits int, 16 bits fraction
+typedef int32_t saccum1516;///< ANSI: signed _Accum. 15 bits int, 16 bits fraction
+typedef uint16_t accum124; ///< no direct ANSI counterpart. 12 bits int, 4 bits fraction
+typedef int32_t saccum114;///< no direct ANSI counterpart. 1 bit int, 14 bits fraction
+
+
+
+#include "math8.h"
+#include "scale8.h"
+#include "random8.h"
+#include "trig8.h"
+
+///////////////////////////////////////////////////////////////////////
+
+
+
+
+
+
+
+///////////////////////////////////////////////////////////////////////
+//
+// float-to-fixed and fixed-to-float conversions
+//
+// Note that anything involving a 'float' on AVR will be slower.
+
+/// sfract15ToFloat: conversion from sfract15 fixed point to
+/// IEEE754 32-bit float.
+LIB8STATIC float sfract15ToFloat( sfract15 y)
+{
+ return y / 32768.0;
+}
+
+/// conversion from IEEE754 float in the range (-1,1)
+/// to 16-bit fixed point. Note that the extremes of
+/// one and negative one are NOT representable. The
+/// representable range is basically
+LIB8STATIC sfract15 floatToSfract15( float f)
+{
+ return f * 32768.0;
+}
+
+
+
+///////////////////////////////////////////////////////////////////////
+//
+// memmove8, memcpy8, and memset8:
+// alternatives to memmove, memcpy, and memset that are
+// faster on AVR than standard avr-libc 1.8
+
+#if defined(__AVR__)
+void * memmove8( void * dst, const void * src, uint16_t num );
+void * memcpy8 ( void * dst, const void * src, uint16_t num ) __attribute__ ((noinline));
+void * memset8 ( void * ptr, uint8_t value, uint16_t num ) __attribute__ ((noinline)) ;
+#else
+// on non-AVR platforms, these names just call standard libc.
+#define memmove8 memmove
+#define memcpy8 memcpy
+#define memset8 memset
+#endif
+
+
+///////////////////////////////////////////////////////////////////////
+//
+// linear interpolation, such as could be used for Perlin noise, etc.
+//
+
+// A note on the structure of the lerp functions:
+// The cases for b>a and b<=a are handled separately for
+// speed: without knowing the relative order of a and b,
+// the value (a-b) might be overflow the width of a or b,
+// and have to be promoted to a wider, slower type.
+// To avoid that, we separate the two cases, and are able
+// to do all the math in the same width as the arguments,
+// which is much faster and smaller on AVR.
+
+/// linear interpolation between two unsigned 8-bit values,
+/// with 8-bit fraction
+LIB8STATIC uint8_t lerp8by8( uint8_t a, uint8_t b, fract8 frac)
+{
+ uint8_t result;
+ if( b > a) {
+ uint8_t delta = b - a;
+ uint8_t scaled = scale8( delta, frac);
+ result = a + scaled;
+ } else {
+ uint8_t delta = a - b;
+ uint8_t scaled = scale8( delta, frac);
+ result = a - scaled;
+ }
+ return result;
+}
+
+/// linear interpolation between two unsigned 16-bit values,
+/// with 16-bit fraction
+LIB8STATIC uint16_t lerp16by16( uint16_t a, uint16_t b, fract16 frac)
+{
+ uint16_t result;
+ if( b > a ) {
+ uint16_t delta = b - a;
+ uint16_t scaled = scale16(delta, frac);
+ result = a + scaled;
+ } else {
+ uint16_t delta = a - b;
+ uint16_t scaled = scale16( delta, frac);
+ result = a - scaled;
+ }
+ return result;
+}
+
+/// linear interpolation between two unsigned 16-bit values,
+/// with 8-bit fraction
+LIB8STATIC uint16_t lerp16by8( uint16_t a, uint16_t b, fract8 frac)
+{
+ uint16_t result;
+ if( b > a) {
+ uint16_t delta = b - a;
+ uint16_t scaled = scale16by8( delta, frac);
+ result = a + scaled;
+ } else {
+ uint16_t delta = a - b;
+ uint16_t scaled = scale16by8( delta, frac);
+ result = a - scaled;
+ }
+ return result;
+}
+
+/// linear interpolation between two signed 15-bit values,
+/// with 8-bit fraction
+LIB8STATIC int16_t lerp15by8( int16_t a, int16_t b, fract8 frac)
+{
+ int16_t result;
+ if( b > a) {
+ uint16_t delta = b - a;
+ uint16_t scaled = scale16by8( delta, frac);
+ result = a + scaled;
+ } else {
+ uint16_t delta = a - b;
+ uint16_t scaled = scale16by8( delta, frac);
+ result = a - scaled;
+ }
+ return result;
+}
+
+/// linear interpolation between two signed 15-bit values,
+/// with 8-bit fraction
+LIB8STATIC int16_t lerp15by16( int16_t a, int16_t b, fract16 frac)
+{
+ int16_t result;
+ if( b > a) {
+ uint16_t delta = b - a;
+ uint16_t scaled = scale16( delta, frac);
+ result = a + scaled;
+ } else {
+ uint16_t delta = a - b;
+ uint16_t scaled = scale16( delta, frac);
+ result = a - scaled;
+ }
+ return result;
+}
+
+/// map8: map from one full-range 8-bit value into a narrower
+/// range of 8-bit values, possibly a range of hues.
+///
+/// E.g. map myValue into a hue in the range blue..purple..pink..red
+/// hue = map8( myValue, HUE_BLUE, HUE_RED);
+///
+/// Combines nicely with the waveform functions (like sin8, etc)
+/// to produce continuous hue gradients back and forth:
+///
+/// hue = map8( sin8( myValue), HUE_BLUE, HUE_RED);
+///
+/// Mathematically simiar to lerp8by8, but arguments are more
+/// like Arduino's "map"; this function is similar to
+///
+/// map( in, 0, 255, rangeStart, rangeEnd)
+///
+/// but faster and specifically designed for 8-bit values.
+LIB8STATIC uint8_t map8( uint8_t in, uint8_t rangeStart, uint8_t rangeEnd)
+{
+ uint8_t rangeWidth = rangeEnd - rangeStart;
+ uint8_t out = scale8( in, rangeWidth);
+ out += rangeStart;
+ return out;
+}
+
+
+///////////////////////////////////////////////////////////////////////
+//
+// easing functions; see http://easings.net
+//
+
+/// ease8InOutQuad: 8-bit quadratic ease-in / ease-out function
+/// Takes around 13 cycles on AVR
+#if EASE8_C == 1
+LIB8STATIC uint8_t ease8InOutQuad( uint8_t i)
+{
+ uint8_t j = i;
+ if( j & 0x80 ) {
+ j = 255 - j;
+ }
+ uint8_t jj = scale8( j, j);
+ uint8_t 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 uint8_t ease8InOutQuad(uint8_t val) {
+ uint8_t 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
+
+/// ease16InOutQuad: 16-bit quadratic ease-in / ease-out function
+// C implementation at this point
+LIB8STATIC uint16_t ease16InOutQuad( uint16_t i)
+{
+ uint16_t j = i;
+ if( j & 0x8000 ) {
+ j = 65535 - j;
+ }
+ uint16_t jj = scale16( j, j);
+ uint16_t jj2 = jj << 1;
+ if( i & 0x8000 ) {
+ jj2 = 65535 - jj2;
+ }
+ return jj2;
+}
+
+
+/// ease8InOutCubic: 8-bit cubic ease-in / ease-out function
+/// Takes around 18 cycles on AVR
+LIB8STATIC fract8 ease8InOutCubic( fract8 i)
+{
+ uint8_t ii = scale8_LEAVING_R1_DIRTY( i, i);
+ uint8_t iii = scale8_LEAVING_R1_DIRTY( ii, i);
+
+ uint16_t r1 = (3 * (uint16_t)(ii)) - ( 2 * (uint16_t)(iii));
+
+ /* the code generated for the above *'s automatically
+ cleans up R1, so there's no need to explicitily call
+ cleanup_R1(); */
+
+ uint8_t result = r1;
+
+ // if we got "256", return 255:
+ if( r1 & 0x100 ) {
+ result = 255;
+ }
+ return result;
+}
+
+/// ease8InOutApprox: fast, rough 8-bit ease-in/ease-out function
+/// shaped approximately like 'ease8InOutCubic',
+/// it's never off by more than a couple of percent
+/// from the actual cubic S-curve, and it executes
+/// more than twice as fast. Use when the cycles
+/// are more important than visual smoothness.
+/// Asm version takes around 7 cycles on AVR.
+
+#if EASE8_C == 1
+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 uint8_t 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", "r1"
+ );
+ return i;
+}
+#else
+#error "No implementation for ease8 available."
+#endif
+
+
+
+/// triwave8: triangle (sawtooth) wave generator. Useful for
+/// turning a one-byte ever-increasing value into a
+/// one-byte value that oscillates up and down.
+///
+/// input output
+/// 0..127 0..254 (positive slope)
+/// 128..255 254..0 (negative slope)
+///
+/// On AVR this function takes just three cycles.
+///
+LIB8STATIC uint8_t triwave8(uint8_t in)
+{
+ if( in & 0x80) {
+ in = 255 - in;
+ }
+ uint8_t out = in << 1;
+ return out;
+}
+
+
+// quadwave8 and cubicwave8: S-shaped wave generators (like 'sine').
+// Useful for turning a one-byte 'counter' value into a
+// one-byte oscillating value that moves smoothly up and down,
+// with an 'acceleration' and 'deceleration' curve.
+//
+// These are even faster than 'sin8', and have
+// slightly different curve shapes.
+//
+
+/// quadwave8: quadratic waveform generator. Spends just a little more
+/// time at the limits than 'sine' does.
+LIB8STATIC uint8_t quadwave8(uint8_t in)
+{
+ return ease8InOutQuad( triwave8( in));
+}
+
+/// cubicwave8: cubic waveform generator. Spends visibly more time
+/// at the limits than 'sine' does.
+LIB8STATIC uint8_t cubicwave8(uint8_t in)
+{
+ return ease8InOutCubic( triwave8( in));
+}
+
+/// squarewave8: square wave generator. Useful for
+/// turning a one-byte ever-increasing value
+/// into a one-byte value that is either 0 or 255.
+/// The width of the output 'pulse' is
+/// determined by the pulsewidth argument:
+///
+///~~~
+/// If pulsewidth is 255, output is always 255.
+/// If pulsewidth < 255, then
+/// if input < pulsewidth then output is 255
+/// if input >= pulsewidth then output is 0
+///~~~
+///
+/// the output looking like:
+///
+///~~~
+/// 255 +--pulsewidth--+
+/// . | |
+/// 0 0 +--------(256-pulsewidth)--------
+///~~~
+///
+/// @param in
+/// @param pulsewidth
+/// @returns square wave output
+LIB8STATIC uint8_t squarewave8( uint8_t in, uint8_t pulsewidth)
+{
+ if( in < pulsewidth || (pulsewidth == 255)) {
+ return 255;
+ } else {
+ return 0;
+ }
+}
+
+
+// Beat generators - These functions produce waves at a given
+// number of 'beats per minute'. Internally, they use
+// the Arduino function 'millis' to track elapsed time.
+// Accuracy is a bit better than one part in a thousand.
+//
+// beat8( BPM ) returns an 8-bit value that cycles 'BPM' times
+// per minute, rising from 0 to 255, resetting to zero,
+// rising up again, etc.. The output of this function
+// is suitable for feeding directly into sin8, and cos8,
+// triwave8, quadwave8, and cubicwave8.
+// beat16( BPM ) returns a 16-bit value that cycles 'BPM' times
+// per minute, rising from 0 to 65535, resetting to zero,
+// rising up again, etc. The output of this function is
+// suitable for feeding directly into sin16 and cos16.
+// beat88( BPM88) is the same as beat16, except that the BPM88 argument
+// MUST be in Q8.8 fixed point format, e.g. 120BPM must
+// be specified as 120*256 = 30720.
+// beatsin8( BPM, uint8_t low, uint8_t high) returns an 8-bit value that
+// rises and falls in a sine wave, 'BPM' times per minute,
+// between the values of 'low' and 'high'.
+// beatsin16( BPM, uint16_t low, uint16_t high) returns a 16-bit value
+// that rises and falls in a sine wave, 'BPM' times per
+// minute, between the values of 'low' and 'high'.
+// beatsin88( BPM88, ...) is the same as beatsin16, except that the
+// BPM88 argument MUST be in Q8.8 fixed point format,
+// e.g. 120BPM must be specified as 120*256 = 30720.
+//
+// BPM can be supplied two ways. The simpler way of specifying BPM is as
+// a simple 8-bit integer from 1-255, (e.g., "120").
+// The more sophisticated way of specifying BPM allows for fractional
+// "Q8.8" fixed point number (an 'accum88') with an 8-bit integer part and
+// an 8-bit fractional part. The easiest way to construct this is to multiply
+// a floating point BPM value (e.g. 120.3) by 256, (e.g. resulting in 30796
+// in this case), and pass that as the 16-bit BPM argument.
+// "BPM88" MUST always be specified in Q8.8 format.
+//
+// Originally designed to make an entire animation project pulse with brightness.
+// For that effect, add this line just above your existing call to "FastLED.show()":
+//
+// uint8_t bright = beatsin8( 60 /*BPM*/, 192 /*dimmest*/, 255 /*brightest*/ ));
+// FastLED.setBrightness( bright );
+// FastLED.show();
+//
+// The entire animation will now pulse between brightness 192 and 255 once per second.
+
+
+// The beat generators need access to a millisecond counter.
+// On Arduino, this is "millis()". On other platforms, you'll
+// need to provide a function with this signature:
+// uint32_t get_millisecond_timer();
+// that provides similar functionality.
+// You can also force use of the get_millisecond_timer function
+// by #defining USE_GET_MILLISECOND_TIMER.
+#if (defined(ARDUINO) || defined(SPARK) || defined(FASTLED_HAS_MILLIS)) && !defined(USE_GET_MILLISECOND_TIMER)
+// Forward declaration of Arduino function 'millis'.
+//uint32_t millis();
+#define GET_MILLIS millis
+#else
+uint32_t get_millisecond_timer(void);
+#define GET_MILLIS get_millisecond_timer
+#endif
+
+// beat16 generates a 16-bit 'sawtooth' wave at a given BPM,
+/// with BPM specified in Q8.8 fixed-point format; e.g.
+/// for this function, 120 BPM MUST BE specified as
+/// 120*256 = 30720.
+/// If you just want to specify "120", use beat16 or beat8.
+LIB8STATIC uint16_t beat88( accum88 beats_per_minute_88, uint32_t timebase)
+{
+ // BPM is 'beats per minute', or 'beats per 60000ms'.
+ // To avoid using the (slower) division operator, we
+ // want to convert 'beats per 60000ms' to 'beats per 65536ms',
+ // and then use a simple, fast bit-shift to divide by 65536.
+ //
+ // The ratio 65536:60000 is 279.620266667:256; we'll call it 280:256.
+ // The conversion is accurate to about 0.05%, more or less,
+ // e.g. if you ask for "120 BPM", you'll get about "119.93".
+ return (((GET_MILLIS()) - timebase) * beats_per_minute_88 * 280) >> 16;
+}
+
+/// beat16 generates a 16-bit 'sawtooth' wave at a given BPM
+LIB8STATIC uint16_t beat16( accum88 beats_per_minute, uint32_t timebase)
+{
+ // Convert simple 8-bit BPM's to full Q8.8 accum88's if needed
+ if( beats_per_minute < 256) beats_per_minute <<= 8;
+ return beat88(beats_per_minute, timebase);
+}
+
+/// beat8 generates an 8-bit 'sawtooth' wave at a given BPM
+LIB8STATIC uint8_t beat8( accum88 beats_per_minute, uint32_t timebase)
+{
+ return beat16( beats_per_minute, timebase) >> 8;
+}
+
+/// beatsin88 generates a 16-bit sine wave at a given BPM,
+/// that oscillates within a given range.
+/// For this function, BPM MUST BE SPECIFIED as
+/// a Q8.8 fixed-point value; e.g. 120BPM must be
+/// specified as 120*256 = 30720.
+/// If you just want to specify "120", use beatsin16 or beatsin8.
+LIB8STATIC uint16_t beatsin88( accum88 beats_per_minute_88, uint16_t lowest, uint16_t highest, uint32_t timebase, uint16_t phase_offset)
+{
+ uint16_t beat = beat88( beats_per_minute_88, timebase);
+ uint16_t beatsin = (sin16( beat + phase_offset) + 32768);
+ uint16_t rangewidth = highest - lowest;
+ uint16_t scaledbeat = scale16( beatsin, rangewidth);
+ uint16_t result = lowest + scaledbeat;
+ return result;
+}
+
+/// beatsin16 generates a 16-bit sine wave at a given BPM,
+/// that oscillates within a given range.
+LIB8STATIC uint16_t beatsin16(accum88 beats_per_minute, uint16_t lowest, uint16_t highest, uint32_t timebase, uint16_t phase_offset)
+{
+ uint16_t beat = beat16( beats_per_minute, timebase);
+ uint16_t beatsin = (sin16( beat + phase_offset) + 32768);
+ uint16_t rangewidth = highest - lowest;
+ uint16_t scaledbeat = scale16( beatsin, rangewidth);
+ uint16_t result = lowest + scaledbeat;
+ return result;
+}
+
+/// beatsin8 generates an 8-bit sine wave at a given BPM,
+/// that oscillates within a given range.
+LIB8STATIC uint8_t beatsin8( accum88 beats_per_minute, uint8_t lowest, uint8_t highest, uint32_t timebase, uint8_t phase_offset)
+{
+ uint8_t beat = beat8( beats_per_minute, timebase);
+ uint8_t beatsin = sin8( beat + phase_offset);
+ uint8_t rangewidth = highest - lowest;
+ uint8_t scaledbeat = scale8( beatsin, rangewidth);
+ uint8_t result = lowest + scaledbeat;
+ return result;
+}
+
+
+/// Return the current seconds since boot in a 16-bit value. Used as part of the
+/// "every N time-periods" mechanism
+LIB8STATIC uint16_t seconds16(void)
+{
+ uint32_t ms = GET_MILLIS();
+ uint16_t s16;
+ s16 = ms / 1000;
+ return s16;
+}
+
+/// Return the current minutes since boot in a 16-bit value. Used as part of the
+/// "every N time-periods" mechanism
+LIB8STATIC uint16_t minutes16(void)
+{
+ uint32_t ms = GET_MILLIS();
+ uint16_t m16;
+ m16 = (ms / (60000L)) & 0xFFFF;
+ return m16;
+}
+
+/// Return the current hours since boot in an 8-bit value. Used as part of the
+/// "every N time-periods" mechanism
+LIB8STATIC uint8_t hours8(void)
+{
+ uint32_t ms = GET_MILLIS();
+ uint8_t h8;
+ h8 = (ms / (3600000L)) & 0xFF;
+ return h8;
+}
+
+///@}
+
+#endif