Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# XMath Types

Each of the main operand types used in this library has a short-hand which is used as a prefix in the naming of API operations. The following tables can be used for reference.

## Common Vector Types

The following table indicates the types and abbreviations associated with various common vector types.

Table 71 Common Vector Types
Prefix | Object Type | Notes
--- | --- | ---
`vect_s32` | `int32_t[]` | Raw vector of signed 32-bit integers.
`vect_s16` | `int16_t[]` | Raw vector of signed 16-bit integers.
`vect_s8` | `int8_t[]` | Raw vector of signed 8-bit integers.
`vect_complex_s32` | `complex_s32_t``[]` | Raw vector of complex 32-bit integers.
`vect_complex_s16` | (`int16_t[]`, `int16_t[]`) | Complex 16-bit vectors are usually represented as a pair of 16-bit vectors. This is an optimization due to the word-alignment requirement when loading data into the VPU’s vector registers.
`chunk_s32` | `int32_t[8]` | A ‘chunk’ is a fixed size vector corresponding to the size of the VPU vector registers.
`vect_qXX` | `int32_t[]` | When used in an API function name, the `XX` will be an actual number (e.g. `vect_q30_exp_small()`) indicating the fixed-point interpretation used by that function.
`vect_f32` | `float[]` | Raw vector of standard IEEE `float`
`vect_float_s32` | `float_s32_t``[]` | Vector of non-standard 32-bit floating-point scalars.
`bfp_s32` | `bfp_s32_t` | Block floating-point vector contianing 32-bit mantissas.
`bfp_s16` | `bfp_s16_t` | Block floating-point vector contianing 16-bit mantissas.
`bfp_complex_s32` | `bfp_complex_s32_t` | Block floating-point vector contianing complex 32-bit mantissas.
`bfp_complex_s16` | `bfp_complex_s16_t` | Block floating-point vector contianing complex 16-bit mantissas.

## Common Scalar Types

The following table indicates the types and abbreviations associated with various common scalar types.

Table 72 Common Scalar Types
Prefix | Object Type | Notes
--- | --- | ---
`s32` | `int32_t` | 32-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value.
`s16` | `int16_t` | 16-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value.
`s8` | `int8_t` | 8-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value.
`complex_s32` | `complex_s32_t` | Signed complex integer with 32-bit real and 32-bit imaginary parts.
`complex_s16` | `complex_s16_t` | Signed complex integer with 16-bit real and 16-bit imaginary parts.
`float_s64` | `float_s64_t` | Non-standard floating-point scalar with exponent and 64-bit mantissa.
`float_s32` | `float_s32_t` | Non-standard floating-point scalar with exponent and 32-bit mantissa.
`qXX` | `int32_t` | 32-bit fixed-point value with `XX` fractional bits (i.e. exponent of `-XX`).
`f32` | `float` | Standard IEEE 754 single-precision `float`.
`f64` | `double` | Standard IEEE 754 double-precision `float`.
`float_complex_s64` | `float_complex_s64_t` | Floating-point value with exponent and complex mantissa with 64-bit real and imaginary parts.
`float_complex_s32` | `float_complex_s32_t` | Floating-point value with exponent and complex mantissa with 32-bit real and imaginary parts.
`float_complex_s16` | `float_complex_s16_t` | Floating-point value with exponent and complex mantissa with 16-bit real and imaginary parts.
N/A | `exponent_t` | Represents an exponent \(p\) as in \(2^p\). Unless otherwise specified exponent are always assumed to have a base of \(2\).
N/A | `headroom_t` | The headroom of a scalar or vector. See Headroom for more information.
N/A | `right_shift_t` | Represents a rightward bit-shift of a certain number of bits. Care should be taken, as sometimes this is treated as unsigned.
N/A | `left_shift_t` | Represents a leftward bit-shift of a certain number of bits. Care should be taken, as sometimes this is treated as unsigned.

## Block Floating-Point Types

