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.

LIB8STATIC_ALWAYS_INLINE uint8_t	qadd8 (uint8_t i, uint8_t j)
	Add one byte to another, saturating at 0xFF.

LIB8STATIC_ALWAYS_INLINE int8_t	qadd7 (int8_t i, int8_t j)
	Add one byte to another, saturating at 0x7F and -0x80.

LIB8STATIC_ALWAYS_INLINE uint8_t	qsub8 (uint8_t i, uint8_t j)
	Subtract one byte from another, saturating at 0x00.

LIB8STATIC_ALWAYS_INLINE uint8_t	add8 (uint8_t i, uint8_t j)
	Add one byte to another, with 8-bit result.

LIB8STATIC_ALWAYS_INLINE uint16_t	add8to16 (uint8_t i, uint16_t j)
	Add one byte to two bytes, with 16-bit result.

LIB8STATIC_ALWAYS_INLINE uint8_t	sub8 (uint8_t i, uint8_t j)
	Subtract one byte from another, 8-bit result.

LIB8STATIC_ALWAYS_INLINE uint8_t	avg8 (uint8_t i, uint8_t j)
	Calculate an integer average of two unsigned 8-bit integer values (uint8_t), rounded down.

LIB8STATIC_ALWAYS_INLINE uint16_t	avg16 (uint16_t i, uint16_t j)
	Calculate an integer average of two unsigned 16-bit integer values (uint16_t), rounded down.

LIB8STATIC_ALWAYS_INLINE uint8_t	avg8r (uint8_t i, uint8_t j)
	Calculate an integer average of two unsigned 8-bit integer values (uint8_t), rounded up.

LIB8STATIC_ALWAYS_INLINE uint16_t	avg16r (uint16_t i, uint16_t j)
	Calculate an integer average of two unsigned 16-bit integer values (uint16_t), rounded up.

LIB8STATIC_ALWAYS_INLINE int8_t	avg7 (int8_t i, int8_t j)
	Calculate an integer average of two signed 7-bit integers (int8_t).

LIB8STATIC_ALWAYS_INLINE int16_t	avg15 (int16_t i, int16_t j)
	Calculate an integer average of two signed 15-bit integers (int16_t).

LIB8STATIC_ALWAYS_INLINE uint8_t	mod8 (uint8_t a, uint8_t m)
	Calculate the remainder of one unsigned 8-bit value divided by anoter, aka A % M.

LIB8STATIC uint8_t	addmod8 (uint8_t a, uint8_t b, uint8_t m)
	Add two numbers, and calculate the modulo of the sum and a third number, M.

LIB8STATIC uint8_t	submod8 (uint8_t a, uint8_t b, uint8_t m)
	Subtract two numbers, and calculate the modulo of the difference and a third number, M.

LIB8STATIC_ALWAYS_INLINE uint8_t	mul8 (uint8_t i, uint8_t j)
	8x8 bit multiplication, with 8-bit result.

LIB8STATIC_ALWAYS_INLINE uint8_t	qmul8 (uint8_t i, uint8_t j)
	8x8 bit multiplication with 8-bit result, saturating at 0xFF.

LIB8STATIC_ALWAYS_INLINE int8_t	abs8 (int8_t i)
	Take the absolute value of a signed 8-bit uint8_t.

LIB8STATIC uint8_t	sqrt16 (uint16_t x)
	Square root for 16-bit integers.

LIB8STATIC_ALWAYS_INLINE uint8_t	sqrt8 (uint8_t x)

LIB8STATIC uint8_t	blend8 (uint8_t a, uint8_t b, uint8_t amountOfB)
	Blend a variable proportion (0-255) of one byte to another.

Function Documentation

◆ abs8()

LIB8STATIC_ALWAYS_INLINE int8_t abs8 ( int8_t i )

Take the absolute value of a signed 8-bit uint8_t.

Definition at line 500 of file math8.h.

◆ add8()

LIB8STATIC_ALWAYS_INLINE uint8_t add8	(	uint8_t	i,
		uint8_t	j )

Add one byte to another, with 8-bit result.

Note: This does not saturate and may overflow!

Parameters

i	first byte to add
j	second byte to add

Returns: the sum of i + j, 8-bit

Definition at line 135 of file math8.h.

