XMath Types#
Each of the main operand types used in this library has a shorthand 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 32bit integers. 


Raw vector of signed 16bit integers. 


Raw vector of signed 8bit integers. 

Raw vector of complex 32bit integers. 


( 
Complex 16bit vectors are usually represented as a pair of 16bit vectors. This is an optimization due to the wordalignment 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 nonstandard 32bit floatingpoint scalars. 


Block floatingpoint vector contianing 32bit mantissas. 


Block floatingpoint vector contianing 16bit mantissas. 


Block floatingpoint vector contianing complex 32bit mantissas. 


Block floatingpoint vector contianing complex 16bit mantissas. 
Common Scalar Types#
The following table indicates the types and abbreviations associated with various common scalar types.
Prefix 
Object Type 
Notes 



32bit signed integer. May be a simple integer, a fixedpoint value or the mantissa of a floatingpoint value. 


16bit signed integer. May be a simple integer, a fixedpoint value or the mantissa of a floatingpoint value. 


8bit signed integer. May be a simple integer, a fixedpoint value or the mantissa of a floatingpoint value. 

Signed complex integer with 32bit real and 32bit imaginary parts. 


Signed complex integer with 16bit real and 16bit imaginary parts. 


Nonstandard floatingpoint scalar with exponent and 64bit mantissa. 


Nonstandard floatingpoint scalar with exponent and 32bit mantissa. 



32bit fixedpoint value with 


Standard IEEE 754 singleprecision 


Standard IEEE 754 doubleprecision 

Floatingpoint value with exponent and complex mantissa with 64bit real and imaginary parts. 


Floatingpoint value with exponent and complex mantissa with 32bit real and imaginary parts. 


Floatingpoint value with exponent and complex mantissa with 16bit 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 bitshift of a certain number of bits. Care should be taken, as sometimes this is treated as unsigned. 

N/A 
Represents a leftward bitshift of a certain number of bits. Care should be taken, as sometimes this is treated as unsigned. 
Block FloatingPoint 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 floatingpoint vector of 32bit 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 (nonmodular) arithmetic.The BFP API keeps the
hr
field uptodate 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 floatingpoint vector of 16bit 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 (nonmodular) arithmetic.The BFP API keeps the
hr
field uptodate 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 floatingpoint vector of complex 32bit 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 (nonmodular) arithmetic, and i is sqrt(1)The BFP API keeps the
hr
field uptodate 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 floatingpoint vector of complex 16bit 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 (nonmodular) arithmetic, and i is sqrt(1)The BFP API keeps the
hr
field uptodate 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 floatingpoint value or block floatingpoint vector.
For a floatingpoint 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 floatingpoint vector.

typedef int right_shift_t#
A rightwards arithmetic bitshift.
Represents a right bitshift to be applied to an integer. May be signed or unsigned, depending on context. If signed, negative values represent leftward bitshifts.
See also

typedef int left_shift_t#
A leftwards arithmetic bitshift.
Represents a left bitshift to be applied to an integer. May be signed or unsigned, depending on context. If signed, negative values represent rightward bitshifts.
See also

struct complex_s64_t#
 #include <types.h>
A complex number with a 64bit real part and 64bit imaginary part.

struct complex_s32_t#
 #include <types.h>
A complex number with a 32bit real part and 32bit imaginary part.

struct complex_s16_t#
 #include <types.h>
A complex number with a 16bit real part and 16bit imaginary part.

typedef int exponent_t#
Scalar Types (FloatingPoint)#
 group type_scalar_float

struct float_s32_t#
 #include <types.h>
A floatingpoint scalar with a 32bit mantissa.
Represents a (nonstandard) floatingpoint value given by \( M \cdot 2^{x} \), where \(M\) is the 32bit mantissa
mant
, and \(x\) is the exponentexp
.To convert a
float_s32_t
to a standard IEEE754 singleprecision floatingpoint 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 floatingpoint scalar with a 64bit mantissa.
Represents a (nonstandard) floatingpoint value given by \( M \cdot 2^{x} \), where \(M\) is the 64bit mantissa
mant
, and \(x\) is the exponentexp
.To convert a
float_s64_t
to a standard IEEE754 doubleprecision floatingpoint 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 floatingpoint scalar with a complex 16bit mantissa.
Represents a (nonstandard) complex floatingpoint value given by \( A + j\cdot B \cdot 2^{x}\), where \(A\) is
mant.re
, the 16bit real part of the mantissa, \(B\) ismant.im
, the 16bit imaginary part of the mantissa, and \(x\) is the exponentexp
.

struct float_complex_s32_t#
 #include <types.h>
A complex floatingpoint scalar with a complex 32bit mantissa.
Represents a (nonstandard) complex floatingpoint value given by \( A + j\cdot B \cdot 2^{x} \), where \(A\) is
mant.re
, the 32bit real part of the mantissa, \(B\) ismant.im
, the 32bit imaginary part of the mantissa, and \(x\) is the exponentexp
.

struct float_complex_s64_t#
 #include <types.h>
A complex floatingpoint scalar with a complex 64bit mantissa.
Represents a (nonstandard) complex floatingpoint value given by \( A + j\cdot B \cdot 2^{x}\), where \(A\) is
mant.re
, the 64bit real part of the mantissa, \(B\) ismant.im
, the 64bit imaginary part of the mantissa, and \(x\) is the exponentexp
.

struct complex_float_t#
 #include <types.h>
A complex number with a singleprecision floatingpoint real part and a singleprecision floatingpoint imaginary part.

struct complex_double_t#
 #include <types.h>
A complex number with a doubleprecision floatingpoint real part and a doubleprecision floatingpoint imaginary part.

struct float_s32_t#
Scalar Types (FixedPoint)#
 group type_scalar_fixed
Typedefs

typedef int32_t q1_31#
Q1.31 (Signed) Fixedpoint value.
Represents a signed, 32bit, real, fixedpoint 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) Fixedpoint value.
Represents a signed, 32bit, real, fixedpoint 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) Fixedpoint value.
Represents a signed, 32bit, real, fixedpoint 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) Fixedpoint value.
Represents a signed, 32bit, real, fixedpoint 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) Fixedpoint value.
Represents an unsigned, 32bit, real, fixedpoint 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) Fixedpoint value.
Represents an unsigned, 32bit, real, fixedpoint 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) Fixedpoint value.
Represents an unsigned, 32bit, real, fixedpoint 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) Fixedpoint value.
Represents an unsigned, 32bit, real, fixedpoint 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) Fixedpoint value.
Represents an unsigned, 32bit, real, fixedpoint 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 32bit accumulators in the XS3 VPU’s internal format.
The XS3 VPU stores 32bit accumulators with the most significant 16bits stored in one 256bit vector register (called vD), and the least significant 16bit stored in another 256bit 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 16bit integer0xSTUVWXYZ
is always exactly0x0000WXYZ
larger than0xSTUV0000
. To combine the upper and lower 16bits of an accumulator, use(((int32_t)vD[k]) << 16) + vR[k]
.

struct split_acc_s32_t#