group type_bfp

  Enums

  enum bfp_flags_e

    (Opaque) Flags field for BFP vectors.

    Warning

    Users should not manually modify fields of this type, as it is intended to be opaque.

    Values:

    enumerator BFP_FLAG_DYNAMIC

      Indicates that BFP vector’s mantissa buffer(s) were allocated dynamically

      This flag lets the bfp_*_dealloc() functions know whether the mantissa vector must be free()ed.

  struct bfp_s32_t
    #include <types.h>

    A block floating-point vector of 32-bit elements.

    Initialized with the `bfp_s32_init()` function.

    The logical quantity represented by each element of this vector is: `data[i]*2^(exp)` where the multiplication and exponentiation are using real (non-modular) arithmetic.

    The BFP API keeps the `hr` field up-to-date with the current headroom of `data[]` so as to minimize precision loss as elements become small.

    Public Members

    int32_t *data

      Pointer to the underlying element buffer.

    exponent_t exp

      Exponent associated with the vector.

    headroom_t hr

      Current headroom in the `data[]`

    unsigned length

      Current size of `data[]`, expressed in elements

    bfp_flags_e flags

      BFP vector flags. Users should not normally modify these manually.

  struct bfp_s16_t
    #include <types.h>

    A block floating-point vector of 16-bit elements.

    Initialized with the `bfp_s16_init()` function.

    The logical quantity represented by each element of this vector is: `data[i] * 2^(exp)` where the multiplication and exponentiation are using real (non-modular) arithmetic.

    The BFP API keeps the `hr` field up-to-date with the current headroom of `data[]` so as to minimize precision loss as elements become small. [bfp_s16_t]

    Public Members

    int16_t *data

      Pointer to the underlying element buffer.

    exponent_t exp

      Exponent associated with the vector.

    headroom_t hr

      Current headroom in the `data[]`

    unsigned length

      Current size of `data[]`, expressed in elements

    bfp_flags_e flags

      BFP vector flags. Users should not normally modify these manually.

  struct bfp_complex_s32_t
    #include <types.h>

    [bfp_s16_t]

    A block floating-point vector of complex 32-bit elements.

    Initialized with the `bfp_complex_s32_init()` function.

    The logical quantity represented by each element of this vector is: `data[k].re * 2^(exp) + i * data[k].im * 2^(exp)` where the multiplication and exponentiation are using real (non-modular) arithmetic, and i is sqrt(-1)

    The BFP API keeps the `hr` field up-to-date with the current headroom of `data[]` so as to minimize precision loss as elements become small. [bfp_complex_s32_t]

    Public Members

    complex_s32_t *data

      Pointer to the underlying element buffer.

    exponent_t exp

      Exponent associated with the vector.

    headroom_t hr

      Current headroom in the `data[]`

    unsigned length

      Current size of `data[]`, expressed in elements

    bfp_flags_e flags

      BFP vector flags. Users should not normally modify these manually.

  struct bfp_complex_s16_t
    #include <types.h>

    [bfp_complex_s32_t]

    A block floating-point vector of complex 16-bit elements.

    Initialized with the `bfp_complex_s16_init()` function.

    The logical quantity represented by each element of this vector is: `data[k].re * 2^(exp) + i * data[k].im * 2^(exp)` where the multiplication and exponentiation are using real (non-modular) arithmetic, and i is sqrt(-1)

    The BFP API keeps the `hr` field up-to-date with the current headroom of `data[]` so as to minimize precision loss as elements become small. [bfp_complex_s16_t]

    Public Members

    int16_t *real

      Pointer to the underlying element buffer.

    int16_t *imag

      Pointer to the underlying element buffer.

    exponent_t exp

      Exponent associated with the vector.

    headroom_t hr

      Current headroom in the `data[]`

    unsigned length

      Current size of `data[]`, expressed in elements

    bfp_flags_e flags

      BFP vector flags. Users should not normally modify these manually.

## Scalar Types (Integer)