◆ add8to16()

LIB8STATIC_ALWAYS_INLINE uint16_t add8to16	(	uint8_t	i,
		uint16_t	j )

Add one byte to two bytes, with 16-bit result.

Note: This does not saturate and may overflow!

Parameters

i	first value to add, 8-bit
j	second value to add, 16-bit

Returns: the sum of i + j, 16-bit

Definition at line 153 of file math8.h.

◆ addmod8()

LIB8STATIC uint8_t addmod8	(	uint8_t	a,
		uint8_t	b,
		uint8_t	m )

Add two numbers, and calculate the modulo of the sum and a third number, M.

In other words, it returns (A+B) % M. It is designed as a compact mechanism for incrementing a "mode" switch and wrapping around back to "mode 0" when the switch goes past the end of the available range. e.g. if you have seven modes, this switches to the next one and wraps around if needed:

mode = addmod8( mode, 1, 7);

addmod8

LIB8STATIC uint8_t addmod8(uint8_t a, uint8_t b, uint8_t m)

Add two numbers, and calculate the modulo of the sum and a third number, M.

Definition math8.h:392

Parameters

a	dividend byte
b	value to add to the dividend
m	divisor byte

Returns: remainder of (a + b) / m

See also: mod8() for notes on performance.

Definition at line 392 of file math8.h.

◆ avg15()

LIB8STATIC_ALWAYS_INLINE int16_t avg15	(	int16_t	i,
		int16_t	j )

Calculate an integer average of two signed 15-bit integers (int16_t).

If the first argument is even, result is rounded down. If the first argument is odd, result is rounded up.

Parameters

i	first value to average
j	second value to average

Returns: mean average of i and j, rounded

Definition at line 328 of file math8.h.

◆ avg16()

LIB8STATIC_ALWAYS_INLINE uint16_t avg16	(	uint16_t	i,
		uint16_t	j )

Calculate an integer average of two unsigned 16-bit integer values (uint16_t), rounded down.

Fractional results are rounded down, e.g. avg16(20,41) = 30

Parameters

i	first value to average
j	second value to average

Returns: mean average of i and j, rounded down

Definition at line 216 of file math8.h.

◆ avg16r()

LIB8STATIC_ALWAYS_INLINE uint16_t avg16r	(	uint16_t	i,
		uint16_t	j )

Calculate an integer average of two unsigned 16-bit integer values (uint16_t), rounded up.

Fractional results are rounded up, e.g. avg16r(20,41) = 31

Parameters

i	first value to average
j	second value to average

Returns: mean average of i and j, rounded up

Definition at line 271 of file math8.h.

◆ avg7()

LIB8STATIC_ALWAYS_INLINE int8_t avg7	(	int8_t	i,
		int8_t	j )

Calculate an integer average of two signed 7-bit integers (int8_t).

If the first argument is even, result is rounded down. If the first argument is odd, result is rounded up.

Parameters

i	first value to average
j	second value to average

Returns: mean average of i and j, rounded

Definition at line 306 of file math8.h.

◆ avg8()

LIB8STATIC_ALWAYS_INLINE uint8_t avg8	(	uint8_t	i,
		uint8_t	j )

Calculate an integer average of two unsigned 8-bit integer values (uint8_t), rounded down.

Fractional results are rounded down, e.g. avg8(20,41) = 30

Parameters

i	first value to average
j	second value to average

Returns: mean average of i and j, rounded down

Definition at line 193 of file math8.h.

◆ avg8r()

LIB8STATIC_ALWAYS_INLINE uint8_t avg8r	(	uint8_t	i,
		uint8_t	j )

Calculate an integer average of two unsigned 8-bit integer values (uint8_t), rounded up.

Fractional results are rounded up, e.g. avg8r(20,41) = 31

Parameters

i	first value to average
j	second value to average

Returns: mean average of i and j, rounded up

Definition at line 245 of file math8.h.

◆ blend8()

LIB8STATIC uint8_t blend8	(	uint8_t	a,
		uint8_t	b,
		uint8_t	amountOfB )

Blend a variable proportion (0-255) of one byte to another.

Parameters

a	the starting byte value
b	the byte value to blend toward
amountOfB	the proportion (0-255) of b to blend

