net.rim.device.api.math
Class Fixed32

java.lang.Object
  |
  +--net.rim.device.api.math.Fixed32

public final class Fixed32

extends Object

The class Fixed32 is a collection of fixed-point math routines. Fixed32 uses the 16.16 convention to fix the decimal point.

There are no add or sub methods because they can be performed with regular integer + and - operators. The goal is to keep this library to an absolute minimum in size.

The methods of class Fixed32 are all static, and deal with 32-bit ints.

The 16.16 convention uses the 16 most-significant bits of a 32-bit int to represent the whole part, and the 16 least-significant bits to represent the fractional part. For example, 0x00010000 is the fixed-point representation of 1, 0x00018000 is the fixed-point representation of 1.5, and 0x00000001 is the fixed-point representation of 1/65536.

The numbers are signed, so negative numbers can be represented. The largest positive number in 16.16 format is just over 32767.9999, and the closest to negative infinity is -32768.0. The smallest increment between consecutive numbers is 1/65536 (which works out to about 0.00001526).

Fixed32 provides 2 methods for converting to fixed-point representation. The method toFP converts an integer to fixed-point:

     int n = Fixed32.toFP(7);              // 7.0
 

The method tenThouToFP converts a quantity in ten-thousandths to fixed-point:

     int m = Fixed32.tenThouToFP(70625);   // 7.0625
 

Also, there are 2 methods for converting back from fixed-point. The method toInt truncates any fractional part:

     System.out.println(Fixed32.toInt(m));        // prints 7
 

The method toIntTenThou returns a value in units of ten-thousandths:

     System.out.println(Fixed32.toIntTenThou(m)); // prints 70625
 

Fixed-point numbers can be added, subtracted, negated, and compared using regular integer operators:

     int result = m - n;           // 7.0625 - 7.0 = 0.0625
     result = -result;             // -0.0625
     result -= n;                  // -0.0625 - 7.0 = -7.0625
     boolean b = (result == -m);   // true
     boolean bb = (m < n);         // false
 

The increment and decrement operators will not give expected results:

     result = Fixed32.toFP(2);
     ++result;                  // WRONG! result will NOT be 3

     result = Fixed32.toFP(2);
     result += Fixed32.toFP(1); // Correct: result will be 3
 

If you are multiplying or dividing by an integer scalar, you may use the regular integer * and / operators. Otherwise you must use the mul or div methods. You must use mul to multiply 2 fixed-point numbers, and you must use div to divide 2 fixed-point numbers!

     m = Fixed32.tenThouToFP(12500);    // 1.25

     m *= 3;                            // OK: 1.25 * 3 = 3.75
     m /= 2;                            // OK: 3.75 / 2 = 1.875

     m = Fixed32.mul(m,
         Fixed32.tenThouToFP(15000));   // 1.875 * 1.5000 = 2.8125

     m = Fixed32.div(m, m);             // 2.8125 / 2.8125 = 1.0
 

The Fixed32 methods mul, div, sqrt, sind, cosd, tand, and atand2 all deal with 16.16 fixed-point numbers:

     m = Fixed32.tenThouToFP(172500);    // 17.2500

     n = Fixed32.sqrt(m);                // sqrt(17.25)
     n = Fixed32.sind(m);                // sine of 17.25 degrees
     n = Fixed32.cosd(m);                // cosine of 17.25 degrees

     result = Fixed32.atand2(-m, -m);    // returns -135.0 degrees in fixed-point
 

Since:

JDE 4.0.0

Field Summary

static int	E A fixed-point representation of e, good to the fourth decimal place (2.71828...).
static int	FP090 Fixed-point representation of 90.
static int	FP180 Fixed-point representation of 180.
static int	FP270 Fixed-point representation of 270.
static int	FP360 Fixed-point representation of 360.
static int	HALF
static int	MAX_VALUE The maximum fixed-point representation (32767.9999847412109375).
static int	MIN_VALUE The minimum fixed-point representation (-32768).
static short	NUM_FRACTION_BITS The number of fraction bits for 16.16 fixed-point representation (16).
static int	ONE
static int	PI A fixed-point representation of pi, good to the fourth decimal place (3.14159...).
static int	PI_OVER_2
static int	QUARTER
static int	RAD2DEG A fixed-point representation of the conversion factor from radians to degrees, good to the fourth decimal place (57.29578...).
static int	TWOPI

Method Summary

