Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.math
Class Fixed32

java.lang.Object
  extended by 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:
BlackBerry API 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 ArcTan(int f)
          Computes ArcTan(f) in radians, f is a fixed point number.
static int Cos(int f)
          Computes COS(f), f is a fixed point number in radians.
static int Sin(int f)
          Computes SIN(f), f is a fixed point number in radians.
static int Tan(int f)
          Computes Tan(f), f is a fixed point number in radians.
static int abs(int a)
          Returns the absolute value of the given parameter
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 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 divtoInt(int n, int m)
          Divide and convert back to regular int.
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 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 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).

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

MIN_VALUE

public static final int MIN_VALUE
The minimum fixed-point representation (-32768).

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

PI

public static final int PI
A fixed-point representation of pi, good to the fourth decimal place (3.14159...).

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

E

public static final int E
A fixed-point representation of e, good to the fourth decimal place (2.71828...).

See Also:
Constant Field Values
Since:
BlackBerry API 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).

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

FP090

public static final int FP090
Fixed-point representation of 90.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

FP180

public static final int FP180
Fixed-point representation of 180.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

FP270

public static final int FP270
Fixed-point representation of 270.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

FP360

public static final int FP360
Fixed-point representation of 360.

See Also:
Constant Field Values
Since:
BlackBerry API 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...).

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

ONE

public static final int ONE
See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

HALF

public static final int HALF
See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

QUARTER

public static final int QUARTER
See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

TWOPI

public static final int TWOPI
See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

PI_OVER_2

public static final int PI_OVER_2
See Also:
Constant Field Values
Since:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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 Fixed32.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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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 Fixed32.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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 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:
BlackBerry API 4.0.0

ArcTan

public static int ArcTan(int f)
Computes ArcTan(f) in radians, f is a fixed point number.

Since:
BlackBerry API 4.0.0

parseFixed32

public static int parseFixed32(String value)
                        throws NumberFormatException
Parses a Fixed32 value from a String. Current precision is 3 decimal places.

Throws:
NumberFormatException
Since:
BlackBerry API 4.0.0

divtoInt

public static int divtoInt(int n,
                           int m)
Divide and convert back to regular int. Because the method uses more precision, it avoids range errors that may occur from 16:16. It does not detect or avoid range errors in general.

Parameters:
n - the fixed-point dividend.
m - the fixed-point divisor.
Returns:
a regular integer number representing n divided by m.
Since:
BlackBerry API 4.3.0



Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal