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.
Prefix |
Object Type |
Notes |
---|---|---|
|
|
Raw vector of signed 32-bit integers. |
|
|
Raw vector of signed 16-bit integers. |
|
|
Raw vector of signed 8-bit integers. |
|
Raw vector of complex 32-bit integers. |
|
|
( |
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. |
|
|
A ‘chunk’ is a fixed size vector corresponding to the size of the VPU vector registers. |
|
|
When used in an API function name, the |
|
|
Raw vector of standard IEEE |
|
Vector of non-standard 32-bit floating-point scalars. |
|
|
Block floating-point vector contianing 32-bit mantissas. |
|
|
Block floating-point vector contianing 16-bit mantissas. |
|
|
Block floating-point vector contianing complex 32-bit mantissas. |
|
|
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.
Prefix |
Object Type |
Notes |
---|---|---|
|
|
32-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value. |
|
|
16-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value. |
|
|
8-bit signed integer. May be a simple integer, a fixed-point value or the mantissa of a floating-point value. |
|
Signed complex integer with 32-bit real and 32-bit imaginary parts. |
|
|
Signed complex integer with 16-bit real and 16-bit imaginary parts. |
|
|
Non-standard floating-point scalar with exponent and 64-bit mantissa. |
|
|
Non-standard floating-point scalar with exponent and 32-bit mantissa. |
|
|
|
32-bit fixed-point value with |
|
|
Standard IEEE 754 single-precision |
|
|
Standard IEEE 754 double-precision |
|
Floating-point value with exponent and complex mantissa with 64-bit real and imaginary parts. |
|
|
Floating-point value with exponent and complex mantissa with 32-bit real and imaginary parts. |
|
|
Floating-point value with exponent and complex mantissa with 16-bit real and imaginary parts. |
|
N/A |
Represents an exponent \(p\) as in \(2^p\). Unless otherwise specified exponent are always assumed to have a base of \(2\). |
|
N/A |
The headroom of a scalar or vector. See Headroom for more information. |
|
N/A |
Represents a rightward bit-shift of a certain number of bits. Care should be taken, as sometimes this is treated as unsigned. |
|
N/A |
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.
-
enumerator BFP_FLAG_DYNAMIC#
-
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 ofdata[]
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.
-
int32_t *data#
-
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 ofdata[]
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.
-
int16_t *data#
-
struct bfp_complex_s32_t#
- #include <types.h>
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 ofdata[]
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.
-
complex_s32_t *data#
-
struct bfp_complex_s16_t#
- #include <types.h>
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 ofdata[]
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.
-
int16_t *real#
-
enum bfp_flags_e#
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
-
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
-
struct complex_s64_t#
- #include <types.h>
A complex number with a 64-bit real part and 64-bit imaginary part.
-
struct complex_s32_t#
- #include <types.h>
A complex number with a 32-bit real part and 32-bit imaginary part.
-
struct complex_s16_t#
- #include <types.h>
A complex number with a 16-bit real part and 16-bit imaginary part.
-
typedef int exponent_t#
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 exponentexp
.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); }
-
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 exponentexp
.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); }
-
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\) ismant.im
, the 16-bit imaginary part of the mantissa, and \(x\) is the exponentexp
.
-
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\) ismant.im
, the 32-bit imaginary part of the mantissa, and \(x\) is the exponentexp
.
-
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\) ismant.im
, the 64-bit imaginary part of the mantissa, and \(x\) is the exponentexp
.
-
struct complex_float_t#
- #include <types.h>
A complex number with a single-precision floating-point real part and a single-precision floating-point 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.
-
struct float_s32_t#
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 int32_t q1_31#
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 integer0xSTUVWXYZ
is always exactly0x0000WXYZ
larger than0xSTUV0000
. To combine the upper and lower 16-bits of an accumulator, use(((int32_t)vD[k]) << 16) + vR[k]
.
-
struct split_acc_s32_t#