Returns: a byte value between a and b, inclusive

Definition at line 667 of file math8.h.

◆ mod8()

LIB8STATIC_ALWAYS_INLINE uint8_t mod8	(	uint8_t	a,
		uint8_t	m )

Calculate the remainder of one unsigned 8-bit value divided by anoter, aka A % M.

Implemented by repeated subtraction, which is very compact, and very fast if A is "probably" less than M. If A is a large multiple of M, the loop has to execute multiple times. However, even in that case, the loop is only two instructions long on AVR, i.e., quick.

Parameters

a	dividend byte
m	divisor byte

Returns: remainder of a / m (i.e. a % m)

Definition at line 361 of file math8.h.

◆ mul8()

LIB8STATIC_ALWAYS_INLINE uint8_t mul8	(	uint8_t	i,
		uint8_t	j )

8x8 bit multiplication, with 8-bit result.

Parameters

i	first byte to multiply
j	second byte to multiply

Returns: the product of i * j

Note: This does not saturate and may overflow!

Definition at line 446 of file math8.h.

◆ qadd7()

LIB8STATIC_ALWAYS_INLINE int8_t qadd7	(	int8_t	i,
		int8_t	j )

Add one byte to another, saturating at 0x7F and -0x80.

Parameters

i	first byte to add
j	second byte to add

Returns: the sum of i + j, capped at 0x7F and -0x80

Definition at line 64 of file math8.h.

◆ qadd8()

LIB8STATIC_ALWAYS_INLINE uint8_t qadd8	(	uint8_t	i,
		uint8_t	j )

Add one byte to another, saturating at 0xFF.

Parameters

i	first byte to add
j	second byte to add

Returns: the sum of i + j, capped at 0xFF

Examples: Fire2012WithPalette.ino.

Definition at line 31 of file math8.h.

◆ qmul8()

LIB8STATIC_ALWAYS_INLINE uint8_t qmul8	(	uint8_t	i,
		uint8_t	j )

8x8 bit multiplication with 8-bit result, saturating at 0xFF.

Parameters

i	first byte to multiply
j	second byte to multiply

Returns: the product of i * j, capping at 0xFF

Definition at line 470 of file math8.h.

◆ qsub8()

LIB8STATIC_ALWAYS_INLINE uint8_t qsub8	(	uint8_t	i,
		uint8_t	j )

Subtract one byte from another, saturating at 0x00.

Parameters

i	byte to subtract from
j	byte to subtract

Returns: i - j with a floor of 0

Examples: Fire2012WithPalette.ino.

Definition at line 103 of file math8.h.

◆ sqrt16()

LIB8STATIC uint8_t sqrt16 ( uint16_t x )

Square root for 16-bit integers.

About three times faster and five times smaller than Arduino's general sqrt on AVR.

Definition at line 524 of file math8.h.

◆ sqrt8()

LIB8STATIC_ALWAYS_INLINE uint8_t sqrt8 ( uint8_t x )

Definition at line 553 of file math8.h.

◆ sub8()

LIB8STATIC_ALWAYS_INLINE uint8_t sub8	(	uint8_t	i,
		uint8_t	j )

Subtract one byte from another, 8-bit result.

Note: This does not saturate and may overflow!

Parameters

i	byte to subtract from
j	byte to subtract

Returns: i - j

Definition at line 174 of file math8.h.

◆ submod8()

LIB8STATIC uint8_t submod8	(	uint8_t	a,
		uint8_t	b,
		uint8_t	m )

Subtract two numbers, and calculate the modulo of the difference and a third number, M.

In other words, it returns (A-B) % M. It is designed as a compact mechanism for decrementing a "mode" switch and wrapping around back to "mode 0" when the switch goes past the start of the available range. e.g. if you have seven modes, this switches to the previous one and wraps around if needed:

mode = submod8( mode, 1, 7);

submod8

LIB8STATIC uint8_t submod8(uint8_t a, uint8_t b, uint8_t m)

Subtract two numbers, and calculate the modulo of the difference and a third number,...

Definition math8.h:425

Parameters

a	dividend byte
b	value to subtract from the dividend
m	divisor byte

Returns: remainder of (a - b) / m

See also: mod8() for notes on performance.

Definition at line 425 of file math8.h.