group type_scalar_int

  Typedefs

  typedef int exponent_t

    An exponent.

    Many places in this API make use of integers representing the exponent associated with some floating-point value or block floating-point vector.

    For a floating-point value \(x \cdot 2^p\), \(p\) is the exponent, and may usually be positive or negative.

  typedef unsigned headroom_t

    Headroom of some integer or integer array.

    Represents the headroom of a signed or unsigned integer, complex integer or channel pair, or the headroom of the mantissa array of a block floating-point vector.

  typedef int right_shift_t

    A rightwards arithmetic bit-shift.

    Represents a right bit-shift to be applied to an integer. May be signed or unsigned, depending on context. If signed, negative values represent leftward bit-shifts.

    See also

    left_shift_t

  typedef int left_shift_t

    A leftwards arithmetic bit-shift.

    Represents a left bit-shift to be applied to an integer. May be signed or unsigned, depending on context. If signed, negative values represent rightward bit-shifts.

    See also

    right_shift_t

  struct complex_s64_t
    #include <types.h>

    A complex number with a 64-bit real part and 64-bit imaginary part.

    Public Members

    int64_t re

      Real Part.

    int64_t im

      Imaginary Part.

  struct complex_s32_t
    #include <types.h>

    A complex number with a 32-bit real part and 32-bit imaginary part.

    Public Members

    int32_t re

      Real Part.

    int32_t im

      Imaginary Part.

  struct complex_s16_t
    #include <types.h>

    A complex number with a 16-bit real part and 16-bit imaginary part.

    Public Members

    int16_t re

      Real Part.

    int16_t im

      Imaginary Part.

## Scalar Types (Floating-Point)

group type_scalar_float
  struct float_s32_t
    #include <types.h>

    A floating-point scalar with a 32-bit mantissa.

    Represents a (non-standard) floating-point value given by \( M \cdot 2^{x} \), where \(M\) is the 32-bit mantissa `mant`, and \(x\) is the exponent `exp`.

    To convert a `float_s32_t` to a standard IEEE754 single-precision floating-point value (which may result in a loss of precision):

        float to_ieee_float(float_s32_t x) {
            return ldexpf(x.mant, x.exp);
        }

    Public Members

    int32_t mant

      32-bit mantissa

    exponent_t exp

      exponent

  struct float_s64_t
    #include <types.h>

    A floating-point scalar with a 64-bit mantissa.

    Represents a (non-standard) floating-point value given by \( M \cdot 2^{x} \), where \(M\) is the 64-bit mantissa `mant`, and \(x\) is the exponent `exp`.

    To convert a `float_s64_t` to a standard IEEE754 double-precision floating-point value (which may result in a loss of precision):

        double to_ieee_float(float_s64_t x) {
            return ldexp(x.mant, x.exp);
        }

    Public Members

    int64_t mant

      64-bit mantissa

    exponent_t exp

      exponent

  struct float_complex_s16_t
    #include <types.h>

    A complex floating-point scalar with a complex 16-bit mantissa.

    Represents a (non-standard) complex floating-point value given by \( A + j\cdot B \cdot 2^{x}\), where \(A\) is `mant.re`, the 16-bit real part of the mantissa, \(B\) is `mant.im`, the 16-bit imaginary part of the mantissa, and \(x\) is the exponent `exp`.

    Public Members

    complex_s16_t mant

      complex 16-bit mantissa

    exponent_t exp

      exponent

  struct float_complex_s32_t
    #include <types.h>

    A complex floating-point scalar with a complex 32-bit mantissa.

    Represents a (non-standard) complex floating-point value given by \( A + j\cdot B \cdot 2^{x} \), where \(A\) is `mant.re`, the 32-bit real part of the mantissa, \(B\) is `mant.im`, the 32-bit imaginary part of the mantissa, and \(x\) is the exponent `exp`.

    Public Members

    complex_s32_t mant

      complex 32-bit mantissa

    exponent_t exp

      exponent

  struct float_complex_s64_t
    #include <types.h>

    A complex floating-point scalar with a complex 64-bit mantissa.

    Represents a (non-standard) complex floating-point value given by \( A + j\cdot B \cdot 2^{x}\), where \(A\) is `mant.re`, the 64-bit real part of the mantissa, \(B\) is `mant.im`, the 64-bit imaginary part of the mantissa, and \(x\) is the exponent `exp`.

    Public Members

    complex_s64_t mant

      complex 64-bit mantissa

    exponent_t exp

      exponent

  struct complex_float_t
    #include <types.h>

    [bfp_complex_s16_t]

    A complex number with a single-precision floating-point real part and a single-precision floating-point imaginary part.

    Public Members

    float re

      Real Part.

    float im

      Imaginary Part.

  struct complex_double_t
    #include <types.h>

    A complex number with a double-precision floating-point real part and a double-precision floating-point imaginary part.

    Public Members

    double re

      Real Part.

    double im

      Imaginary Part.