static int	abs(int a) Returns the absolute value of the given parameter
static int	ArcTan(int f) Computes ArcTan(f) in radians, f is a fixed point number |f| <= 1 For the inverse tangent calls, all approximations are valid for |t| <= 1.
static int	atand2(int y, int x) Returns the arctangent of y/x in degrees for the point (x,y) with consideration to all 4 quadrants.
static int	Cos(int f) Computes COS(f), f is a fixed point number in radians.
static int	cosd(int ang) Returns the cosine of a fixed-point angle in degrees.
static int	div(int n, int m) Returns the quotient of two fixed-point numbers.
static int	mul(int n, int m) Returns the product of two fixed-point numbers.
static int	parseFixed32(String value) Parses a Fixed32 value from a String.
static int	round(int n) Round a fixed-point value to the nearest fixed-point value representing an integer.
static int	Sin(int f) Computes SIN(f), f is a fixed point number in radians.
static int	sind(int ang) Returns the sine of a fixed-point angle in degrees.
static int	sqrt(int n) Returns the square root of a fixed-point number.
static int	Tan(int f) Computes Tan(f), f is a fixed point number in radians.
static int	tand(int ang) Returns the tangent of a fixed-point angle in degrees.
static int	tenThouToFP(int tenThou) Converts an integer in ten-thousandths to a fixed-point number.
static int	toFP(int i) Converts a normal integer to a fixed-point number.
static int	toInt(int fp) Converts a fixed-point number to a normal integer.
static int	toIntTenThou(int fp) Converts a fixed-point number to an integer in ten-thousandths.
static int	toRoundedInt(int value) Converts a fixed-point number to a normal integer.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_VALUE

public static final int MAX_VALUE

The maximum fixed-point representation (32767.9999847412109375).

Since:

JDE 4.0.0

MIN_VALUE

public static final int MIN_VALUE

The minimum fixed-point representation (-32768).

Since:

JDE 4.0.0

PI

public static final int PI

A fixed-point representation of pi, good to the fourth decimal place (3.14159...).

Since:

JDE 4.0.0

E

public static final int E

A fixed-point representation of e, good to the fourth decimal place (2.71828...).

Since:

JDE 4.0.0

NUM_FRACTION_BITS

public static final short NUM_FRACTION_BITS

The number of fraction bits for 16.16 fixed-point representation (16).

Since:

JDE 4.0.0

FP090

public static final int FP090

Fixed-point representation of 90.

Since:

JDE 4.0.0

FP180

public static final int FP180

Fixed-point representation of 180.

Since:

JDE 4.0.0

FP270

public static final int FP270

Fixed-point representation of 270.

Since:

JDE 4.0.0

FP360

public static final int FP360

Fixed-point representation of 360.

Since:

JDE 4.0.0

RAD2DEG

public static final int RAD2DEG

A fixed-point representation of the conversion factor from radians to degrees, good to the fourth decimal place (57.29578...).

Since:

JDE 4.0.0

ONE

public static final int ONE

Since:

JDE 4.0.0

HALF

public static final int HALF

Since:

JDE 4.0.0

QUARTER

public static final int QUARTER

Since:

JDE 4.0.0

TWOPI

public static final int TWOPI

Since:

JDE 4.0.0

PI_OVER_2

public static final int PI_OVER_2

Since:

JDE 4.0.0

Method Detail

abs

public static int abs(int a)

Returns the absolute value of the given parameter

Parameters:

a - The value to find the absolute value of

Since:

JDE 4.0.0

mul

public static int mul(int n,
                      int m)

Returns the product of two fixed-point numbers. This method uses 64-bit (long) multiplication. Overflow and underflow are possible just as with normal finite-precision math.

Parameters:

n - the fixed-point number to be multiplied.

m - the fixed-point multiplier.

Returns:

a fixed-point number representing the product of n and m.

Since:

JDE 4.0.0

div

public static int div(int n,
                      int m)

Returns the quotient of two fixed-point numbers. This method uses 64-bit (long) division. Overflow and underflow are possible just as with normal finite-precision math, as is divide-by-zero.

Parameters:

n - the fixed-point dividend.

m - the fixed-point divisor.

Returns:

a fixed-point number representing n divided by m.

Since:

JDE 4.0.0

toInt

public static int toInt(int fp)

Converts a fixed-point number to a normal integer. The fixed-point integer is truncated, so any fractional part is discarded. Use toIntTenThou(int) if you need to keep the fractional part.

Parameters:

fp - the fixed-point number to be truncated and converted.

Returns:

the truncated result in normal integer representation.

Since:

JDE 4.0.0

toRoundedInt

public static int toRoundedInt(int value)

Converts a fixed-point number to a normal integer. The fixed point integer is rounded to the nearest whole number.

Parameters:

value - the fixed-point number to convert.

Returns:

the rounded result in normal integer representation.

Since:

JDE 4.0.0

toIntTenThou

