Basic Math Operations

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 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 524 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 134 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);

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.

Examples

TwinkleFox.ino.

Definition at line 407 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 338 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 223 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 279 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 313 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 198 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 252 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 692 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 374 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 465 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 62 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

Fire2012.ino, Fire2012WithPalette.ino, NoisePlusPalette.ino, and Pacifica.ino.

Definition at line 28 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 492 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

Fire2012.ino, Fire2012WithPalette.ino, NoisePlusPalette.ino, and TwinkleFox.ino.

Definition at line 101 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 548 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 178 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);

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 442 of file math8.h.