Class FloatUtil

java.lang.Object
com.jogamp.opengl.math.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 final boolean
     
    static final float
     
    static final float
    Epsilon for floating point 1.1920928955078125E-7f, as once computed via getMachineEpsilon() on an AMD-64 CPU.
    static final float
    The value PI/2, i.e.
    static final float
    Inversion Epsilon, used with equals method to determine if two inverted matrices are close enough to be considered equal.
    static final float
    The value PI, i.e.
    static final float
    The value PI/4, i.e.
    static final float
    The value PI^2.
    static final float
    The value 2PI, i.e.
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • Method Summary

    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
    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
    matrixRowToString(StringBuilder sb, String f, float[] a, int aOffset, int rows, int columns, boolean rowMajorOrder, int row)
     
    matrixRowToString(StringBuilder sb, String f, FloatBuffer a, int aOffset, int rows, int columns, boolean rowMajorOrder, int row)
    Deprecated.
    use on of the float[] variants
    matrixToString(StringBuilder sb, String rowPrefix, String f, float[] a, int aOffset, float[] b, int bOffset, int rows, int columns, boolean rowMajorOrder)
     
    matrixToString(StringBuilder sb, String rowPrefix, String f, float[] a, int aOffset, int rows, int columns, boolean rowMajorOrder)
     
    matrixToString(StringBuilder sb, String rowPrefix, String f, FloatBuffer a, int aOffset, int rows, int columns, boolean rowMajorOrder)
    Deprecated.
    use on of the float[] variants
    matrixToString(StringBuilder sb, String rowPrefix, String f, FloatBuffer a, int aOffset, FloatBuffer b, int bOffset, int rows, int columns, boolean rowMajorOrder)
    Deprecated.
    use on of the float[] variants
    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
    Deprecated.
    use on of the float[] variants
    static void
    multMatrix(FloatBuffer a, FloatBuffer b, float[] d)
    Deprecated.
    use on of the float[] variants
    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)
    Deprecated.
    use on of the float[] variants
    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.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • DEBUG

      public static final boolean DEBUG
    • E

      public static final float E
      See Also:
    • PI

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

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

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

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

      public static final float SQUARED_PI
      The value PI^2.
      See Also:
    • 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:
    • 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:
  • Constructor Details

    • FloatUtil

      public FloatUtil()
  • Method Details

    • 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:
    • 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:
    • 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:
    • makePerspective

      public static float[] makePerspective(float[] m, int m_offset, boolean initM, FovHVHalves fovhv, 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.
      fovhv - FovHVHalves field of view in both directions, may not be centered, either in radians or tangent
      zNear -
      zFar -
      Returns:
      given matrix for chaining
      Throws:
      GLException - if zNear <= 0 or zFar <= zNear
      See Also:
    • 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)
      Deprecated.
      use on of the float[] variants
      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)
      Deprecated.
      use on of the float[] variants
      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)
      Deprecated.
      use on of the float[] variants
      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)
      Deprecated.
      use on of the float[] variants
      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)
      Deprecated.
      use on of the float[] variants
      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)
      Deprecated.
      use on of the float[] variants
      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:
    • 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

      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:
    • 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

      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:
    • isZero

      public static boolean isZero(float a, float epsilon)
      Return true if value is zero, i.e. it's absolute value < epsilon.
      See Also:
    • 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);