FastLED  3.1
Fast math functions

A variety of functions for working with numbers. More...

+ Collaboration diagram for Fast math functions:

Modules

 Basic math operations
 Fast, efficient 8-bit math functions specifically designed for high-performance LED programming.
 
 Fast random number generators
 Fast 8- and 16- bit unsigned random numbers.
 
 Fast trig functions
 Fast 8 and 16-bit approximations of sin(x) and cos(x).
 
 Scaling functions
 Fast, efficient 8-bit scaling functions specifically designed for high-performance LED programming.
 

Classes

union  IEEE754binary32_t
 typedef for IEEE754 "binary32" float type internals More...
 
class  q< T, F, I >
 Template class for represneting fractional ints. More...
 
class  CEveryNTimePeriods< timeType, timeGetter >
 

Typedefs

typedef uint8_t fract8
 ANSI unsigned short _Fract. More...
 
typedef int8_t sfract7
 ANSI: signed short _Fract. More...
 
typedef uint16_t fract16
 ANSI: unsigned _Fract. More...
 
typedef int16_t sfract15
 ANSI: signed _Fract. More...
 
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
 
typedef q< uint8_t, 4, 4 > q44
 A 4.4 integer (4 bits integer, 4 bits fraction)
 
typedef q< uint8_t, 6, 2 > q62
 A 6.2 integer (6 bits integer, 2 bits fraction)
 
typedef q< uint16_t, 8, 8 > q88
 A 8.8 integer (8 bits integer, 8 bits fraction)
 
typedef q< uint16_t, 12, 4 > q124
 A 12.4 integer (12 bits integer, 4 bits fraction)
 
typedef CEveryNTimePeriods< uint16_t, seconds16CEveryNSeconds
 
typedef CEveryNTimePeriods< uint16_t, bseconds16CEveryNBSeconds
 
typedef CEveryNTimePeriods< uint32_t, millis > CEveryNMillis
 
typedef CEveryNTimePeriods< uint16_t, minutes16CEveryNMinutes
 
typedef CEveryNTimePeriods< uint8_t, hours8CEveryNHours
 

Functions

LIB8STATIC float sfract15ToFloat (sfract15 y)
 sfract15ToFloat: conversion from sfract15 fixed point to IEEE754 32-bit float. More...
 
LIB8STATIC sfract15 floatToSfract15 (float f)
 conversion from IEEE754 float in the range (-1,1) to 16-bit fixed point. More...
 
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))
 
LIB8STATIC uint8_t lerp8by8 (uint8_t a, uint8_t b, fract8 frac)
 linear interpolation between two unsigned 8-bit values, with 8-bit fraction
 
LIB8STATIC uint16_t lerp16by16 (uint16_t a, uint16_t b, fract16 frac)
 linear interpolation between two unsigned 16-bit values, with 16-bit fraction
 
LIB8STATIC uint16_t lerp16by8 (uint16_t a, uint16_t b, fract8 frac)
 linear interpolation between two unsigned 16-bit values, with 8-bit fraction
 
LIB8STATIC int16_t lerp15by8 (int16_t a, int16_t b, fract8 frac)
 linear interpolation between two signed 15-bit values, with 8-bit fraction
 
LIB8STATIC int16_t lerp15by16 (int16_t a, int16_t b, fract16 frac)
 linear interpolation between two signed 15-bit values, with 8-bit fraction
 
LIB8STATIC uint8_t map8 (uint8_t in, uint8_t rangeStart, uint8_t rangeEnd)
 map8: map from one full-range 8-bit value into a narrower range of 8-bit values, possibly a range of hues. More...
 
LIB8STATIC uint8_t ease8InOutQuad (uint8_t i)
 ease8InOutQuad: 8-bit quadratic ease-in / ease-out function Takes around 13 cycles on AVR
 
LIB8STATIC fract8 ease8InOutCubic (fract8 i)
 ease8InOutCubic: 8-bit cubic ease-in / ease-out function Takes around 18 cycles on AVR
 
LIB8STATIC fract8 ease8InOutApprox (fract8 i)
 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. More...
 
LIB8STATIC uint8_t triwave8 (uint8_t in)
 triwave8: triangle (sawtooth) wave generator. More...
 
LIB8STATIC uint8_t quadwave8 (uint8_t in)
 quadwave8: quadratic waveform generator. More...
 
LIB8STATIC uint8_t cubicwave8 (uint8_t in)
 cubicwave8: cubic waveform generator. More...
 
LIB8STATIC uint8_t squarewave8 (uint8_t in, uint8_t pulsewidth=128)
 squarewave8: square wave generator. More...
 
uint32_t get_millisecond_timer ()
 
LIB8STATIC uint16_t beat88 (accum88 beats_per_minute_88, uint32_t timebase=0)
 with BPM specified in Q8.8 fixed-point format; e.g. More...
 
LIB8STATIC uint16_t beat16 (accum88 beats_per_minute, uint32_t timebase=0)
 beat16 generates a 16-bit 'sawtooth' wave at a given BPM
 
LIB8STATIC uint8_t beat8 (accum88 beats_per_minute, uint32_t timebase=0)
 beat8 generates an 8-bit 'sawtooth' wave at a given BPM
 
LIB8STATIC uint16_t beatsin88 (accum88 beats_per_minute_88, uint16_t lowest=0, uint16_t highest=65535, uint32_t timebase=0, uint16_t phase_offset=0)
 beatsin88 generates a 16-bit sine wave at a given BPM, that oscillates within a given range. More...
 
LIB8STATIC uint16_t beatsin16 (accum88 beats_per_minute, uint16_t lowest=0, uint16_t highest=65535, uint32_t timebase=0, uint16_t phase_offset=0)
 beatsin16 generates a 16-bit sine wave at a given BPM, that oscillates within a given range. More...
 
LIB8STATIC uint8_t beatsin8 (accum88 beats_per_minute, uint8_t lowest=0, uint8_t highest=255, uint32_t timebase=0, uint8_t phase_offset=0)
 beatsin8 generates an 8-bit sine wave at a given BPM, that oscillates within a given range. More...
 
LIB8STATIC uint16_t seconds16 ()
 Return the current seconds since boot in a 16-bit value. More...
 
LIB8STATIC uint16_t minutes16 ()
 Return the current minutes since boot in a 16-bit value. More...
 
LIB8STATIC uint8_t hours8 ()
 Return the current hours since boot in an 8-bit value. More...
 
LIB8STATIC uint16_t div1024_32_16 (uint32_t in32)
 Helper routine to divide a 32-bit value by 1024, returning only the low 16 bits. More...
 
LIB8STATIC uint16_t bseconds16 ()
 bseconds16 returns the current time-since-boot in "binary seconds", which are actually 1024/1000 of a second long. More...
 
 INSTANTIATE_EVERY_N_TIME_PERIODS (CEveryNMillis, uint32_t, GET_MILLIS)
 
 INSTANTIATE_EVERY_N_TIME_PERIODS (CEveryNSeconds, uint16_t, seconds16)
 
 INSTANTIATE_EVERY_N_TIME_PERIODS (CEveryNBSeconds, uint16_t, bseconds16)
 
 INSTANTIATE_EVERY_N_TIME_PERIODS (CEveryNMinutes, uint16_t, minutes16)
 
 INSTANTIATE_EVERY_N_TIME_PERIODS (CEveryNHours, uint8_t, hours8)
 

Detailed Description

A variety of functions for working with numbers.

Typedef Documentation

typedef uint16_t fract16

ANSI: unsigned _Fract.

range is 0 to 0.99998474121 in steps of 0.00001525878 ANSI: unsigned _Fract

Definition at line 343 of file lib8tion.h.

typedef uint8_t fract8

ANSI unsigned short _Fract.

range is 0 to 0.99609375 in steps of 0.00390625 ANSI: unsigned short _Fract

Definition at line 335 of file lib8tion.h.

typedef int16_t sfract15

ANSI: signed _Fract.

range is -0.99996948242 to 0.99996948242 in steps of 0.00003051757 ANSI: signed _Fract

Definition at line 347 of file lib8tion.h.

typedef int8_t sfract7

ANSI: signed short _Fract.

range is -0.9921875 to 0.9921875 in steps of 0.0078125 ANSI: signed short _Fract

Definition at line 339 of file lib8tion.h.

Function Documentation

LIB8STATIC uint16_t beat88 ( accum88  beats_per_minute_88,
uint32_t  timebase = 0 
)

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.

