com.jogamp.opengl.math

## Class Binary16

- java.lang.Object
- - com.jogamp.opengl.math.Binary16

-     public final class Binary16
      extends Object

  Functions to convert values to/from the `binary16` format specified in `IEEE 754 2008`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BIAS` The bias value used to offset the encoded exponent.
    `static char` | `NEGATIVE_INFINITY` The encoded form of negative infinity `-∞`.
    `static char` | `NEGATIVE_ZERO` The encoded form of negative zero `-0`.
    `static char` | `POSITIVE_INFINITY` The encoded form of positive infinity `∞`.
    `static char` | `POSITIVE_ZERO` The encoded form of positive zero `0`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static char` | `exampleNaN()` One possible not-a-number value.
    `static boolean` | `isInfinite(char k)` Return `true` if the given packed `binary16` value is infinite.
    `static boolean` | `isNaN(char k)` Return `true` if the given packed `binary16` value is not a number (`NaN`).
    `static char` | `packDouble(double k)` Convert a double precision floating point value to a packed `binary16` value.
    `static char` | `packFloat(float k)` Convert a single precision floating point value to a packed `binary16` value.
    `static char` | `packSetExponentUnbiasedUnchecked(int e)` Encode the unbiased exponent `e`.
    `static char` | `packSetSignificandUnchecked(int s)` Encode the significand `s`.
    `static char` | `packSetSignUnchecked(int s)` Encode the sign bit `s`.
    `static String` | `toRawBinaryString(char k)` Show the given raw packed `binary16` value as a string of binary digits.
    `static double` | `unpackDouble(char k)` Convert a packed `binary16` value `k` to a double-precision floating point value.
    `static float` | `unpackFloat(char k)` Convert a packed `binary16` value `k` to a single-precision floating point value.
    `static int` | `unpackGetExponentUnbiased(char k)` Extract and unbias the exponent of the given packed `binary16` value.
    `static int` | `unpackGetSign(char k)` Retrieve the sign bit of the given packed `binary16` value, as an integer in the range `[0, 1]`.
    `static int` | `unpackGetSignificand(char k)` Return the significand of the given packed `binary16` value as an integer in the range `[0, 1023]`.

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

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

