Package icyllis.arc3d.core

# Class MathUtil

java.lang.Object
icyllis.arc3d.core.MathUtil

Direct Known Subclasses:
  `MathUtil`

public class MathUtil extends Object
Utility class that provides auxiliary operations.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final float`
  `DEG_TO_RAD`
  `static final float`
  `EPS`
  `static final float`
  `INV_EPS`
  `static final float`
  `INV_SQRT2`
  `static final float`
  `PATH_TOLERANCE`
  The tolerance (error) for 2D renderer.
  `static final float`
  `PI`
  `static final float`
  `PI_O_2`
  `static final float`
  `PI_O_3`
  `static final float`
  `PI_O_4`
  `static final float`
  `PI_O_6`
  `static final float`
  `PI2`
  `static final float`
  `PI3`
  `static final float`
  `PI4`
  `static final float`
  `RAD_TO_DEG`
  `static final float`
  `SQRT2`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `MathUtil()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static float`
  `acos(float a)`
  `static int`
  `align2(int a)`
  Aligns `a` up to 2 (half-word).
  `static long`
  `align2(long a)`
  Aligns `a` up to 2 (half-word).
  `static int`
  `align4(int a)`
  Aligns `a` up to 4 (word).
  `static long`
  `align4(long a)`
  Aligns `a` up to 4 (word).
  `static int`
  `align8(int a)`
  Aligns `a` up to 8 (double word).
  `static long`
  `align8(long a)`
  Aligns `a` up to 8 (double word).
  `static int`
  `alignDown(int a, int alignment)`
  `static int`
  `alignTo(int a, int alignment)`
  Aligns `a` up to a power of two.
  `static long`
  `alignTo(long a, long alignment)`
  Aligns `a` up to a power of two.
  `static int`
  `alignUp(int a, int alignment)`
  `static int`
  `alignUpPad(int a, int alignment)`
  `static float`
  `asin(float a)`
  `static float`
  `atan2(float a, float b)`
  `static double`
  `biLerp(double q00, double q10, double q01, double q11, double tx, double ty)`
  2D bilinear interpolation between four values (a rect).
  `static float`
  `biLerp(float q00, float q10, float q01, float q11, float tx, float ty)`
  2D bilinear interpolation between four values (a rect).
  `static int`
  `ceilLog16(float v)`
  Returns ceil(log2(sqrt(sqrt(x)))):
  `static int`
  `ceilLog2(float v)`
  Returns the log2 of the provided value, were that value to be rounded up to the next power of 2.
  `static int`
  `ceilLog2(int a)`
  Returns the log2 of `a`, were that value to be rounded up to the next power of 2.
  `static int`
  `ceilLog2(long a)`
  Returns the log2 of `a`, were that value to be rounded up to the next power of 2.
  `static int`
  `ceilLog4(float v)`
  Returns ceil(log2(sqrt(x))):
  `static int`
  `ceilPow2(int a)`
  Returns the smallest power of two greater than or equal to `a`.
  `static long`
  `ceilPow2(long a)`
  Returns the smallest power of two greater than or equal to `a`.
  `static double`
  `clamp(double x, double min, double max)`
  Clamps x between min and max, exactly.
  `static float`
  `clamp(float x, float min, float max)`
  Clamps x between min and max, exactly.
  `static int`
  `clamp(int x, int min, int max)`
  If x compares less than min, returns min; otherwise if max compares less than x, returns max; otherwise returns x.
  `static long`
  `clamp(long x, long min, long max)`
  If x compares less than min, returns min; otherwise if max compares less than x, returns max; otherwise returns x.
  `static float`
  `cos(float a)`
  `static short`
  `floatToHalf(float f)`
  Converts the specified single-precision float value into a half-precision float value.
  `static int`
  `floorLog2(int a)`
  Returns the log2 of `a`, were that value to be rounded down to the previous power of 2.
  `static int`
  `floorLog2(long a)`
  Returns the log2 of `a`, were that value to be rounded down to the previous power of 2.
  `static int`
  `floorPow2(int a)`
  Returns the largest power of two less than or equal to `a`.
  `static long`
  `floorPow2(long a)`
  Returns the largest power of two less than or equal to `a`.
  `static float`
  `frexp(float x, int[] exp)`
  Decomposes x into a floating-point significand in the range `(-1,-0.5], [0.5,1.0)`, and an integral exponent of two, such that
  `static float`
  `halfToFloat(short h)`
  Converts the specified half-precision float value into a single-precision float value.
  `static boolean`
  `isAlign2(int a)`
  Returns `true` if `a` is a multiple of 2.
  `static boolean`
  `isAlign2(long a)`
  Returns `true` if `a` is a multiple of 2.
  `static boolean`
  `isAlign4(int a)`
  Returns `true` if `a` is a multiple of 4.
  `static boolean`
  `isAlign4(long a)`
  Returns `true` if `a` is a multiple of 4.
  `static boolean`
  `isAlign8(int a)`
  Returns `true` if `a` is a multiple of 8.
  `static boolean`
  `isAlign8(long a)`
  Returns `true` if `a` is a multiple of 8.
  `static boolean`
  `isApproxEqual(float a, float b)`
  `static boolean`
  `isApproxEqual(float a, float b, float tolerance)`
  `static boolean`
  `isApproxZero(float a)`
  `static boolean`
  `isApproxZero(float a, float tolerance)`
  `static boolean`
  `isFinite(float[] values, int offset, int count)`
  Returns true if all values are finite.
  `static boolean`
  `isFinite(float v0, float v1, float v2, float v3)`
  Returns true if all values are finite.
  `static boolean`
  `isFinite(float v0, float v1, float v2, float v3, float v4, float v5)`
  Returns true if all values are finite.
  `static boolean`
  `isFinite(float v0, float v1, float v2, float v3, float v4, float v5, float v6, float v7, float v8)`
  Returns true if all values are finite.
  `static boolean`
  `isPow2(int a)`
  Returns `true` if `a` is a power of 2.
  `static boolean`
  `isPow2(long a)`
  Returns `true` if `a` is a power of 2.
  `static float`
  `ldexp(float x, int exp)`
  Composes a floating-point number from x and the corresponding integral exponent of two in exp, resulting
  `static double`
  `lerp(double a, double b, double t)`
  Linear interpolation between two values.
  `static float`
  `lerp(float a, float b, float t)`
  Linear interpolation between two values.
  `static double`
  `max(double a, double b, double c)`
  Component-wise maximum of a vector.
  `static double`
  `max(double a, double b, double c, double d)`
  Component-wise maximum of a vector.
  `static float`
  `max(float a, float b, float c)`
  Component-wise maximum of a vector.
  `static float`
  `max(float a, float b, float c, float d)`
  Component-wise maximum of a vector.
  `static float`
  `max3(float[] v)`
  Component-wise maximum of a vector.
  `static double`
  `median(double a, double b, double c)`
  Median of three numbers.
  `static float`
  `median(float a, float b, float c)`
  Median of three numbers.
  `static double`
  `min(double a, double b, double c)`
  Component-wise minimum of a vector.
  `static double`
  `min(double a, double b, double c, double d)`
  Component-wise minimum of a vector.
  `static float`
  `min(float a, float b, float c)`
  Component-wise minimum of a vector.
  `static float`
  `min(float a, float b, float c, float d)`
  Component-wise minimum of a vector.
  `static float`
  `min3(float[] v)`
  Component-wise minimum of a vector.
  `static double`
  `mix(double a, double b, double t)`
  Linear interpolation between two values, matches GLSL `mix` intrinsic function.
  `static float`
  `mix(float a, float b, float t)`
  Linear interpolation between two values, matches GLSL `mix` intrinsic function.
  `static double`
  `pin(double x, double min, double max)`
  Clamps x between min and max.
  `static float`
  `pin(float x, float min, float max)`
  Clamps x between min and max.
  `static float`
  `sin(float a)`
  `static float`
  `sqrt(float f)`
  `static float`
  `tan(float a)`
  `static double`
  `triLerp(double c000, double c100, double c010, double c110, double c001, double c101, double c011, double c111, double tx, double ty, double tz)`
  3D trilinear interpolation between eight values (a cuboid).
  `static float`
  `triLerp(float c000, float c100, float c010, float c110, float c001, float c101, float c011, float c111, float tx, float ty, float tz)`
  3D trilinear interpolation between eight values (a cuboid).

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### PI

    public static final float PI
    See Also:
      - Constant Field Values

  - ### PI2

    public static final float PI2
    See Also:
      - Constant Field Values

  - ### PI3

    public static final float PI3
    See Also:
      - Constant Field Values

  - ### PI4

    public static final float PI4
    See Also:
      - Constant Field Values

  - ### PI_O_2

    public static final float PI_O_2
    See Also:
      - Constant Field Values

  - ### PI_O_3

    public static final float PI_O_3
    See Also:
      - Constant Field Values

  - ### PI_O_4

    public static final float PI_O_4
    See Also:
      - Constant Field Values

  - ### PI_O_6

    public static final float PI_O_6
    See Also:
      - Constant Field Values

  - ### EPS

    public static final float EPS
    See Also:
      - Constant Field Values

  - ### INV_EPS

    public static final float INV_EPS
    See Also:
      - Constant Field Values

  - ### DEG_TO_RAD

    public static final float DEG_TO_RAD
    See Also:
      - Constant Field Values

  - ### RAD_TO_DEG

    public static final float RAD_TO_DEG
    See Also:
      - Constant Field Values

  - ### SQRT2

    public static final float SQRT2
    See Also:
      - Constant Field Values

  - ### INV_SQRT2

    public static final float INV_SQRT2
    See Also:
      - Constant Field Values

  - ### PATH_TOLERANCE

    public static final float PATH_TOLERANCE
    The tolerance (error) for 2D renderer.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### MathUtil

    protected MathUtil()

- ## Method Details

  - ### sin

    public static float sin(float a)

  - ### cos

    public static float cos(float a)

  - ### tan

    public static float tan(float a)

  - ### frexp

    public static float frexp(float x, int[] exp)
    Decomposes x into a floating-point significand in the range `(-1,-0.5], [0.5,1.0)`, and an integral exponent of two, such that

        x = significand * 2exponent

    If x is +- zero, +- Inf, or NaN, returns the input value as-is, and sets exp to 0.
    Parameters:
      `x` - the input value
      `exp` - the resulting exponent
    Returns:
      the resulting significand

  - ### ldexp

    public static float ldexp(float x, int exp)
    Composes a floating-point number from x and the corresponding integral exponent of two in exp, resulting

        significand * 2exponent

    If x is +- zero, +- Inf, or NaN, returns the input value as-is. If overflow or underflow occurs, returns a rounded value.
    Parameters:
      `x` - the input significand
      `exp` - the input exponent
    Returns:
      the resulting value

  - ### isApproxZero

    public static boolean isApproxZero(float a)
    Returns:
      true if `a` is approximately equal to zero

  - ### isApproxZero

    public static boolean isApproxZero(float a, float tolerance)
    Returns:
      true if `a` is approximately equal to zero within a given tolerance

  - ### isApproxEqual

    public static boolean isApproxEqual(float a, float b)
    Returns:
      true if `a` is approximately equal to `b`

  - ### isApproxEqual

    public static boolean isApproxEqual(float a, float b, float tolerance)
    Returns:
      true if `a` is approximately equal to `b` within a given tolerance

  - ### sqrt

    public static float sqrt(float f)

  - ### asin

    public static float asin(float a)

  - ### acos

    public static float acos(float a)

  - ### atan2

    public static float atan2(float a, float b)

  - ### clamp

    public static int clamp(int x, int min, int max)
    If x compares less than min, returns min; otherwise if max compares less than x, returns max; otherwise returns x.
    Returns:
      x clamped between min and max, inclusively.

  - ### clamp

    public static long clamp(long x, long min, long max)
    If x compares less than min, returns min; otherwise if max compares less than x, returns max; otherwise returns x.
    Returns:
      x clamped between min and max, inclusively.

  - ### clamp

    public static float clamp(float x, float min, float max)
    Clamps x between min and max, exactly. If x is NaN, returns NaN.
    Returns:
      x clamped between min and max

  - ### clamp

    public static double clamp(double x, double min, double max)
    Clamps x between min and max, exactly. If x is NaN, returns NaN.
    Returns:
      x clamped between min and max

  - ### pin

    public static float pin(float x, float min, float max)
    Clamps x between min and max. If x is NaN, returns min. Note the result is incorrect if min is negative zero.
    Returns:
      x clamped between min and max

  - ### pin

    public static double pin(double x, double min, double max)
    Clamps x between min and max. If x is NaN, returns min. Note the result is incorrect if min is negative zero.
    Returns:
      x clamped between min and max

  - ### min

    public static float min(float a, float b, float c)
    Component-wise minimum of a vector.

  - ### min3

    public static float min3(float[] v)
    Component-wise minimum of a vector.

  - ### min

    public static double min(double a, double b, double c)
    Component-wise minimum of a vector.

  - ### min

    public static float min(float a, float b, float c, float d)
    Component-wise minimum of a vector.

  - ### min

    public static double min(double a, double b, double c, double d)
    Component-wise minimum of a vector.

  - ### max

    public static float max(float a, float b, float c)
    Component-wise maximum of a vector.

  - ### max3

    public static float max3(float[] v)
    Component-wise maximum of a vector.

  - ### max

    public static double max(double a, double b, double c)
    Component-wise maximum of a vector.

  - ### max

    public static float max(float a, float b, float c, float d)
    Component-wise maximum of a vector.

  - ### max

    public static double max(double a, double b, double c, double d)
    Component-wise maximum of a vector.

  - ### median

    public static float median(float a, float b, float c)
    Median of three numbers.

  - ### median

    public static double median(double a, double b, double c)
    Median of three numbers.

  - ### lerp

    public static float lerp(float a, float b, float t)
    Linear interpolation between two values.

  - ### lerp

    public static double lerp(double a, double b, double t)
    Linear interpolation between two values.

  - ### mix

    public static float mix(float a, float b, float t)
    Linear interpolation between two values, matches GLSL `mix` intrinsic function. Slower than `lerp(float, float, float)` but without intermediate overflow or underflow.

  - ### mix

    public static double mix(double a, double b, double t)
    Linear interpolation between two values, matches GLSL `mix` intrinsic function. Slower than `lerp(double, double, double)` but without intermediate overflow or underflow.

  - ### biLerp

    public static float biLerp(float q00, float q10, float q01, float q11, float tx, float ty)
    2D bilinear interpolation between four values (a rect).

  - ### biLerp

    public static double biLerp(double q00, double q10, double q01, double q11, double tx, double ty)
    2D bilinear interpolation between four values (a rect).

  - ### triLerp

    public static float triLerp(float c000, float c100, float c010, float c110, float c001, float c101, float c011, float c111, float tx, float ty, float tz)
    3D trilinear interpolation between eight values (a cuboid).

  - ### triLerp

    public static double triLerp(double c000, double c100, double c010, double c110, double c001, double c101, double c011, double c111, double tx, double ty, double tz)
    3D trilinear interpolation between eight values (a cuboid).

  - ### isFinite

    public static boolean isFinite(float v0, float v1, float v2, float v3)
    Returns true if all values are finite.
    Returns:
      true if no member is infinite or NaN

  - ### isFinite

    public static boolean isFinite(float v0, float v1, float v2, float v3, float v4, float v5)
    Returns true if all values are finite.
    Returns:
      true if no member is infinite or NaN

  - ### isFinite

    public static boolean isFinite(float v0, float v1, float v2, float v3, float v4, float v5, float v6, float v7, float v8)
    Returns true if all values are finite.
    Returns:
      true if no member is infinite or NaN

  - ### isFinite

    public static boolean isFinite(float[] values, int offset, int count)
    Returns true if all values are finite.
    Returns:
      true if no member is infinite or NaN

  - ### align2

    public static int align2(int a)
    Aligns `a` up to 2 (half-word).

  - ### align4

    public static int align4(int a)
    Aligns `a` up to 4 (word).

  - ### align8

    public static int align8(int a)
    Aligns `a` up to 8 (double word).

  - ### align2

    public static long align2(long a)
    Aligns `a` up to 2 (half-word).

  - ### align4

    public static long align4(long a)
    Aligns `a` up to 4 (word).

  - ### align8

    public static long align8(long a)
    Aligns `a` up to 8 (double word).

  - ### isAlign2

    public static boolean isAlign2(int a)
    Returns `true` if `a` is a multiple of 2. Asserts `a >= 0`.

  - ### isAlign4

    public static boolean isAlign4(int a)
    Returns `true` if `a` is a multiple of 4. Asserts `a >= 0`.

  - ### isAlign8

    public static boolean isAlign8(int a)
    Returns `true` if `a` is a multiple of 8. Asserts `a >= 0`.

  - ### isAlign2

    public static boolean isAlign2(long a)
    Returns `true` if `a` is a multiple of 2. Asserts `a >= 0`.

  - ### isAlign4

    public static boolean isAlign4(long a)
    Returns `true` if `a` is a multiple of 4. Asserts `a >= 0`.

  - ### isAlign8

    public static boolean isAlign8(long a)
    Returns `true` if `a` is a multiple of 8. Asserts `a >= 0`.

  - ### alignTo

    public static int alignTo(int a, int alignment)
    Aligns `a` up to a power of two.

  - ### alignTo

    public static long alignTo(long a, long alignment)
    Aligns `a` up to a power of two.

  - ### alignUp

    public static int alignUp(int a, int alignment)

  - ### alignUpPad

    public static int alignUpPad(int a, int alignment)

  - ### alignDown

    public static int alignDown(int a, int alignment)

  - ### isPow2

    public static boolean isPow2(int a)
    Returns `true` if `a` is a power of 2. Asserts `a > 0`.

  - ### isPow2

    public static boolean isPow2(long a)
    Returns `true` if `a` is a power of 2. Asserts `a > 0`.

  - ### ceilLog2

    public static int ceilLog2(int a)
    Returns the log2 of `a`, were that value to be rounded up to the next power of 2. Asserts `a > 0`. NextLog2.

  - ### ceilLog2

    public static int ceilLog2(long a)
    Returns the log2 of `a`, were that value to be rounded up to the next power of 2. Asserts `a > 0`. NextLog2.

  - ### ceilPow2

    public static int ceilPow2(int a)
    Returns the smallest power of two greater than or equal to `a`. Asserts `a > 0 && a <= 2^30`. NextPow2.

  - ### ceilPow2

    public static long ceilPow2(long a)
    Returns the smallest power of two greater than or equal to `a`. Asserts `a > 0 && a <= 2^62`. NextPow2.

  - ### floorLog2

    public static int floorLog2(int a)
    Returns the log2 of `a`, were that value to be rounded down to the previous power of 2. Asserts `a > 0`. PrevLog2.

  - ### floorLog2

    public static int floorLog2(long a)
    Returns the log2 of `a`, were that value to be rounded down to the previous power of 2. Asserts `a > 0`. PrevLog2.

  - ### floorPow2

    public static int floorPow2(int a)
    Returns the largest power of two less than or equal to `a`. Asserts `a > 0`. PrevPow2.

  - ### floorPow2

    public static long floorPow2(long a)
    Returns the largest power of two less than or equal to `a`. Asserts `a > 0`. PrevPow2.

  - ### ceilLog2

    public static int ceilLog2(float v)
    Returns the log2 of the provided value, were that value to be rounded up to the next power of 2. Returns 0 if value invalid input: '<'= 0:
    Never returns a negative number, even if value is NaN.

             ceilLog2((-inf..1]) -> 0
             ceilLog2((1..2])    -> 1
             ceilLog2((2..4])    -> 2
             ceilLog2((4..8])    -> 3
             ceilLog2(+inf)      -> 128
             ceilLog2(NaN)       -> 0

    NextLog2.

  - ### ceilLog4

    public static int ceilLog4(float v)
    Returns ceil(log2(sqrt(x))):

             log2(sqrt(x)) == log2(x^(1/2)) == log2(x)/2 == log2(x)/log2(4) == log4(x)

  - ### ceilLog16

    public static int ceilLog16(float v)
    Returns ceil(log2(sqrt(sqrt(x)))):

             log2(sqrt(sqrt(x))) == log2(x^(1/4)) == log2(x)/4 == log2(x)/log2(16) == log16(x)

  - ### halfToFloat

    public static float halfToFloat(short h)

    Converts the specified half-precision float value into a single-precision float value. The following special cases are handled:

    - If the input is `FP16.NaN`, the returned value is `Float.NaN`
    - If the input is `FP16.POSITIVE_INFINITY` or `FP16.NEGATIVE_INFINITY`, the returned value is respectively `Float.POSITIVE_INFINITY` or `Float.NEGATIVE_INFINITY`
    - If the input is 0 (positive or negative), the returned value is +/-0.0f
    - Otherwise, the returned value is a normalized single-precision float value
    Parameters:
      `h` - The half-precision float value to convert to single-precision
    Returns:
      A normalized single-precision float value

  - ### floatToHalf

    public static short floatToHalf(float f)

    Converts the specified single-precision float value into a half-precision float value. The following special cases are handled:

    - If the input is NaN (see `Float.isNaN(float)`), the returned value is `FP16.NaN`
    - If the input is `Float.POSITIVE_INFINITY` or `Float.NEGATIVE_INFINITY`, the returned value is respectively `FP16.POSITIVE_INFINITY` or `FP16.NEGATIVE_INFINITY`
    - If the input is 0 (positive or negative), the returned value is `FP16.POSITIVE_ZERO` or `FP16.NEGATIVE_ZERO`
    - If the input is a less than `FP16.MIN_VALUE`, the returned value is flushed to `FP16.POSITIVE_ZERO` or `FP16.NEGATIVE_ZERO`
    - If the input is a less than `FP16.MIN_NORMAL`, the returned value is a denorm half-precision float
    - Otherwise, the returned value is rounded to the nearest representable half-precision float value
    Parameters:
      `f` - The single-precision float value to convert to half-precision
    Returns:
      A half-precision float value