Class FloatUtil


  • public final class FloatUtil
    extends Object
    Basic Float math utility functions.

    Implementation assumes linear matrix layout in column-major order matching OpenGL's implementation, illustration:

        Row-Major                  Column-Major (OpenGL):
    
            |  0   1   2   3 |         |  0   4   8  12 |
            |                |         |                |
            |  4   5   6   7 |         |  1   5   9  13 |
        M = |                |     M = |                |
            |  8   9  10  11 |         |  2   6  10  14 |
            |                |         |                |
            | 12  13  14  15 |         |  3   7  11  15 |
    
               C   R                      C   R
             m[0*4+3] = tx;             m[0+4*3] = tx;
             m[1*4+3] = ty;             m[1+4*3] = ty;
             m[2*4+3] = tz;             m[2+4*3] = tz;
     

    Implementation utilizes unrolling of small vertices and matrices wherever possible while trying to access memory in a linear fashion for performance reasons, see:

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static boolean DEBUG  
      static float E  
      static float EPSILON
      Epsilon for floating point 1.1920928955078125E-7f, as once computed via getMachineEpsilon() on an AMD-64 CPU.
      static float HALF_PI
      The value PI/2, i.e.
      static float INV_DEVIANCE
      Inversion Epsilon, used with equals method to determine if two inverted matrices are close enough to be considered equal.
      static float PI
      The value PI, i.e.
      static float QUARTER_PI
      The value PI/4, i.e.
      static float SQUARED_PI
      The value PI^2.
      static float TWO_PI
      The value 2PI, i.e.
    • Constructor Summary

      Constructors 
      Constructor Description
      FloatUtil()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static float abs​(float a)  
      static float acos​(float a)  
      static float asin​(float a)  
      static float atan​(float a)  
      static float atan2​(float y, float x)  
      static int compare​(float a, float b)
      Return true if both values are equal w/o regarding an epsilon.
      static int compare​(float a, float b, float epsilon)
      Return true if both values are equal, i.e.
      static float[] copyMatrixColumn​(float[] m_in, int m_in_off, int column, float[] v_out, int v_out_off)
      Copy the named column of the given column-major matrix to v_out.
      static float[] copyMatrixRow​(float[] m_in, int m_in_off, int row, float[] v_out, int v_out_off)
      Copy the named row of the given column-major matrix to v_out.
      static float cos​(float a)  
      static float getMachineEpsilon()
      Return computed machine Epsilon value.
      static float getOrthoWinZ​(float orthoZ, float zNear, float zFar)
      Returns orthogonal distance (1f/zNear-1f/orthoDist)/(1f/zNear-1f/zFar);
      static float getZBufferEpsilon​(int zBits, float z, float zNear)
      Returns resolution of Z buffer of given parameter, see Love Your Z-Buffer.
      static int getZBufferValue​(int zBits, float z, float zNear, float zFar)
      Returns Z buffer value of given parameter, see Love Your Z-Buffer.
      static float[] invertMatrix​(float[] msrc, float[] mres)
      Invert the given matrix.
      static float[] invertMatrix​(float[] msrc, int msrc_offset, float[] mres, int mres_offset)
      Invert the given matrix.
      static boolean isEqual​(float a, float b)
      Return true if both values are equal w/o regarding an epsilon.
      static boolean isEqual​(float a, float b, float epsilon)
      Return true if both values are equal, i.e.
      static boolean isZero​(float a, float epsilon)
      Return true if value is zero, i.e.
      static float[] makeFrustum​(float[] m, int m_offset, boolean initM, float left, float right, float bottom, float top, float zNear, float zFar)
      Make given matrix the frustum matrix based on given parameters.
      static float[] makeIdentity​(float[] m)
      Make matrix an identity matrix
      static float[] makeIdentity​(float[] m, int m_offset)
      Make matrix an identity matrix
      static float[] makeLookAt​(float[] m, int m_offset, float[] eye, int eye_offset, float[] center, int center_offset, float[] up, int up_offset, float[] mat4Tmp)
      Make given matrix the look-at matrix based on given parameters.
      static float[] makeOrtho​(float[] m, int m_offset, boolean initM, float left, float right, float bottom, float top, float zNear, float zFar)
      Make given matrix the orthogonal matrix based on given parameters.
      static float[] makePerspective​(float[] m, int m_off, boolean initM, float fovy_rad, float aspect, float zNear, float zFar)
      Make given matrix the perspective frustum matrix based on given parameters.
      static float[] makePerspective​(float[] m, int m_offset, boolean initM, FovHVHalves fovhv, float zNear, float zFar)
      Make given matrix the perspective frustum matrix based on given parameters.
      static float[] makePick​(float[] m, int m_offset, float x, float y, float deltaX, float deltaY, int[] viewport, int viewport_offset, float[] mat4Tmp)
      Make given matrix the pick matrix based on given parameters.
      static float[] makeRotationAxis​(float[] m, int m_offset, float angrad, float x, float y, float z, float[] tmpVec3f)
      Make a rotation matrix from the given axis and angle in radians.
      static float[] makeRotationEuler​(float[] m, int m_offset, float bankX, float headingY, float attitudeZ)
      Make a concatenated rotation matrix in column-major order from the given Euler rotation angles in radians.
      static float[] makeScale​(float[] m, boolean initM, float sx, float sy, float sz)
      Make a scale matrix in column-major order from the given axis factors
      static float[] makeScale​(float[] m, int m_offset, boolean initM, float sx, float sy, float sz)
      Make a scale matrix in column-major order from the given axis factors
      static float[] makeTranslation​(float[] m, boolean initM, float tx, float ty, float tz)
      Make a translation matrix in column-major order from the given axis deltas
      static float[] makeTranslation​(float[] m, int m_offset, boolean initM, float tx, float ty, float tz)
      Make a translation matrix in column-major order from the given axis deltas
      static boolean mapObjToWinCoords​(float objx, float objy, float objz, float[] mat4PMv, int[] viewport, int viewport_offset, float[] win_pos, int win_pos_offset, float[] vec4Tmp1, float[] vec4Tmp2)
      Map object coordinates to window coordinates.
      static boolean mapObjToWinCoords​(float objx, float objy, float objz, float[] modelMatrix, int modelMatrix_offset, float[] projMatrix, int projMatrix_offset, int[] viewport, int viewport_offset, float[] win_pos, int win_pos_offset, float[] vec4Tmp1, float[] vec4Tmp2)
      Map object coordinates to window coordinates.
      static boolean mapWinToObjCoords​(float winx, float winy, float winz, float[] mat4PMvI, int[] viewport, int viewport_offset, float[] obj_pos, int obj_pos_offset, float[] vec4Tmp1, float[] vec4Tmp2)
      Map window coordinates to object coordinates.
      static boolean mapWinToObjCoords​(float winx, float winy, float winz, float[] modelMatrix, int modelMatrix_offset, float[] projMatrix, int projMatrix_offset, int[] viewport, int viewport_offset, float[] obj_pos, int obj_pos_offset, float[] mat4Tmp1, float[] mat4Tmp2)
      Map window coordinates to object coordinates.
      static boolean mapWinToObjCoords​(float winx, float winy, float winz1, float winz2, float[] mat4PMvI, int[] viewport, int viewport_offset, float[] obj1_pos, int obj1_pos_offset, float[] obj2_pos, int obj2_pos_offset, float[] vec4Tmp1, float[] vec4Tmp2)
      Map two window coordinates to two object coordinates, distinguished by their z component.
      static boolean mapWinToObjCoords​(float winx, float winy, float winz, float clipw, float[] modelMatrix, int modelMatrix_offset, float[] projMatrix, int projMatrix_offset, int[] viewport, int viewport_offset, float near, float far, float[] obj_pos, int obj_pos_offset, float[] mat4Tmp1, float[] mat4Tmp2)
      Map window coordinates to object coordinates.
      static boolean mapWinToRay​(float winx, float winy, float winz0, float winz1, float[] modelMatrix, int modelMatrix_offset, float[] projMatrix, int projMatrix_offset, int[] viewport, int viewport_offset, Ray ray, float[] mat4Tmp1, float[] mat4Tmp2, float[] vec4Tmp2)
      Map two window coordinates w/ shared X/Y and distinctive Z to a Ray.
      static float matrixDeterminant​(float[] m)
      Returns the determinant of the given matrix
      static float matrixDeterminant​(float[] m, int m_offset)
      Returns the determinant of the given matrix
      static StringBuilder matrixRowToString​(StringBuilder sb, String f, float[] a, int aOffset, int rows, int columns, boolean rowMajorOrder, int row)  
      static StringBuilder matrixRowToString​(StringBuilder sb, String f, FloatBuffer a, int aOffset, int rows, int columns, boolean rowMajorOrder, int row)  
      static StringBuilder matrixToString​(StringBuilder sb, String rowPrefix, String f, float[] a, int aOffset, float[] b, int bOffset, int rows, int columns, boolean rowMajorOrder)  
      static StringBuilder matrixToString​(StringBuilder sb, String rowPrefix, String f, float[] a, int aOffset, int rows, int columns, boolean rowMajorOrder)  
      static StringBuilder matrixToString​(StringBuilder sb, String rowPrefix, String f, FloatBuffer a, int aOffset, int rows, int columns, boolean rowMajorOrder)  
      static StringBuilder matrixToString​(StringBuilder sb, String rowPrefix, String f, FloatBuffer a, int aOffset, FloatBuffer b, int bOffset, int rows, int columns, boolean rowMajorOrder)  
      static float[] multMatrix​(float[] a, float[] b)
      Multiply matrix: [a] = [a] x [b]
      static float[] multMatrix​(float[] a, float[] b, float[] d)
      Multiply matrix: [d] = [a] x [b]
      static float[] multMatrix​(float[] a, int a_off, float[] b, int b_off)
      Multiply matrix: [a] = [a] x [b]
      static float[] multMatrix​(float[] a, int a_off, float[] b, int b_off, float[] d, int d_off)
      Multiply matrix: [d] = [a] x [b]
      static void multMatrix​(FloatBuffer a, FloatBuffer b)
      Multiply matrix: [a] = [a] x [b]
      static void multMatrix​(FloatBuffer a, FloatBuffer b, float[] d)
      Multiply matrix: [d] = [a] x [b]
      static float[] multMatrixVec​(float[] m_in, float[] v_in, float[] v_out)  
      static float[] multMatrixVec​(float[] m_in, int m_in_off, float[] v_in, int v_in_off, float[] v_out, int v_out_off)  
      static void multMatrixVec​(FloatBuffer m_in, float[] v_in, float[] v_out)  
      static float pow​(float a, float b)  
      static float sin​(float a)  
      static float sqrt​(float a)  
      static float tan​(float a)  
      static float[] transposeMatrix​(float[] msrc, float[] mres)
      Transpose the given matrix.
      static float[] transposeMatrix​(float[] msrc, int msrc_offset, float[] mres, int mres_offset)
      Transpose the given matrix.
    • Field Detail

      • DEBUG

        public static final boolean DEBUG
      • PI

        public static final float PI
        The value PI, i.e. 180 degrees in radians.
        See Also:
        Constant Field Values
      • TWO_PI

        public static final float TWO_PI
        The value 2PI, i.e. 360 degrees in radians.
        See Also:
        Constant Field Values
      • HALF_PI

        public static final float HALF_PI
        The value PI/2, i.e. 90 degrees in radians.
        See Also:
        Constant Field Values
      • QUARTER_PI

        public static final float QUARTER_PI
        The value PI/4, i.e. 45 degrees in radians.
        See Also:
        Constant Field Values
      • EPSILON

        public static final float EPSILON
        Epsilon for floating point 1.1920928955078125E-7f, as once computed via getMachineEpsilon() on an AMD-64 CPU.

        Definition of machine epsilon guarantees that:

                1.0f + EPSILON != 1.0f
         
        In other words: machEps is the maximum relative error of the chosen rounding procedure.

        A number can be considered zero if it is in the range (or in the set):

            MaybeZeroSet e ]-machEps .. machEps[  (exclusive)
         
        While comparing floating point values, machEps allows to clip the relative error:
            boolean isZero    = afloat < EPSILON;
            boolean isNotZero = afloat >= EPSILON;
        
            boolean isEqual    = abs(bfloat - afloat) < EPSILON;
            boolean isNotEqual = abs(bfloat - afloat) >= EPSILON;
         

        See Also:
        isEqual(float, float, float), isZero(float, float), Constant Field Values
      • INV_DEVIANCE

        public static final float INV_DEVIANCE
        Inversion Epsilon, used with equals method to determine if two inverted matrices are close enough to be considered equal.

        Using 9.999999747378752E-6f, which is ~100 times EPSILON.

        See Also:
        Constant Field Values
    • Constructor Detail

      • FloatUtil

        public FloatUtil()
    • Method Detail

      • makeIdentity

        public static float[] makeIdentity​(float[] m,
                                           int m_offset)
        Make matrix an identity matrix
        Parameters:
        m - 4x4 matrix in column-major order (also result)
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        Returns:
        given matrix for chaining
      • makeIdentity

        public static float[] makeIdentity​(float[] m)
        Make matrix an identity matrix
        Parameters:
        m - 4x4 matrix in column-major order (also result)
        Returns:
        given matrix for chaining
      • makeTranslation

        public static float[] makeTranslation​(float[] m,
                                              int m_offset,
                                              boolean initM,
                                              float tx,
                                              float ty,
                                              float tz)
        Make a translation matrix in column-major order from the given axis deltas
              Translation matrix (Column Order):
              1 0 0 0
              0 1 0 0
              0 0 1 0
              x y z 1
         

        All matrix fields are only set if initM is true.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        initM - if true, given matrix will be initialized w/ identity matrix, otherwise only the diagonal and last-row is set. The latter can be utilized to share a once identity set matrix for scaling and translation, while leaving the other fields untouched for performance reasons.
        Returns:
        given matrix for chaining
      • makeTranslation

        public static float[] makeTranslation​(float[] m,
                                              boolean initM,
                                              float tx,
                                              float ty,
                                              float tz)
        Make a translation matrix in column-major order from the given axis deltas
              Translation matrix (Column Order):
              1 0 0 0
              0 1 0 0
              0 0 1 0
              x y z 1
         

        All matrix fields are only set if initM is true.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        initM - if true, given matrix will be initialized w/ identity matrix, otherwise only the diagonal and last-row is set. The latter can be utilized to share a once identity set matrix for scaling and translation, while leaving the other fields untouched for performance reasons.
        Returns:
        given matrix for chaining
      • makeScale

        public static float[] makeScale​(float[] m,
                                        int m_offset,
                                        boolean initM,
                                        float sx,
                                        float sy,
                                        float sz)
        Make a scale matrix in column-major order from the given axis factors
              Scale matrix (Any Order):
              x 0 0 0
              0 y 0 0
              0 0 z 0
              0 0 0 1
         

        All matrix fields are only set if initM is true.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        initM - if true, given matrix will be initialized w/ identity matrix, otherwise only the diagonal and last-row is set. The latter can be utilized to share a once identity set matrix for scaling and translation, while leaving the other fields untouched for performance reasons.
        Returns:
        given matrix for chaining
      • makeScale

        public static float[] makeScale​(float[] m,
                                        boolean initM,
                                        float sx,
                                        float sy,
                                        float sz)
        Make a scale matrix in column-major order from the given axis factors
              Scale matrix (Any Order):
              x 0 0 0
              0 y 0 0
              0 0 z 0
              0 0 0 1
         

        All matrix fields are only set if initM is true.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        initM - if true, given matrix will be initialized w/ identity matrix, otherwise only the diagonal and last-row is set. The latter can be utilized to share a once identity set matrix for scaling and translation, while leaving the other fields untouched for performance reasons.
        Returns:
        given matrix for chaining
      • makeRotationAxis

        public static float[] makeRotationAxis​(float[] m,
                                               int m_offset,
                                               float angrad,
                                               float x,
                                               float y,
                                               float z,
                                               float[] tmpVec3f)
        Make a rotation matrix from the given axis and angle in radians.
                Rotation matrix (Column Order):
                xx(1-c)+c  xy(1-c)+zs xz(1-c)-ys 0
                xy(1-c)-zs yy(1-c)+c  yz(1-c)+xs 0
                xz(1-c)+ys yz(1-c)-xs zz(1-c)+c  0
                0          0          0          1
         

        All matrix fields are set.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        Returns:
        given matrix for chaining
        See Also:
        Matrix-FAQ Q38
      • makeRotationEuler

        public static float[] makeRotationEuler​(float[] m,
                                                int m_offset,
                                                float bankX,
                                                float headingY,
                                                float attitudeZ)
        Make a concatenated rotation matrix in column-major order from the given Euler rotation angles in radians.

        The rotations are applied in the given order:

        • y - heading
        • z - attitude
        • x - bank

        All matrix fields are set.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        bankX - the Euler pitch angle in radians. (rotation about the X axis)
        headingY - the Euler yaw angle in radians. (rotation about the Y axis)
        attitudeZ - the Euler roll angle in radians. (rotation about the Z axis)
        Returns:
        given matrix for chaining

        Implementation does not use Quaternion and hence is exposed to Gimbal-Lock

        See Also:
        Matrix-FAQ Q36, euclideanspace.com-eulerToMatrix
      • makeOrtho

        public static float[] makeOrtho​(float[] m,
                                        int m_offset,
                                        boolean initM,
                                        float left,
                                        float right,
                                        float bottom,
                                        float top,
                                        float zNear,
                                        float zFar)
        Make given matrix the orthogonal matrix based on given parameters.
              Ortho matrix (Column Order):
              2/dx  0     0    0
              0     2/dy  0    0
              0     0     2/dz 0
              tx    ty    tz   1
         

        All matrix fields are only set if initM is true.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        initM - if true, given matrix will be initialized w/ identity matrix, otherwise only the orthogonal fields are set.
        left -
        right -
        bottom -
        top -
        zNear -
        zFar -
        Returns:
        given matrix for chaining
      • makeFrustum

        public static float[] makeFrustum​(float[] m,
                                          int m_offset,
                                          boolean initM,
                                          float left,
                                          float right,
                                          float bottom,
                                          float top,
                                          float zNear,
                                          float zFar)
                                   throws GLException
        Make given matrix the frustum matrix based on given parameters.
              Frustum matrix (Column Order):
              2*zNear/dx   0          0   0
              0            2*zNear/dy 0   0
              A            B          C  -1
              0            0          D   0
         

        All matrix fields are only set if initM is true.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        initM - if true, given matrix will be initialized w/ identity matrix, otherwise only the frustum fields are set.
        left -
        right -
        bottom -
        top -
        zNear -
        zFar -
        Returns:
        given matrix for chaining
        Throws:
        GLException - if zNear <= 0 or zFar <= zNear or left == right, or bottom == top.
      • makePerspective

        public static float[] makePerspective​(float[] m,
                                              int m_off,
                                              boolean initM,
                                              float fovy_rad,
                                              float aspect,
                                              float zNear,
                                              float zFar)
                                       throws GLException
        Make given matrix the perspective frustum matrix based on given parameters.

        All matrix fields are only set if initM is true.

        Parameters:
        m - 4x4 matrix in column-major order (also result)
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        initM - if true, given matrix will be initialized w/ identity matrix, otherwise only the frustum fields are set.
        fovy_rad - angle in radians
        aspect - aspect ratio width / height
        zNear -
        zFar -
        Returns:
        given matrix for chaining
        Throws:
        GLException - if zNear <= 0 or zFar <= zNear
        See Also:
        makeFrustum(float[], int, boolean, float, float, float, float, float, float)
      • makeLookAt

        public static float[] makeLookAt​(float[] m,
                                         int m_offset,
                                         float[] eye,
                                         int eye_offset,
                                         float[] center,
                                         int center_offset,
                                         float[] up,
                                         int up_offset,
                                         float[] mat4Tmp)
        Make given matrix the look-at matrix based on given parameters.

        Consist out of two matrix multiplications:

           R = L x T,
           with L for look-at matrix and
                T for eye translation.
        
           Result R can be utilized for modelview multiplication, i.e.
                  M = M x R,
                  with M being the modelview matrix.
         

        All matrix fields are set.

        Parameters:
        m - 4x4 matrix in column-major order, result only
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        eye - 3 component eye vector
        eye_offset -
        center - 3 component center vector
        center_offset -
        up - 3 component up vector
        up_offset -
        mat4Tmp - temp float[16] storage
        Returns:
        given matrix m for chaining
      • makePick

        public static float[] makePick​(float[] m,
                                       int m_offset,
                                       float x,
                                       float y,
                                       float deltaX,
                                       float deltaY,
                                       int[] viewport,
                                       int viewport_offset,
                                       float[] mat4Tmp)
        Make given matrix the pick matrix based on given parameters.

        Traditional gluPickMatrix implementation.

        Consist out of two matrix multiplications:

           R = T x S,
           with T for viewport translation matrix and
                S for viewport scale matrix.
        
           Result R can be utilized for projection multiplication, i.e.
                  P = P x R,
                  with P being the projection matrix.
         

        To effectively use the generated pick matrix for picking, call makePick and multiply a custom perspective matrix by this pick matrix. Then you may load the result onto the perspective matrix stack.

        All matrix fields are set.

        Parameters:
        m - 4x4 matrix in column-major order, result only
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        x - the center x-component of a picking region in window coordinates
        y - the center y-component of a picking region in window coordinates
        deltaX - the width of the picking region in window coordinates.
        deltaY - the height of the picking region in window coordinates.
        viewport - 4 component viewport vector
        viewport_offset -
        mat4Tmp - temp float[16] storage
        Returns:
        given matrix m for chaining or null if either delta value is <= zero.
      • transposeMatrix

        public static float[] transposeMatrix​(float[] msrc,
                                              int msrc_offset,
                                              float[] mres,
                                              int mres_offset)
        Transpose the given matrix.
        Parameters:
        msrc - 4x4 matrix in column-major order, the source
        msrc_offset - offset in given array msrc, i.e. start of the 4x4 matrix
        mres - 4x4 matrix in column-major order, the result
        mres_offset - offset in given array mres, i.e. start of the 4x4 matrix
        Returns:
        given result matrix mres for chaining
      • transposeMatrix

        public static float[] transposeMatrix​(float[] msrc,
                                              float[] mres)
        Transpose the given matrix.
        Parameters:
        msrc - 4x4 matrix in column-major order, the source
        mres - 4x4 matrix in column-major order, the result
        Returns:
        given result matrix mres for chaining
      • matrixDeterminant

        public static float matrixDeterminant​(float[] m,
                                              int m_offset)
        Returns the determinant of the given matrix
        Parameters:
        m - 4x4 matrix in column-major order, the source
        m_offset - offset in given array m, i.e. start of the 4x4 matrix
        Returns:
        the matrix determinant
      • matrixDeterminant

        public static float matrixDeterminant​(float[] m)
        Returns the determinant of the given matrix
        Parameters:
        m - 4x4 matrix in column-major order, the source
        Returns:
        the matrix determinant
      • invertMatrix

        public static float[] invertMatrix​(float[] msrc,
                                           int msrc_offset,
                                           float[] mres,
                                           int mres_offset)
        Invert the given matrix.

        Returns null if inversion is not possible, e.g. matrix is singular due to a bad matrix.

        Parameters:
        msrc - 4x4 matrix in column-major order, the source
        msrc_offset - offset in given array msrc, i.e. start of the 4x4 matrix
        mres - 4x4 matrix in column-major order, the result - may be msrc (in-place)
        mres_offset - offset in given array mres, i.e. start of the 4x4 matrix - may be msrc_offset (in-place)
        Returns:
        given result matrix mres for chaining if successful, otherwise null. See above.
      • invertMatrix

        public static float[] invertMatrix​(float[] msrc,
                                           float[] mres)
        Invert the given matrix.

        Returns null if inversion is not possible, e.g. matrix is singular due to a bad matrix.

        Parameters:
        msrc - 4x4 matrix in column-major order, the source
        mres - 4x4 matrix in column-major order, the result - may be msrc (in-place)
        Returns:
        given result matrix mres for chaining if successful, otherwise null. See above.
      • mapObjToWinCoords

        public static boolean mapObjToWinCoords​(float objx,
                                                float objy,
                                                float objz,
                                                float[] modelMatrix,
                                                int modelMatrix_offset,
                                                float[] projMatrix,
                                                int projMatrix_offset,
                                                int[] viewport,
                                                int viewport_offset,
                                                float[] win_pos,
                                                int win_pos_offset,
                                                float[] vec4Tmp1,
                                                float[] vec4Tmp2)
        Map object coordinates to window coordinates.

        Traditional gluProject implementation.

        Parameters:
        objx -
        objy -
        objz -
        modelMatrix - 4x4 modelview matrix
        modelMatrix_offset -
        projMatrix - 4x4 projection matrix
        projMatrix_offset -
        viewport - 4 component viewport vector
        viewport_offset -
        win_pos - 3 component window coordinate, the result
        win_pos_offset -
        vec4Tmp1 - 4 component vector for temp storage
        vec4Tmp2 - 4 component vector for temp storage
        Returns:
        true if successful, otherwise false (z is 1)
      • mapObjToWinCoords

        public static boolean mapObjToWinCoords​(float objx,
                                                float objy,
                                                float objz,
                                                float[] mat4PMv,
                                                int[] viewport,
                                                int viewport_offset,
                                                float[] win_pos,
                                                int win_pos_offset,
                                                float[] vec4Tmp1,
                                                float[] vec4Tmp2)
        Map object coordinates to window coordinates.

        Traditional gluProject implementation.

        Parameters:
        objx -
        objy -
        objz -
        mat4PMv - [projection] x [modelview] matrix, i.e. P x Mv
        viewport - 4 component viewport vector
        viewport_offset -
        win_pos - 3 component window coordinate, the result
        win_pos_offset -
        vec4Tmp1 - 4 component vector for temp storage
        vec4Tmp2 - 4 component vector for temp storage
        Returns:
        true if successful, otherwise false (z is 1)
      • mapWinToObjCoords

        public static boolean mapWinToObjCoords​(float winx,
                                                float winy,
                                                float winz,
                                                float[] modelMatrix,
                                                int modelMatrix_offset,
                                                float[] projMatrix,
                                                int projMatrix_offset,
                                                int[] viewport,
                                                int viewport_offset,
                                                float[] obj_pos,
                                                int obj_pos_offset,
                                                float[] mat4Tmp1,
                                                float[] mat4Tmp2)
        Map window coordinates to object coordinates.

        Traditional gluUnProject implementation.

        Parameters:
        winx -
        winy -
        winz -
        modelMatrix - 4x4 modelview matrix
        modelMatrix_offset -
        projMatrix - 4x4 projection matrix
        projMatrix_offset -
        viewport - 4 component viewport vector
        viewport_offset -
        obj_pos - 3 component object coordinate, the result
        obj_pos_offset -
        mat4Tmp1 - 16 component matrix for temp storage
        mat4Tmp2 - 16 component matrix for temp storage
        Returns:
        true if successful, otherwise false (failed to invert matrix, or becomes infinity due to zero z)
      • mapWinToObjCoords

        public static boolean mapWinToObjCoords​(float winx,
                                                float winy,
                                                float winz,
                                                float[] mat4PMvI,
                                                int[] viewport,
                                                int viewport_offset,
                                                float[] obj_pos,
                                                int obj_pos_offset,
                                                float[] vec4Tmp1,
                                                float[] vec4Tmp2)
        Map window coordinates to object coordinates.

        Traditional gluUnProject implementation.

        Parameters:
        winx -
        winy -
        winz -
        mat4PMvI - inverse [projection] x [modelview] matrix, i.e. Inv(P x Mv)
        viewport - 4 component viewport vector
        viewport_offset -
        obj_pos - 3 component object coordinate, the result
        obj_pos_offset -
        vec4Tmp1 - 4 component vector for temp storage
        vec4Tmp2 - 4 component vector for temp storage
        Returns:
        true if successful, otherwise false (failed to invert matrix, or becomes infinity due to zero z)
      • mapWinToObjCoords

        public static boolean mapWinToObjCoords​(float winx,
                                                float winy,
                                                float winz1,
                                                float winz2,
                                                float[] mat4PMvI,
                                                int[] viewport,
                                                int viewport_offset,
                                                float[] obj1_pos,
                                                int obj1_pos_offset,
                                                float[] obj2_pos,
                                                int obj2_pos_offset,
                                                float[] vec4Tmp1,
                                                float[] vec4Tmp2)
        Map two window coordinates to two object coordinates, distinguished by their z component.
        Parameters:
        winx -
        winy -
        winz1 -
        winz2 -
        mat4PMvI - inverse [projection] x [modelview] matrix, i.e. Inv(P x Mv)
        viewport - 4 component viewport vector
        viewport_offset -
        obj1_pos - 3 component object coordinate, the result for winz1
        obj1_pos_offset -
        obj2_pos - 3 component object coordinate, the result for winz2
        obj2_pos_offset -
        vec4Tmp1 - 4 component vector for temp storage
        vec4Tmp2 - 4 component vector for temp storage
        Returns:
        true if successful, otherwise false (failed to invert matrix, or becomes infinity due to zero z)
      • mapWinToObjCoords

        public static boolean mapWinToObjCoords​(float winx,
                                                float winy,
                                                float winz,
                                                float clipw,
                                                float[] modelMatrix,
                                                int modelMatrix_offset,
                                                float[] projMatrix,
                                                int projMatrix_offset,
                                                int[] viewport,
                                                int viewport_offset,
                                                float near,
                                                float far,
                                                float[] obj_pos,
                                                int obj_pos_offset,
                                                float[] mat4Tmp1,
                                                float[] mat4Tmp2)
        Map window coordinates to object coordinates.

        Traditional gluUnProject4 implementation.

        Parameters:
        winx -
        winy -
        winz -
        clipw -
        modelMatrix - 4x4 modelview matrix
        modelMatrix_offset -
        projMatrix - 4x4 projection matrix
        projMatrix_offset -
        viewport - 4 component viewport vector
        viewport_offset -
        near -
        far -
        obj_pos - 4 component object coordinate, the result
        obj_pos_offset -
        mat4Tmp1 - 16 component matrix for temp storage
        mat4Tmp2 - 16 component matrix for temp storage
        Returns:
        true if successful, otherwise false (failed to invert matrix, or becomes infinity due to zero z)
      • mapWinToRay

        public static boolean mapWinToRay​(float winx,
                                          float winy,
                                          float winz0,
                                          float winz1,
                                          float[] modelMatrix,
                                          int modelMatrix_offset,
                                          float[] projMatrix,
                                          int projMatrix_offset,
                                          int[] viewport,
                                          int viewport_offset,
                                          Ray ray,
                                          float[] mat4Tmp1,
                                          float[] mat4Tmp2,
                                          float[] vec4Tmp2)
        Map two window coordinates w/ shared X/Y and distinctive Z to a Ray. The resulting Ray maybe used for picking using a bounding box.

        Notes for picking winz0 and winz1:

        Parameters:
        winx -
        winy -
        winz0 -
        winz1 -
        modelMatrix - 4x4 modelview matrix
        modelMatrix_offset -
        projMatrix - 4x4 projection matrix
        projMatrix_offset -
        viewport - 4 component viewport vector
        viewport_offset -
        ray - storage for the resulting Ray
        mat4Tmp1 - 16 component matrix for temp storage
        mat4Tmp2 - 16 component matrix for temp storage
        vec4Tmp2 - 4 component vector for temp storage
        Returns:
        true if successful, otherwise false (failed to invert matrix, or becomes z is infinity)
      • multMatrix

        public static float[] multMatrix​(float[] a,
                                         int a_off,
                                         float[] b,
                                         int b_off,
                                         float[] d,
                                         int d_off)
        Multiply matrix: [d] = [a] x [b]
        Parameters:
        a - 4x4 matrix in column-major order
        b - 4x4 matrix in column-major order
        d - result a*b in column-major order
        Returns:
        given result matrix d for chaining
      • multMatrix

        public static float[] multMatrix​(float[] a,
                                         float[] b,
                                         float[] d)
        Multiply matrix: [d] = [a] x [b]
        Parameters:
        a - 4x4 matrix in column-major order
        b - 4x4 matrix in column-major order
        d - result a*b in column-major order
        Returns:
        given result matrix d for chaining
      • multMatrix

        public static float[] multMatrix​(float[] a,
                                         int a_off,
                                         float[] b,
                                         int b_off)
        Multiply matrix: [a] = [a] x [b]
        Parameters:
        a - 4x4 matrix in column-major order (also result)
        b - 4x4 matrix in column-major order
        Returns:
        given result matrix a for chaining
      • multMatrix

        public static float[] multMatrix​(float[] a,
                                         float[] b)
        Multiply matrix: [a] = [a] x [b]
        Parameters:
        a - 4x4 matrix in column-major order (also result)
        b - 4x4 matrix in column-major order
        Returns:
        given result matrix a for chaining
      • multMatrix

        public static void multMatrix​(FloatBuffer a,
                                      FloatBuffer b,
                                      float[] d)
        Multiply matrix: [d] = [a] x [b]
        Parameters:
        a - 4x4 matrix in column-major order
        b - 4x4 matrix in column-major order
        d - result a*b in column-major order
      • multMatrix

        public static void multMatrix​(FloatBuffer a,
                                      FloatBuffer b)
        Multiply matrix: [a] = [a] x [b]
        Parameters:
        a - 4x4 matrix in column-major order (also result)
        b - 4x4 matrix in column-major order
      • multMatrixVec

        public static float[] multMatrixVec​(float[] m_in,
                                            int m_in_off,
                                            float[] v_in,
                                            int v_in_off,
                                            float[] v_out,
                                            int v_out_off)
        Parameters:
        m_in - 4x4 matrix in column-major order
        m_in_off -
        v_in - 4-component column-vector
        v_out - m_in * v_in
        Returns:
        given result vector v_out for chaining
      • multMatrixVec

        public static float[] multMatrixVec​(float[] m_in,
                                            float[] v_in,
                                            float[] v_out)
        Parameters:
        m_in - 4x4 matrix in column-major order
        m_in_off -
        v_in - 4-component column-vector
        v_out - m_in * v_in
        Returns:
        given result vector v_out for chaining
      • multMatrixVec

        public static void multMatrixVec​(FloatBuffer m_in,
                                         float[] v_in,
                                         float[] v_out)
        Parameters:
        m_in - 4x4 matrix in column-major order
        v_in - 4-component column-vector
        v_out - m_in * v_in
      • copyMatrixColumn

        public static float[] copyMatrixColumn​(float[] m_in,
                                               int m_in_off,
                                               int column,
                                               float[] v_out,
                                               int v_out_off)
        Copy the named column of the given column-major matrix to v_out.

        v_out may be 3 or 4 components long, hence the 4th row may not be stored.

        Parameters:
        m_in - input column-major matrix
        m_in_off - offset to input matrix
        column - named column to copy
        v_out - the column-vector storage, at least 3 components long
        v_out_off - offset to storage
        Returns:
        given result vector v_out for chaining
      • copyMatrixRow

        public static float[] copyMatrixRow​(float[] m_in,
                                            int m_in_off,
                                            int row,
                                            float[] v_out,
                                            int v_out_off)
        Copy the named row of the given column-major matrix to v_out.

        v_out may be 3 or 4 components long, hence the 4th column may not be stored.

        Parameters:
        m_in - input column-major matrix
        m_in_off - offset to input matrix
        row - named row to copy
        v_out - the row-vector storage, at least 3 components long
        v_out_off - offset to storage
        Returns:
        given result vector v_out for chaining
      • matrixRowToString

        public static StringBuilder matrixRowToString​(StringBuilder sb,
                                                      String f,
                                                      FloatBuffer a,
                                                      int aOffset,
                                                      int rows,
                                                      int columns,
                                                      boolean rowMajorOrder,
                                                      int row)
        Parameters:
        sb - optional passed StringBuilder instance to be used
        f - the format string of one floating point, i.e. "%10.5f", see Formatter
        a - mxn matrix (rows x columns)
        aOffset - offset to a's current position
        rows -
        columns -
        rowMajorOrder - if true floats are layed out in row-major-order, otherwise column-major-order (OpenGL)
        row - row number to print
        Returns:
        matrix row string representation
      • matrixRowToString

        public static StringBuilder matrixRowToString​(StringBuilder sb,
                                                      String f,
                                                      float[] a,
                                                      int aOffset,
                                                      int rows,
                                                      int columns,
                                                      boolean rowMajorOrder,
                                                      int row)
        Parameters:
        sb - optional passed StringBuilder instance to be used
        f - the format string of one floating point, i.e. "%10.5f", see Formatter
        a - mxn matrix (rows x columns)
        aOffset - offset to a's current position
        rows -
        columns -
        rowMajorOrder - if true floats are layed out in row-major-order, otherwise column-major-order (OpenGL)
        row - row number to print
        Returns:
        matrix row string representation
      • matrixToString

        public static StringBuilder matrixToString​(StringBuilder sb,
                                                   String rowPrefix,
                                                   String f,
                                                   FloatBuffer a,
                                                   int aOffset,
                                                   int rows,
                                                   int columns,
                                                   boolean rowMajorOrder)
        Parameters:
        sb - optional passed StringBuilder instance to be used
        rowPrefix - optional prefix for each row
        f - the format string of one floating point, i.e. "%10.5f", see Formatter
        a - mxn matrix (rows x columns)
        aOffset - offset to a's current position
        rows -
        columns -
        rowMajorOrder - if true floats are layed out in row-major-order, otherwise column-major-order (OpenGL)
        Returns:
        matrix string representation
      • matrixToString

        public static StringBuilder matrixToString​(StringBuilder sb,
                                                   String rowPrefix,
                                                   String f,
                                                   float[] a,
                                                   int aOffset,
                                                   int rows,
                                                   int columns,
                                                   boolean rowMajorOrder)
        Parameters:
        sb - optional passed StringBuilder instance to be used
        rowPrefix - optional prefix for each row
        f - the format string of one floating point, i.e. "%10.5f", see Formatter
        a - mxn matrix (rows x columns)
        aOffset - offset to a's current position
        rows -
        columns -
        rowMajorOrder - if true floats are layed out in row-major-order, otherwise column-major-order (OpenGL)
        Returns:
        matrix string representation
      • matrixToString

        public static StringBuilder matrixToString​(StringBuilder sb,
                                                   String rowPrefix,
                                                   String f,
                                                   FloatBuffer a,
                                                   int aOffset,
                                                   FloatBuffer b,
                                                   int bOffset,
                                                   int rows,
                                                   int columns,
                                                   boolean rowMajorOrder)
        Parameters:
        sb - optional passed StringBuilder instance to be used
        rowPrefix - optional prefix for each row
        f - the format string of one floating point, i.e. "%10.5f", see Formatter
        a - 4x4 matrix in column major order (OpenGL)
        aOffset - offset to a's current position
        b - 4x4 matrix in column major order (OpenGL)
        bOffset - offset to a's current position
        rows -
        columns -
        rowMajorOrder - if true floats are layed out in row-major-order, otherwise column-major-order (OpenGL)
        Returns:
        side by side representation
      • matrixToString

        public static StringBuilder matrixToString​(StringBuilder sb,
                                                   String rowPrefix,
                                                   String f,
                                                   float[] a,
                                                   int aOffset,
                                                   float[] b,
                                                   int bOffset,
                                                   int rows,
                                                   int columns,
                                                   boolean rowMajorOrder)
        Parameters:
        sb - optional passed StringBuilder instance to be used
        rowPrefix - optional prefix for each row
        f - the format string of one floating point, i.e. "%10.5f", see Formatter
        a - 4x4 matrix in column major order (OpenGL)
        aOffset - offset to a's current position
        b - 4x4 matrix in column major order (OpenGL)
        bOffset - offset to a's current position
        rows -
        columns -
        rowMajorOrder - if true floats are layed out in row-major-order, otherwise column-major-order (OpenGL)
        Returns:
        side by side representation
      • getMachineEpsilon

        public static float getMachineEpsilon()
        Return computed machine Epsilon value.

        The machine Epsilon value is computed once.

        On a reference machine the result was EPSILON in 23 iterations.

        See Also:
        EPSILON
      • isEqual

        public static boolean isEqual​(float a,
                                      float b)
        Return true if both values are equal w/o regarding an epsilon.

        Implementation considers following corner cases:

        • NaN == NaN
        • +Inf == +Inf
        • -Inf == -Inf

        See Also:
        isEqual(float, float, float)
      • isEqual

        public static boolean isEqual​(float a,
                                      float b,
                                      float epsilon)
        Return true if both values are equal, i.e. their absolute delta < epsilon.

        Implementation considers following corner cases:

        • NaN == NaN
        • +Inf == +Inf
        • -Inf == -Inf

        See Also:
        EPSILON
      • compare

        public static int compare​(float a,
                                  float b)
        Return true if both values are equal w/o regarding an epsilon.

        Implementation considers following corner cases:

        • NaN == NaN
        • +Inf == +Inf
        • -Inf == -Inf
        • NaN > 0
        • +Inf > -Inf

        See Also:
        compare(float, float, float)
      • compare

        public static int compare​(float a,
                                  float b,
                                  float epsilon)
        Return true if both values are equal, i.e. their absolute delta < epsilon.

        Implementation considers following corner cases:

        • NaN == NaN
        • +Inf == +Inf
        • -Inf == -Inf
        • NaN > 0
        • +Inf > -Inf

        See Also:
        EPSILON
      • isZero

        public static boolean isZero​(float a,
                                     float epsilon)
        Return true if value is zero, i.e. it's absolute value < epsilon.
        See Also:
        EPSILON
      • abs

        public static float abs​(float a)
      • pow

        public static float pow​(float a,
                                float b)
      • sin

        public static float sin​(float a)
      • asin

        public static float asin​(float a)
      • cos

        public static float cos​(float a)
      • acos

        public static float acos​(float a)
      • tan

        public static float tan​(float a)
      • atan

        public static float atan​(float a)
      • atan2

        public static float atan2​(float y,
                                  float x)
      • sqrt

        public static float sqrt​(float a)
      • getZBufferEpsilon

        public static float getZBufferEpsilon​(int zBits,
                                              float z,
                                              float zNear)
        Returns resolution of Z buffer of given parameter, see Love Your Z-Buffer.
          return z * z / ( zNear * (1<<zBits) - z )
         
        Parameters:
        zBits - number of bits of Z precision, i.e. z-buffer depth
        z - distance from the eye to the object
        zNear - distance from eye to near clip plane
        Returns:
        smallest resolvable Z separation at this range.
      • getZBufferValue

        public static int getZBufferValue​(int zBits,
                                          float z,
                                          float zNear,
                                          float zFar)
        Returns Z buffer value of given parameter, see Love Your Z-Buffer.
          float a = zFar / ( zFar - zNear )
          float b = zFar * zNear / ( zNear - zFar )
          return (int) ( (1<<zBits) * ( a + b / z ) )
         
        Parameters:
        zBits - number of bits of Z precision, i.e. z-buffer depth
        z - distance from the eye to the object
        zNear - distance from eye to near clip plane
        zFar - distance from eye to far clip plane
        Returns:
        z buffer value
      • getOrthoWinZ

        public static float getOrthoWinZ​(float orthoZ,
                                         float zNear,
                                         float zFar)
        Returns orthogonal distance (1f/zNear-1f/orthoDist)/(1f/zNear-1f/zFar);