Definition at line 855 of file lib8tion.h.

LIB8STATIC uint16_t beatsin16 ( accum88  beats_per_minute,
uint16_t  lowest = 0,
uint16_t  highest = 65535,
uint32_t  timebase = 0,
uint16_t  phase_offset = 0 
)

beatsin16 generates a 16-bit sine wave at a given BPM, that oscillates within a given range.

Definition at line 901 of file lib8tion.h.

LIB8STATIC uint8_t beatsin8 ( accum88  beats_per_minute,
uint8_t  lowest = 0,
uint8_t  highest = 255,
uint32_t  timebase = 0,
uint8_t  phase_offset = 0 
)

beatsin8 generates an 8-bit sine wave at a given BPM, that oscillates within a given range.

Definition at line 914 of file lib8tion.h.

LIB8STATIC uint16_t beatsin88 ( accum88  beats_per_minute_88,
uint16_t  lowest = 0,
uint16_t  highest = 65535,
uint32_t  timebase = 0,
uint16_t  phase_offset = 0 
)

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.

Definition at line 888 of file lib8tion.h.

LIB8STATIC uint16_t bseconds16 ( )

bseconds16 returns the current time-since-boot in "binary seconds", which are actually 1024/1000 of a second long.

Definition at line 992 of file lib8tion.h.

LIB8STATIC uint8_t cubicwave8 ( uint8_t  in)

cubicwave8: cubic waveform generator.

Spends visibly more time at the limits than 'sine' does.

Definition at line 712 of file lib8tion.h.

LIB8STATIC uint16_t div1024_32_16 ( uint32_t  in32)

Helper routine to divide a 32-bit value by 1024, returning only the low 16 bits.

You'd think this would be just result = (in32 >> 10) & 0xFFFF; and on ARM, that's what you want and all is well. But on AVR that code turns into a loop that executes a four-byte shift ten times: 40 shifts in all, plus loop overhead. This routine gets exactly the same result with just six shifts (vs 40), and no loop overhead. Used to convert millis to 'binary seconds' aka bseconds: one bsecond == 1024 millis.

Definition at line 967 of file lib8tion.h.

LIB8STATIC uint8_t ease8InOutApprox ( fract8  i)

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.

Definition at line 619 of file lib8tion.h.

LIB8STATIC sfract15 floatToSfract15 ( float  f)

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

Definition at line 414 of file lib8tion.h.

LIB8STATIC uint8_t hours8 ( )

Return the current hours since boot in an 8-bit value.

Used as part of the "every N time-periods" mechanism

Definition at line 948 of file lib8tion.h.

LIB8STATIC uint8_t map8 ( uint8_t  in,
uint8_t  rangeStart,
uint8_t  rangeEnd 
)

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.

Definition at line 557 of file lib8tion.h.

LIB8STATIC uint16_t minutes16 ( )

Return the current minutes since boot in a 16-bit value.

Used as part of the "every N time-periods" mechanism

Definition at line 938 of file lib8tion.h.

LIB8STATIC uint8_t quadwave8 ( uint8_t  in)

quadwave8: quadratic waveform generator.

Spends just a little more time at the limits than 'sine' does.

Definition at line 705 of file lib8tion.h.

LIB8STATIC uint16_t seconds16 ( )

Return the current seconds since boot in a 16-bit value.

Used as part of the "every N time-periods" mechanism

Definition at line 928 of file lib8tion.h.

LIB8STATIC float sfract15ToFloat ( sfract15  y)

sfract15ToFloat: conversion from sfract15 fixed point to IEEE754 32-bit float.

Definition at line 405 of file lib8tion.h.

LIB8STATIC uint8_t squarewave8 ( uint8_t  in,
uint8_t  pulsewidth = 128 
)

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:

1 If pulsewidth is 255, output is always 255.
2 If pulsewidth < 255, then
3  if input < pulsewidth then output is 255
4  if input >= pulsewidth then output is 0

the output looking like:

1 255 +--pulsewidth--+
2  . | |
3  0 0 +--------(256-pulsewidth)--------
Parameters
in
pulsewidth
Returns
square wave output

Definition at line 741 of file lib8tion.h.

LIB8STATIC uint8_t triwave8 ( uint8_t  in)

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.

Definition at line 684 of file lib8tion.h.