Scaling Functions

Detailed Description

Fast, efficient 8-bit scaling 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.

Topics
	Scaling Functions that Leave R1 Dirty
	These functions are more efficient for scaling multiple bytes at once, but require calling cleanup_R1() afterwards.

Functions
LIB8STATIC_ALWAYS_INLINE uint8_t	scale8 (uint8_t i, fract8 scale)
	Scale one byte by a second one, which is treated as the numerator of a fraction whose denominator is 256.
constexpr uint8_t	scale8_constexpr (uint8_t i, fract8 scale)
LIB8STATIC_ALWAYS_INLINE uint8_t	scale8_video (uint8_t i, fract8 scale)
	The "video" version of scale8() guarantees that the output will be only be zero if one or both of the inputs are zero.
LIB8STATIC void	nscale8x3 (uint8_t &r, uint8_t &g, uint8_t &b, fract8 scale)
	Scale three one-byte values by a fourth one, which is treated as the numerator of a fraction whose demominator is 256.
LIB8STATIC void	nscale8x3_video (uint8_t &r, uint8_t &g, uint8_t &b, fract8 scale)
	Scale three one-byte values by a fourth one, which is treated as the numerator of a fraction whose demominator is 256.
LIB8STATIC void	nscale8x2 (uint8_t &i, uint8_t &j, fract8 scale)
	Scale two one-byte values by a third one, which is treated as the numerator of a fraction whose demominator is 256.
LIB8STATIC void	nscale8x2_video (uint8_t &i, uint8_t &j, fract8 scale)
	Scale two one-byte values by a third one, which is treated as the numerator of a fraction whose demominator is 256.
LIB8STATIC_ALWAYS_INLINE uint16_t	scale16by8 (uint16_t i, fract8 scale)
	Scale a 16-bit unsigned value by an 8-bit value, which is treated as the numerator of a fraction whose denominator is 256.
LIB8STATIC uint16_t	scale16 (uint16_t i, fract16 scale)
	Scale a 16-bit unsigned value by an 16-bit value, which is treated as the numerator of a fraction whose denominator is 65536.

Function Documentation

nscale8x2()

LIB8STATIC void nscale8x2	(	uint8_t &	i,
		uint8_t &	j,
		fract8	scale )

Scale two one-byte values by a third one, which is treated as the numerator of a fraction whose demominator is 256.

In other words, it computes i,j * (scale / 256).

Warning

This function always modifies its arguments in place!

Parameters

i	first value to scale
j	second value to scale
scale	scale factor, in n/256 units

Definition at line 417 of file scale8.h.

nscale8x2_video()

LIB8STATIC void nscale8x2_video	(	uint8_t &	i,
		uint8_t &	j,
		fract8	scale )

Scale two one-byte values by a third one, which is treated as the numerator of a fraction whose demominator is 256.

In other words, it computes i,j * (scale / 256), ensuring that non-zero values passed in remain non zero, no matter how low the scale argument.

Warning

This function always modifies its arguments in place!

Parameters

i	first value to scale
j	second value to scale
scale	scale factor, in n/256 units

Definition at line 447 of file scale8.h.

nscale8x3()

LIB8STATIC void nscale8x3	(	uint8_t &	r,
		uint8_t &	g,
		uint8_t &	b,
		fract8	scale )

Scale three one-byte values by a fourth one, which is treated as the numerator of a fraction whose demominator is 256.

In other words, it computes r,g,b * (scale / 256)

Warning

This function always modifies its arguments in place!

Parameters

r	first value to scale
g	second value to scale
b	third value to scale
scale	scale factor, in n/256 units

Definition at line 357 of file scale8.h.

nscale8x3_video()

LIB8STATIC void nscale8x3_video	(	uint8_t &	r,
		uint8_t &	g,
		uint8_t &	b,
		fract8	scale )

Scale three one-byte values by a fourth one, which is treated as the numerator of a fraction whose demominator is 256.

In other words, it computes r,g,b * (scale / 256), ensuring that non-zero values passed in remain non-zero, no matter how low the scale argument.

Warning

This function always modifies its arguments in place!

Parameters

r	first value to scale
g	second value to scale
b	third value to scale
scale	scale factor, in n/256 units

Definition at line 391 of file scale8.h.

scale16()

LIB8STATIC uint16_t scale16	(	uint16_t	i,
		fract16	scale )

Scale a 16-bit unsigned value by an 16-bit value, which is treated as the numerator of a fraction whose denominator is 65536.

In other words, it computes i * (scale / 65536)

Parameters

i	input value to scale
scale	scale factor, in n/65536 units

Returns

scaled value

Definition at line 540 of file scale8.h.

scale16by8()

LIB8STATIC_ALWAYS_INLINE uint16_t scale16by8	(	uint16_t	i,
		fract8	scale )

Scale a 16-bit unsigned value by an 8-bit value, which is treated as the numerator of a fraction whose denominator is 256.

In other words, it computes i * (scale / 256)

Parameters

i	input value to scale
scale	scale factor, in n/256 units

Returns

scaled value

Definition at line 468 of file scale8.h.

scale8()

LIB8STATIC_ALWAYS_INLINE uint8_t scale8	(	uint8_t	i,
		fract8	scale )

Scale one byte by a second one, which is treated as the numerator of a fraction whose denominator is 256.

In other words, it computes i * (scale / 256)

Parameters

i	input value to scale
scale	scale factor, in n/256 units

Returns

scaled value

Note

Takes 4 clocks on AVR with MUL, 2 clocks on ARM

Examples

Fire2012WithPalette.ino, and XYMatrix.ino.

Definition at line 34 of file scale8.h.

scale8_constexpr()

uint8_t scale8_constexpr ( uint8_t i, fract8 scale )

constexpr

Definition at line 104 of file scale8.h.

scale8_video()

LIB8STATIC_ALWAYS_INLINE uint8_t scale8_video	(	uint8_t	i,
		fract8	scale )

The "video" version of scale8() guarantees that the output will be only be zero if one or both of the inputs are zero.

If both inputs are non-zero, the output is guaranteed to be non-zero. This makes for better "video"/LED dimming, at the cost of several additional cycles.

Parameters

i	input value to scale
scale	scale factor, in n/256 units

Returns

scaled value

See also

scale8()

Definition at line 117 of file scale8.h.