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

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

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

HALF

public static final int HALF
Since:
JDE 4.0.0

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

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

ONE

public static final int ONE
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

PI_OVER_2

public static final int PI_OVER_2
Since:
JDE 4.0.0

QUARTER

public static final int QUARTER
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

TWOPI

public static final int TWOPI
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

ArcTan

public static int ArcTan(int f)
Computes ArcTan(f) in radians, f is a fixed point number.
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


Copyright 1999-2007 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.