public static int toIntTenThou(int fp)

Converts a fixed-point number to an integer in ten-thousandths.

Parameters:

fp - the fixed-point number to be converted.

Returns:

a normal integer in ten thousandths.

Since:

JDE 4.0.0

toFP

public static int toFP(int i)

Converts a normal integer to a fixed-point number. The input integer is shifted left by 16 bits. Use tenThouToFP(int) if you need to convert a number with a fractional part. The given integer must be within -32768 to 32767 (inclusive) or the return value will not be representative.

Parameters:

i - the integer to be converted to a fixed-point number.

Returns:

a fixed-point number with 16 bits fraction.

Since:

JDE 4.0.0

tenThouToFP

public static int tenThouToFP(int tenThou)

Converts an integer in ten-thousandths to a fixed-point number. The given integer must be within -327680000 to 327679999 (inclusive) or the return value will not be representative.

Parameters:

tenThou - the integer in ten-thousandths to be converted.

Returns:

a fixed-point number with 16 bits fraction.

Since:

JDE 4.0.0

sqrt

public static int sqrt(int n)

Returns the square root of a fixed-point number.

Parameters:

n - the fixed-point number to extract the root from.

Returns:

a fixed-point number representing the square root of n.

Throws:

IllegalArgumentException - if n is negative.

Since:

JDE 4.0.0

sind

public static int sind(int ang)

Returns the sine of a fixed-point angle in degrees.

Parameters:

ang - the fixed-point angle in degrees.

Returns:

a fixed-point number representing the sine of ang.

Since:

JDE 4.0.0

cosd

public static int cosd(int ang)

Returns the cosine of a fixed-point angle in degrees.

Parameters:

ang - the fixed-point angle in degrees.

Returns:

a fixed-point number representing the cosine of ang.

Since:

JDE 4.0.0

tand

public static int tand(int ang)

Returns the tangent of a fixed-point angle in degrees. The accuracy of this function is reduced near the singularities, and evaluation at a singularity will result in division by zero. (Singularities are where the cosine of the angle is zero.)

Parameters:

ang - the fixed-point angle in degrees.

Returns:

a fixed-point number representing the tangent of ang.

Since:

JDE 4.0.0

atand2

public static int atand2(int y,
                         int x)

Returns the arctangent of y/x in degrees for the point (x,y) with consideration to all 4 quadrants. This function is analogous to the standard atan2(y,x) function, except that it returns an angle in degrees. If x and y are both zero, the result is undefined and a division by zero will occur.

Parameters:

y - fixed-point numerator for arctangent.

x - fixed-point denominator for arctangent.

Returns:

a fixed-point number representing the arctangent in degrees of y/x. Will be between -180.0 and 180.0 degrees.

Since:

JDE 4.0.0

round

public static int round(int n)

Round a fixed-point value to the nearest fixed-point value representing an integer.

Parameters:

n - Fixed-point value to round.

Returns:

Rounded fixed-point value.

Since:

JDE 4.0.0

Sin

public static int Sin(int f)

Computes SIN(f), f is a fixed point number in radians. For best precision, it is recommended that -2PI <= f <= 2PI, but generally speaking, f can be any number as long as its conversion to degrees does not cause Fixed32 overflow, i.e. 32767 < f * 180 / PI < -32768.

Since:

JDE 4.0.0

Cos

public static int Cos(int f)

Computes COS(f), f is a fixed point number in radians. For best precision, it is recommended that -2PI <= f <= 2PI, but generally speaking, f can be any number as long as its conversion to degrees does not cause Fixed32 overflow, i.e. 32767 < f * 180 / PI < -32768.

Since:

JDE 4.0.0

Tan

public static int Tan(int f)

Computes Tan(f), f is a fixed point number in radians. For best precision, it is recommended that -2PI <= f <= 2PI, but generally speaking, f can be any number as long as its conversion to degrees does not cause Fixed32 overflow, i.e. 32767 < f * 180 / PI < -32768. f = PI/2 + PI*n (where n is integer) will cause an arithmetic exception.

Since:

JDE 4.0.0

ArcTan

public static int ArcTan(int f)

Computes ArcTan(f) in radians, f is a fixed point number |f| <= 1

For the inverse tangent calls, all approximations are valid for |t| <= 1. To compute ATAN(t) for t > 1, use ATAN(t) = PI/2 - ATAN(1/t). For t < -1, use ATAN(t) = -PI/2 - ATAN(1/t).

Since:

JDE 4.0.0

parseFixed32

public static int parseFixed32(String value)
                        throws NumberFormatException

Parses a Fixed32 value from a String. Current percision is 3 decimal places

Since:

JDE 4.0.0