Fast Math Functions

Detailed Description

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^2) - 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

Topics
	Basic Math Operations
	Fast, efficient 8-bit math functions specifically designed for high-performance LED programming.
	Dimming and Brightening Functions
	Functions to dim or brighten data.
	Easing Functions
	Specify the rate of change of a parameter over time.
	Fast Memory Functions for AVR
	Alternatives to memmove, memcpy, and memset that are faster on AVR than standard avr-libc 1.8.
	Fast Random Number Generators
	Fast 8-bit and 16-bit unsigned random number generators.
	Fast Trigonometry Functions
	Fast 8-bit and 16-bit approximations of sin(x) and cos(x).
	Float-to-Fixed and Fixed-to-Float Conversions
	Functions to convert between floating point and fixed point types.
	Linear Interpolation
	Fast linear interpolation functions, such as could be used for Perlin noise, etc.
	Scaling Functions
	Fast, efficient 8-bit scaling functions specifically designed for high-performance LED programming.
	Waveform Beat Generators
	Waveform generators that reset at a given number of "beats per minute" (BPM).
	Waveform Generators
	General purpose wave generator functions.