CWRUtil

Helper classes and functions for CanvasWidget. A handful of utility functions can be found here. These include helper functions for converting between float, int and Q5/Q10/Q15 formats. There are also functions for calculating sin() and cos() in integers with a high number of bits (15) reserved for fraction. Having sin() and cos() pre-calculated in this way allows very fast drawing of circles without the need for floating point arithmetic.

Using Q5, which uses 32 bit value internally, numbers from -67108865 to +67108864.96875 with a precision of 1/32 = 0.03125 can be represented, as described in http://en.wikipedia.org/wiki/Q_%28number_format%29.

Doing arithmetic operations on Q5, Q10 and Q15 numbers is described in detail on http://en.wikipedia.org/wiki/Fixed-point_arithmetic.

Public Classes

class	Q10
	Defines a "floating point number" with 10 bits reserved for the fractional part of the decimal number.
class	Q15
	Defines a "floating point number" with 15 bits reserved for the fractional part of the decimal number.
class	Q5
	Defines a "floating point number" with 5 bits reserved for the fractional part of the decimal number.

Public Functions

int	angle(Q5 x, Q5 y)
	Find angle of a coordinate relative to (0,0).
int	angle(Q5 x, Q5 y, Q5 & d)
	Find the angle of the coordinate (x, y) relative to (0, 0).
template \<typename T \> int	angle(T x, T y)
	Find angle of a coordinate relative to (0,0).
template \<typename T \> int	angle(T x, T y, T & d)
	Find angle of a coordinate relative to (0,0).
int8_t	arcsine(Q10 q10)
	Gets the arcsine of the given fraction (given as Q10).
Q15	cosine(int i)
	Find the value of cos(i) with 15 bits precision using the fact that cos(i)=sin(90-i).
Q15	cosine(Q5 i)
	Find the value of cos(i) with 15 bits precision using the fact that cos(i)=sin(90-i).
Q5	length(Q5 x, Q5 y)
	Find the length of a given distance x,y as sqrt(xx+yy) while avoiding overflow.
Q5	muldiv_toQ5(int32_t factor1, int32_t factor2, int32_t divisor)
	Multiply two integers and divide by an integer without overflowing the multiplication.
Q5	muldivQ10(Q10 factor1, Q10 factor2, Q10 divisor)
	Multiply two Q5's and divide by a Q5 without overflowing the multiplication (assuming that the final result can be stored in a Q5).
Q5	muldivQ5(Q5 factor1, Q5 factor2, Q5 divisor)
	Multiply two Q5's and divide by a Q5 without overflowing the multiplication (assuming that the final result can be stored in a Q5).
Q5	mulQ5(Q5 factor1, Q10 factor2)
	Multiply one Q5 by a Q10 returning a new Q5 without overflowing.
Q5	mulQ5(Q5 factor1, Q5 factor2)
	Multiply two Q5's returning a new Q5 without overflowing.
Q15	sine(int i)
	Find the value of sin(i) with 15 bits precision.
Q15	sine(Q5 i)
	Find the value of sin(i) with 15 bits precision.
Q5	sqrtQ10(Q10 value)
	Find the square root of the given value.
template \<typename T \> FORCE_INLINE_FUNCTION Q10	toQ10(T value)
	Convert an integer to a fixed point number.
FORCE_INLINE_FUNCTION Q5	toQ5(Q5 value)
	Convert a Q5 to itself.
template \<typename T \> FORCE_INLINE_FUNCTION Q5	toQ5(T value)
	Convert an integer to a fixed point number.

Public Functions Documentation

angle

static int angle	(	Q5	x ,
		Q5	y
		)

Find angle of a coordinate relative to (0,0).

Parameters:

x	The x coordinate.
y	The y coordinate.

Returns:

The angle of the coordinate.

angle

static int angle	(	Q5	x ,
		Q5	y ,
		Q5 &	d
		)

Find the angle of the coordinate (x, y) relative to (0, 0).

Parameters:

x	The x coordinate.
y	The y coordinate.
d	The distance from (0,0) to (x,y).

Returns:

The angle.

angle

static int angle	(	T	x ,
		T	y
		)

Find angle of a coordinate relative to (0,0).

Template Parameters:

T	Generic type parameter (int or float).

Parameters:

x	The x coordinate.
y	The y coordinate.

Returns:

The angle of the coordinate.

angle

static int angle	(	T	x ,
		T	y ,
		T &	d
		)

Find angle of a coordinate relative to (0,0).

Template Parameters:

T	Generic type parameter (int or float).

Parameters:

x	The x coordinate.
y	The y coordinate.
d	The distance from (0,0) to (x,y).

Returns:

The angle of the coordinate.

arcsine

static int8_t arcsine	(	Q10	q10	)

Gets the arcsine of the given fraction (given as Q10).

The function is most precise for angles 0-45. To limit memory requirements, values above sqrt(1/2) is calculated as 90-arcsine(sqrt(1-q10^2)). Internally.

Parameters:

q10	The 10.

Returns:

An int8_t.

cosine

static Q15 cosine	(	int	i	)

Find the value of cos(i) with 15 bits precision using the fact that cos(i)=sin(90-i).

Parameters:

i	the angle in degrees. The angle follows the angles of the clock, 0 being straight up and 90 being 3 o'clock.

Returns:

the value of cos(i) with 15 bits precision on the fractional part.

See also:

sine

cosine

static Q15 cosine	(	Q5	i	)

Find the value of cos(i) with 15 bits precision using the fact that cos(i)=sin(90-i).

Parameters:

i	the angle in degrees. The angle follows the angles of the clock, 0 being straight up and 90 being 3 o'clock.

Returns:

the value of cos(i) with 15 bits precision on the fractional part.

See also:

sine

length

static Q5 length	(	Q5	x ,
		Q5	y
		)

Find the length of a given distance x,y as sqrt(xx+yy) while avoiding overflow.

The function uses sqrtQ10(Q10) as a helper function.

Parameters:

x	The x distance.
y	The y distance.

Returns:

The length of the vector (x,y).

See also:

sqrtQ10

muldiv_toQ5

static Q5 muldiv_toQ5	(	int32_t	factor1 ,
		int32_t	factor2 ,
		int32_t	divisor
		)

Multiply two integers and divide by an integer without overflowing the multiplication.

The result is returned in a Q5 thus allowing a more precise calculation to be performed.

Parameters:

factor1	The first factor.
factor2	The second factor.
divisor	The divisor.

Returns:

factor1 * factor2 / divisor as a Q5

muldivQ10

static Q5 muldivQ10	(	Q10	factor1 ,
		Q10	factor2 ,
		Q10	divisor
		)

Multiply two Q5's and divide by a Q5 without overflowing the multiplication (assuming that the final result can be stored in a Q5).

Parameters:

factor1	The first factor.
factor2	The second factor.
divisor	The divisor.

Returns:

factor1 * factor2 / divisor.

muldivQ5

static Q5 muldivQ5	(	Q5	factor1 ,
		Q5	factor2 ,
		Q5	divisor
		)

Multiply two Q5's and divide by a Q5 without overflowing the multiplication (assuming that the final result can be stored in a Q5).

Parameters:

factor1	The first factor.
factor2	The second factor.
divisor	The divisor.

Returns:

factor1 * factor2 / divisor.

mulQ5

static Q5 mulQ5	(	Q5	factor1 ,
		Q10	factor2
		)

Multiply one Q5 by a Q10 returning a new Q5 without overflowing.

Parameters:

factor1	The first factor.
factor2	The second factor.

Returns:

factor1 * factor2.

mulQ5

static Q5 mulQ5	(	Q5	factor1 ,
		Q5	factor2
		)

Multiply two Q5's returning a new Q5 without overflowing.

Parameters:

factor1	The first factor.
factor2	The second factor.

Returns:

factor1 * factor2.

sine

static Q15 sine	(	int	i	)

Find the value of sin(i) with 15 bits precision.

The returned value can be converted to a floating point number and divided by (1<<15) to get the rounded value of sin(i). By using this function, a complete circle can be drawn without the need for using floating point math.

Parameters:

i	the angle in degrees. The angle follows the angles of the clock, 0 being straight up and 90 being 3 o'clock.

Returns:

the value of sin(i) with 15 bits precision on the fractional part.

sine

static Q15 sine	(	Q5	i	)

Find the value of sin(i) with 15 bits precision.

The returned value can be converted to a floating point number and divided by (1<<15) to get the rounded value of sin(i). By using this function, a complete circle can be drawn without the need for using floating point math.

If the given degree is not an integer, the value is approximated by interpolation between sin(floor(i)) and sin(ceil(i)).

Parameters:

i	the angle in degrees. The angle follows the angles of the clock, 0 being straight up and 90 being 3 o'clock.

Returns:

the value of sin(i) with 15 bits precision on the fractional part.

sqrtQ10

static Q5 sqrtQ10	(	Q10	value	)

Find the square root of the given value.

Consider using length to avoid possible overflow when calculating a length.

Parameters:

value	The value to find the square root of.

Returns:

The square root of the given value.

See also:

length

toQ10

static FORCE_INLINE_FUNCTION Q10 toQ10	(	T	value	)

Convert an integer to a fixed point number.

This is done by multiplying the floating point value by (1 << 10).

Template Parameters:

T	Should be either int or float.

Parameters:

value	the integer to convert.

Returns:

the converted integer.

toQ5

static FORCE_INLINE_FUNCTION Q5 toQ5	(	Q5	value	)

Convert a Q5 to itself.

Allows toQ5 to be called with a variable that is already Q5.

Parameters:

value	the Q5.

Returns:

the value passed.

toQ5

static FORCE_INLINE_FUNCTION Q5 toQ5	(	T	value	)

Convert an integer to a fixed point number.

This is done by multiplying the floating point value by (1 << 5)

Template Parameters:

T	Should be either int or float.

Parameters:

value	the integer to convert.

Returns:

the converted integer.