Version: 4.16

# 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#

classQ10
Defines a "floating point number" with 10 bits reserved for the fractional part of the decimal number.
classQ15
Defines a "floating point number" with 15 bits reserved for the fractional part of the decimal number.
classQ5
Defines a "floating point number" with 5 bits reserved for the fractional part of the decimal number.

## Public Functions#

intangle(Q5 x, Q5 y)
Find angle of a coordinate relative to (0,0).
intangle(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_tarcsine(Q10 q10)
Gets the arcsine of the given fraction (given as Q10).
Q15cosine(int i)
Find the value of cos(i) with 15 bits precision using the fact that cos(i)=sin(90-i).
Q15cosine(Q5 i)
Find the value of cos(i) with 15 bits precision using the fact that cos(i)=sin(90-i).
Q5muldiv_toQ5(int32_t factor1, int32_t factor2, int32_t divisor)
Multiply two integers and divide by an integer without overflowing the multiplication.
Q5muldivQ10(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).
Q5muldivQ5(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).
Q5mulQ5(Q5 factor1, Q10 factor2)
Multiply one Q5 by a Q10 returning a new Q5 without overflowing.
Q5mulQ5(Q5 factor1, Q5 factor2)
Multiply two Q5's returning a new Q5 without overflowing.
Q15sine(int i)
Find the value of sin(i) with 15 bits precision.
Q15sine(Q5 i)
Find the value of sin(i) with 15 bits precision.
Q5sqrtQ10(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 Q5toQ5(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(Q5x ,
Q5y
)

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

Parameters:
xThe x coordinate.
yThe y coordinate.
Returns:

The angle of the coordinate.

### angle#

static int angle(Q5x ,
Q5y ,
Q5 &d
)

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

Parameters:
xThe x coordinate.
yThe y coordinate.
dThe distance from (0,0) to (x,y).
Returns:

The angle.

### angle#

static int angle(Tx ,
Ty
)

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

Template Parameters:
TGeneric type parameter (int or float).
Parameters:
xThe x coordinate.
yThe y coordinate.
Returns:

The angle of the coordinate.

### angle#

static int angle(Tx ,
Ty ,
T &d
)

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

Template Parameters:
TGeneric type parameter (int or float).
Parameters:
xThe x coordinate.
yThe y coordinate.
dThe distance from (0,0) to (x,y).
Returns:

The angle of the coordinate.

### arcsine#

static int8_t arcsine(Q10q10)

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:
q10The 10.
Returns:

An int8_t.

### cosine#

static Q15 cosine(inti)

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

Parameters:
ithe 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.

### cosine#

static Q15 cosine(Q5i)

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

Parameters:
ithe 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.

### muldiv_toQ5#

static Q5 muldiv_toQ5(int32_tfactor1 ,
int32_tfactor2 ,
int32_tdivisor
)

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:
factor1The first factor.
factor2The second factor.
divisorThe divisor.
Returns:

factor1 * factor2 / divisor as a Q5

### muldivQ10#

static Q5 muldivQ10(Q10factor1 ,
Q10factor2 ,
Q10divisor
)

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:
factor1The first factor.
factor2The second factor.
divisorThe divisor.
Returns:

factor1 * factor2 / divisor.

### muldivQ5#

static Q5 muldivQ5(Q5factor1 ,
Q5factor2 ,
Q5divisor
)

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:
factor1The first factor.
factor2The second factor.
divisorThe divisor.
Returns:

factor1 * factor2 / divisor.

### mulQ5#

static Q5 mulQ5(Q5factor1 ,
Q10factor2
)

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

Parameters:
factor1The first factor.
factor2The second factor.
Returns:

factor1 * factor2.

### mulQ5#

static Q5 mulQ5(Q5factor1 ,
Q5factor2
)

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

Parameters:
factor1The first factor.
factor2The second factor.
Returns:

factor1 * factor2.

### sine#

static Q15 sine(inti)

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:
ithe 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(Q5i)

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:
ithe 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(Q10value)

Find the square root of the given value.

Parameters:
valueThe value to find the square root of.
Returns:

The square root of the given value.

### toQ10#

static FORCE_INLINE_FUNCTION Q10 toQ10(Tvalue)

Convert an integer to a fixed point number.

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

Template Parameters:
TShould be either int or float.
Parameters:
valuethe integer to convert.
Returns:

the converted integer.

### toQ5#

static FORCE_INLINE_FUNCTION Q5 toQ5(Q5value)

Convert a Q5 to itself.

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

Parameters:
valuethe Q5.
Returns:

the value passed.

### toQ5#

static FORCE_INLINE_FUNCTION Q5 toQ5(Tvalue)

Convert an integer to a fixed point number.

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

Template Parameters:
TShould be either int or float.
Parameters:
valuethe integer to convert.
Returns:

the converted integer.