3-D math utilities

You can use methods in the net.rim.device.api.math package to enhance the speed and versatility of BlackBerry® device applications that you create.

You can use the math.Fixed32 class for a collection of fixed-point math routines that use the 16.16 convention to fix the decimal point. This convention specifies that the most significant 16 bits of a 32-bit integer are used for the fixed-point component of the value, and the remainder are used for the mantissa. Addition and subtraction operations are performed with regular integer + and - operators to help keep this library small. 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 number to negative infinity is -32768.0. The smallest increment between consecutive numbers is 1/65536.

You can use the math.Matrix4f class to create a 4-by-4 matrix of floating point numbers that represents a 3-D transformation. The math.Matrix4f class is directly compatible with OpenGL® because its elements are stored in memory in the same manner that is used by OpenGL.

You can use the math.Quaternion4f class to create a quaternion number that you can use to represent the orientation of an object in space. Quaternions are typically used instead of Euler angles and rotation matrices as a way to achieve smooth interpolation and avoid gimbal lock. The math.Quaternion4f class does not keep the quaternion normalized, so you must normalize the quaternion when necessary by invoking normalize().

You can use the math.Vector3f class to create a 3-element vector of floating-point numbers. When you use a vector to represent a surface normal, the vector should typically be normalized. In other applications of directional vectors, you might want to leave the magnitude of the vector intact. When you use a vector to represent a point, the elements of the vector represent a position in 3-D space.

Code sample: Using Fixed32()

import net.rim.device.api.math.*;

public class demoFixed32
{
    demoFixed32()
    {
        // convert an integer to fixed-point
        int n = Fixed32.toFP(7); // 7.0

        // convert a quantity in ten-thousandths to fixed-point
        int m = Fixed32.tenThouToFP(70625); // 7.0625

        // convert from fixed-point, truncate fractional component
        int trunc = Fixed32.toInt(m); // 7
 
        // multiply by ten thousand
        int mult = Fixed32.toIntTenThou(m); // 70625

        // add, subtract, negate, and compare
        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

        // do not use increment and decrement operators
        result = Fixed32.toFP(2);
        ++result; // WRONG! result will NOT be 3

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

        // Use * and / when multiplying or dividing by an integer scalar
        // Use mul to multiply 2 fixed-point numbers
        // 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
 
        // mul, div, sqrt, sind, cosd, tand, and atand2
        // all work 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); // -135.0 degrees in fixed-point
    }
}
Previous topic: Native I/O

Was this information helpful? Send us your comments.