- - ### Field Detail

    - #### NEGATIVE_INFINITY

          public static final char NEGATIVE_INFINITY

      The encoded form of negative infinity `-∞`.

    - #### POSITIVE_INFINITY

          public static final char POSITIVE_INFINITY

      The encoded form of positive infinity `∞`.

    - #### POSITIVE_ZERO

          public static final char POSITIVE_ZERO

      The encoded form of positive zero `0`.

    - #### NEGATIVE_ZERO

          public static final char NEGATIVE_ZERO

      The encoded form of negative zero `-0`.

    - #### BIAS

          public static final int BIAS

      The bias value used to offset the encoded exponent. A given exponent `e` is encoded as ``BIAS` + e`.

  - ### Method Detail

    - #### exampleNaN

          public static char exampleNaN()

      One possible not-a-number value.

    - #### isInfinite

          public static boolean isInfinite(char k)

      Return `true` if the given packed `binary16` value is infinite.

    - #### isNaN

          public static boolean isNaN(char k)

      Return `true` if the given packed `binary16` value is not a number (`NaN`).

    - #### packDouble

          public static char packDouble(double k)

      Convert a double precision floating point value to a packed `binary16` value.

      For the following specific cases, the function returns:

      - `NaN` iff `isNaN(k)`
      - `POSITIVE_INFINITY` iff `k == `Double.POSITIVE_INFINITY``
      - `NEGATIVE_INFINITY` iff `k == `Double.NEGATIVE_INFINITY``
      - `NEGATIVE_ZERO` iff `k == -0.0`
      - `POSITIVE_ZERO` iff `k == 0.0`

      Otherwise, the `binary16` value that most closely represents `k` is returned. This may obviously be an infinite value as the interval of double precision values is far larger than that of the `binary16` type.

      See Also:
        `unpackDouble(char)`

    - #### packFloat

          public static char packFloat(float k)

      Convert a single precision floating point value to a packed `binary16` value.

      For the following specific cases, the function returns:

      - `NaN` iff `isNaN(k)`
      - `POSITIVE_INFINITY` iff `k == `Float.POSITIVE_INFINITY``
      - `NEGATIVE_INFINITY` iff `k == `Float.NEGATIVE_INFINITY``
      - `NEGATIVE_ZERO` iff `k == -0.0`
      - `POSITIVE_ZERO` iff `k == 0.0`

      Otherwise, the `binary16` value that most closely represents `k` is returned. This may obviously be an infinite value as the interval of single precision values is far larger than that of the `binary16` type.

      See Also:
        `unpackFloat(char)`

    - #### packSetExponentUnbiasedUnchecked

          public static char packSetExponentUnbiasedUnchecked(int e)

      Encode the unbiased exponent `e`. Values should be in the range `[-15, 16]` - values outside of this range will be truncated.

      See Also:
        `unpackGetExponentUnbiased(char)`

    - #### packSetSignificandUnchecked

          public static char packSetSignificandUnchecked(int s)

      Encode the significand `s`. Values should be in the range `[0, 1023]`. Values outside of this range will be truncated.

      See Also:
        `unpackGetSignificand(char)`

    - #### packSetSignUnchecked

          public static char packSetSignUnchecked(int s)

      Encode the sign bit `s`. Values should be in the range `[0, 1]`, with `0` ironically denoting a positive value. Values outside of this range will be truncated.

      See Also:
        `unpackGetSign(char)`

    - #### toRawBinaryString

          public static String toRawBinaryString(char k)

      Show the given raw packed `binary16` value as a string of binary digits.

    - #### unpackDouble

          public static double unpackDouble(char k)

      Convert a packed `binary16` value `k` to a double-precision floating point value.

      The function returns:

      - `NaN` iff `isNaN(k)`
      - `Double.POSITIVE_INFINITY` iff `k == `POSITIVE_INFINITY``
      - `Double.NEGATIVE_INFINITY` iff `k == `NEGATIVE_INFINITY``
      - `-0.0` iff `k == `NEGATIVE_ZERO``
      - `0.0` iff `k == `POSITIVE_ZERO``
      - `(-1.0 * n) * (2 ^ e) * 1.s`, for the decoded sign `n` of `k`, the decoded exponent `e` of `k`, and the decoded significand `s` of `k`.
      See Also:
        `packDouble(double)`

    - #### unpackFloat

          public static float unpackFloat(char k)

      Convert a packed `binary16` value `k` to a single-precision floating point value.

      The function returns:

      - `NaN` iff `isNaN(k)`
      - `Float.POSITIVE_INFINITY` iff `k == `POSITIVE_INFINITY``
      - `Float.NEGATIVE_INFINITY` iff `k == `NEGATIVE_INFINITY``
      - `-0.0` iff `k == `NEGATIVE_ZERO``
      - `0.0` iff `k == `POSITIVE_ZERO``
      - `(-1.0 * n) * (2 ^ e) * 1.s`, for the decoded sign `n` of `k`, the decoded exponent `e` of `k`, and the decoded significand `s` of `k`.
      See Also:
        `packFloat(float)`

    - #### unpackGetExponentUnbiased

          public static int unpackGetExponentUnbiased(char k)

      Extract and unbias the exponent of the given packed `binary16` value.

      The exponent is encoded biased as a number in the range `[0, 31]`, with `0` indicating that the number is subnormal and `[1, 30]` denoting the actual exponent plus `BIAS`. Infinite and `NaN` values always have an exponent of `31`.

      This function will therefore return:

      - `0 - `BIAS` = -15` iff the input is a subnormal number.
      - An integer in the range `[1 - `BIAS`, 30 - `BIAS`] = [-14, 15]` iff the input is a normal number.
      - `16` iff the input is `POSITIVE_INFINITY`, `NEGATIVE_INFINITY`, or `NaN`.
      See Also:
        `packSetExponentUnbiasedUnchecked(int)`

    - #### unpackGetSign

          public static int unpackGetSign(char k)

      Retrieve the sign bit of the given packed `binary16` value, as an integer in the range `[0, 1]`.
      See Also:
        `packSetSignUnchecked(int)`

    - #### unpackGetSignificand

          public static int unpackGetSignificand(char k)

      Return the significand of the given packed `binary16` value as an integer in the range `[0, 1023]`.

      See Also:
        `packSetSignificandUnchecked(int)`

Copyright 2010 JogAmp Community.