## Scalar Types (Fixed-Point)

group type_scalar_fixed

  Typedefs

  typedef int32_t q1_31

    Q1.31 (Signed) Fixed-point value.

    Represents a signed, 32-bit, real, fixed-point value with 31 fractional bits (i.e. an implicit exponent of \(-31\)).

    Capable of representing values in the range \(\left[-1.0, 1.0\right)\)

  typedef int32_t q2_30

    Q2.30 (Signed) Fixed-point value.

    Represents a signed, 32-bit, real, fixed-point value with 30 fractional bits (i.e. an implicit exponent of \(-30\)).

    Capable of representing values in the range \(\left[-2.0, 2.0\right)\)

  typedef int32_t q4_28

    Q4.28 (Signed) Fixed-point value.

    Represents a signed, 32-bit, real, fixed-point value with 28 fractional bits (i.e. an implicit exponent of \(-28\)).

    Capable of representing values in the range \(\left[-8.0, 8.0\right)\)

  typedef int32_t q8_24

    Q8.24 (Signed) Fixed-point value.

    Represents a signed, 32-bit, real, fixed-point value with 24 fractional bits (i.e. an implicit exponent of \(-24\)).

    Capable of representing values in the range \(\left[-128.0, 128.0\right)\)

  typedef uint32_t uq0_32

    UQ0.32 (Unsigned) Fixed-point value.

    Represents an unsigned, 32-bit, real, fixed-point value with 32 fractional bits (i.e. an implicit exponent of \(-32\)).

    Capable of representing values in the range \(\left[0, 1.0\right)\)

  typedef uint32_t uq1_31

    UQ1.31 (Unsigned) Fixed-point value.

    Represents an unsigned, 32-bit, real, fixed-point value with 31 fractional bits (i.e. an implicit exponent of \(-31\)).

    Capable of representing values in the range \(\left[0, 2.0\right)\)

  typedef uint32_t uq2_30

    UQ2.30 (Unsigned) Fixed-point value.

    Represents an unsigned, 32-bit, real, fixed-point value with 30 fractional bits (i.e. an implicit exponent of \(-30\)).

    Capable of representing values in the range \(\left[0, 4.0\right)\)

  typedef uint32_t uq4_28

    UQ4.28 (Unsigned) Fixed-point value.

    Represents an unsigned, 32-bit, real, fixed-point value with 28 fractional bits (i.e. an implicit exponent of \(-28\)).

    Capable of representing values in the range \(\left[0, 16.0\right)\)

  typedef uint32_t uq8_24

    UQ8.24 (Unsigned) Fixed-point value.

    Represents an unsigned, 32-bit, real, fixed-point value with 24 fractional bits (i.e. an implicit exponent of \(-24\)).

    Capable of representing values in the range \(\left[0, 256.0\right)\)

  typedef q1_31 sbrad_t

    Specialized angular unit used by this library.

    ‘sbrad’ is a kind of modified binary radian (hence ‘brad’) which takes into account the symmetries of \(sin(\theta)\).

    Use radians_to_sbrads() to convert from radians to `sbrad_t`.

  typedef q8_24 radian_q24_t

    Angle measurement in radians using a Q8.24 representation.

## Misc Types

group type_misc
  struct split_acc_s32_t
    #include <types.h>

    Holds a set of sixteen 32-bit accumulators in the XS3 VPU’s internal format.

    The XS3 VPU stores 32-bit accumulators with the most significant 16-bits stored in one 256-bit vector register (called vD), and the least significant 16-bit stored in another 256-bit register (called vR). This struct reflects that internal format, and is occasionally used to store intermediate results.

    Note

    `vR` is unsigned. This reflects the fact that a signed 16-bit integer `0xSTUVWXYZ` is always exactly `0x0000WXYZ` larger than `0xSTUV0000`. To combine the upper and lower 16-bits of an accumulator, use `(((int32_t)vD[k]) << 16) + vR[k]`.

    Public Members

    int16_t vD[16]

      Most significant 16 bits of accumulators.

    uint16_t vR[16]

      Least significant 16 bits of accumulators.