Skip to content

File syn_qmath.h

FileList > src > syntropic > util > syn_qmath.h

Go to the source code of this file

Fixed-point Q16.16 arithmetic — no floating point. More...

  • #include <stddef.h>
  • #include <stdint.h>

Public Types

Type Name
typedef int32_t q16_t

Public Functions

Type Name
q16_t q16_acos (q16_t x)
Arc-cosine: π/2 − asin(x).
q16_t q16_asin (q16_t x)
Arc-sine (5th-order Chebyshev polynomial).
q16_t q16_atan2 (q16_t y, q16_t x)
Four-quadrant arctangent (minimax polynomial).
q16_t q16_ceil (q16_t x)
Fixed-point ceil: smallest integer >= x.
q16_t q16_cos (q16_t x)
Cosine approximation via sin(x + π/2).
q16_t q16_cos_fast (q16_t x)
Ultra-fast Parabolic/Chebyshev Cosine approximation (<20 CPU cycles).
q16_t q16_exp (q16_t x)
Fixed-point exponential e^x (range reduction + minimax polynomial).
q16_t q16_exp_fast (q16_t x)
Ultra-fast hybrid LUT exponential e^x (~15 CPU cycles).
q16_t q16_floor (q16_t x)
Fixed-point floor: largest integer <= x.
size_t q16_from_str (const char * str, q16_t * out)
Parse a decimal string (e.g. "-3.1415") into Q16.
q16_t q16_hypot (q16_t x, q16_t y)
Overflow-safe hypotenuse: √(x² + y²).
q16_t q16_inv (q16_t x)
Fast reciprocal 1/x in Q16.16 using Newton-Raphson iterations.
q16_t q16_log (q16_t x)
Fixed-point natural logarithm ln(x) (CLZ + minimax polynomial).
q16_t q16_log_fast (q16_t x)
Ultra-fast hybrid LUT natural logarithm ln(x) (~15 CPU cycles).
q16_t q16_poly_eval (const q16_t * coeffs, uint8_t n, q16_t x)
Evaluate polynomial P(x) = c0 + c1*x + c2*x^2 + ... + cn*x^n via Horner's method.
q16_t q16_pow (q16_t base, q16_t exp)
Fixed-point power: base^exp = exp(exp * log(base)).
q16_t q16_round (q16_t x)
Fixed-point round: nearest integer (half rounded up).
q16_t q16_rsqrt (q16_t x)
Fast inverse square root 1/√x in Q16.16 (Fast Quake/Newton-Raphson algorithm).
q16_t q16_sin (q16_t x)
Sine approximation (5th-order Taylor series).
q16_t q16_sin_fast (q16_t x)
Ultra-fast Parabolic/Chebyshev Sine approximation (<20 CPU cycles).
void q16_sincos_fast (q16_t x, q16_t * sin_out, q16_t * cos_out)
Simultaneous ultra-fast sine and cosine calculation (<30 CPU cycles).
q16_t q16_sqrt (q16_t x)
Fixed-point square root (binary restoring algorithm).
q16_t q16_tan (q16_t x)
Tangent: sin(x) / cos(x).
size_t q16_to_str (q16_t val, char * buf, size_t buf_len, uint8_t decimals)
Format a Q16 value as a decimal string (e.g. "-12.345").
uint32_t syn_isqrt32 (uint32_t n)
Compute floor of 32-bit unsigned integer square root: ⌊√n⌋.
uint64_t syn_isqrt64 (uint64_t n)
Compute floor of 64-bit unsigned integer square root: ⌊√n⌋.

Public Static Functions

Type Name
q16_t q16_abs (q16_t a)
Absolute value of a Q16 number.
q16_t q16_add (q16_t a, q16_t b)
Add two Q16 values.
q16_t q16_add_sat (q16_t a, q16_t b)
Saturating add (clamp to INT32 range).
q16_t q16_clamp (q16_t val, q16_t lo, q16_t hi)
Clamp a Q16 value to [lo, hi].
q16_t q16_div (q16_t a, q16_t b)
Divide two Q16 values.
q16_t q16_lerp (q16_t a, q16_t b, q16_t t)
Linear interpolation: lerp(a, b, t) where t is Q16 in [0, 1.0].
q16_t q16_mul (q16_t a, q16_t b)
Multiply two Q16 values.
q16_t q16_mul_sat (q16_t a, q16_t b)
Saturating multiply.
q16_t q16_sub (q16_t a, q16_t b)
Subtract two Q16 values.
q16_t q16_sub_sat (q16_t a, q16_t b)
Saturating subtract (clamp to INT32 range).

Macros

Type Name
define Q16_2_PI 411775
define Q16_E 178145
define Q16_FRAC_1000 (q) ((int32\_t)((((q) & 0xFFFF) \* 1000L) &gt;&gt; [**Q16\_SHIFT**](syn__qmath_8h.md#define-q16_shift)))
define Q16_FRAC_10000 (q) ((int32\_t)((((q) & 0xFFFF) \* 10000L) &gt;&gt; [**Q16\_SHIFT**](syn__qmath_8h.md#define-q16_shift)))
define Q16_FROM_FLOAT (f) (([**q16\_t**](syn__qmath_8h.md#typedef-q16_t))((f) \* (1L &lt;&lt; [**Q16\_SHIFT**](syn__qmath_8h.md#define-q16_shift))))
define Q16_FROM_FRAC (num, den) (([**q16\_t**](syn__qmath_8h.md#typedef-q16_t))(((int64\_t)((uint64\_t)(int64\_t)(num) &lt;&lt; [**Q16\_SHIFT**](syn__qmath_8h.md#define-q16_shift))) / (den)))
define Q16_FROM_INT (n) (([**q16\_t**](syn__qmath_8h.md#typedef-q16_t))((int32\_t)(n) \* [**Q16\_ONE**](syn__qmath_8h.md#define-q16_one)))
define Q16_HALF (([**q16\_t**](syn__qmath_8h.md#typedef-q16_t))(1L &lt;&lt; ([**Q16\_SHIFT**](syn__qmath_8h.md#define-q16_shift) - 1)))
define Q16_LN2 45426
define Q16_ONE (([**q16\_t**](syn__qmath_8h.md#typedef-q16_t))(1L &lt;&lt; [**Q16\_SHIFT**](syn__qmath_8h.md#define-q16_shift)))
define Q16_PI 205887
define Q16_PI_2 102944
define Q16_SHIFT 16
define Q16_SQRT2 92682
define Q16_TO_INT (q) ((int32\_t)((q) &gt;&gt; [**Q16\_SHIFT**](syn__qmath_8h.md#define-q16_shift)))
define Q16_TO_INT_ROUND (q) ((int32\_t)(((q) + [**Q16\_HALF**](syn__qmath_8h.md#define-q16_half)) &gt;&gt; [**Q16\_SHIFT**](syn__qmath_8h.md#define-q16_shift)))

Detailed Description

All operations use signed 32-bit values with 16 integer bits and 16 fractional bits. Multiply/divide use 64-bit intermediates to avoid overflow.

Basic arithmetic (add, sub, mul, div, lerp, clamp) is inline in this header. Transcendental functions (sin, cos, sqrt, atan2, exp, log) and string I/O are compiled in syn_qmath.c.

** **

q16_t a = Q16_FROM_INT(3);         // 3.0
q16_t b = Q16_FROM_FRAC(1, 2);     // 0.5
q16_t c = q16_mul(a, b);           // 1.5
int   i = Q16_TO_INT(c);           // 1
int   f = Q16_FRAC_1000(c);        // 500 (fractional part × 1000)

Public Types Documentation

typedef q16_t

typedef int32_t q16_t;

Fixed-point Q16.16 type: 16 integer bits, 16 fractional bits.

Public Functions Documentation

function q16_acos

Arc-cosine: π/2 − asin(x). 

q16_t q16_acos (
    q16_t x
)

Parameters:

  • x Input in Q16, must be in [−1.0, 1.0].

Returns:

Angle in Q16 radians [0, π].

function q16_asin

Arc-sine (5th-order Chebyshev polynomial). 

q16_t q16_asin (
    q16_t x
)

Parameters:

  • x Input in Q16, must be in [−1.0, 1.0].

Returns:

Angle in Q16 radians [−π/2, π/2].

function q16_atan2

Four-quadrant arctangent (minimax polynomial). 

q16_t q16_atan2 (
    q16_t y,
    q16_t x
)

Parameters:

  • y Y coordinate in Q16.
  • x X coordinate in Q16.

Returns:

Angle in Q16 radians [−π, π].

function q16_ceil

Fixed-point ceil: smallest integer >= x. 

q16_t q16_ceil (
    q16_t x
)

Parameters:

  • x Input in Q16.

Returns:

Ceil value in Q16.

function q16_cos

Cosine approximation via sin(x + π/2). 

q16_t q16_cos (
    q16_t x
)

Parameters:

  • x Angle in Q16 radians.

Returns:

cos(x) in Q16.

function q16_cos_fast

Ultra-fast Parabolic/Chebyshev Cosine approximation (<20 CPU cycles). 

q16_t q16_cos_fast (
    q16_t x
)

Parameters:

  • x Angle in Q16 radians.

Returns:

cos(x) in Q16.

function q16_exp

Fixed-point exponential e^x (range reduction + minimax polynomial). 

q16_t q16_exp (
    q16_t x
)

Parameters:

  • x Exponent in Q16.

Returns:

e^x in Q16. Returns INT32_MAX on overflow.

function q16_exp_fast

Ultra-fast hybrid LUT exponential e^x (~15 CPU cycles). 

q16_t q16_exp_fast (
    q16_t x
)

Parameters:

  • x Exponent in Q16.

Returns:

e^x in Q16. Returns INT32_MAX on overflow.

function q16_floor

Fixed-point floor: largest integer <= x. 

q16_t q16_floor (
    q16_t x
)

Parameters:

  • x Input in Q16.

Returns:

Floor value in Q16.

function q16_from_str

Parse a decimal string (e.g. "-3.1415") into Q16. 

size_t q16_from_str (
    const char * str,
    q16_t * out
)

Handles optional sign, integer part, optional decimal point and fractional digits. Stops at first non-numeric character.

Parameters:

  • str Input string (NUL-terminated).
  • out Output Q16 value.

Returns:

Number of characters consumed, or 0 on parse error.

function q16_hypot

Overflow-safe hypotenuse: √(x² + y²). 

q16_t q16_hypot (
    q16_t x,
    q16_t y
)

Parameters:

  • x First coordinate in Q16.
  • y Second coordinate in Q16.

Returns:

Magnitude in Q16.

function q16_inv

Fast reciprocal 1/x in Q16.16 using Newton-Raphson iterations. 

q16_t q16_inv (
    q16_t x
)

Parameters:

  • x Input in Q16 (must be > 0).

Returns:

1/x in Q16. Returns INT32_MAX on x == 0.

function q16_log

Fixed-point natural logarithm ln(x) (CLZ + minimax polynomial). 

q16_t q16_log (
    q16_t x
)

Parameters:

  • x Input in Q16 (must be > 0).

Returns:

ln(x) in Q16.

function q16_log_fast

Ultra-fast hybrid LUT natural logarithm ln(x) (~15 CPU cycles). 

q16_t q16_log_fast (
    q16_t x
)

Parameters:

  • x Input in Q16 (must be > 0).

Returns:

ln(x) in Q16.

function q16_poly_eval

Evaluate polynomial P(x) = c0 + c1*x + c2*x^2 + ... + cn*x^n via Horner's method. 

q16_t q16_poly_eval (
    const q16_t * coeffs,
    uint8_t n,
    q16_t x
)

Parameters:

  • coeffs Array of polynomial coefficients [c0, c1, ..., cn].
  • n Number of coefficients (order = n - 1).
  • x Evaluation point in Q16.

Returns:

P(x) in Q16.

function q16_pow

Fixed-point power: base^exp = exp(exp * log(base)). 

q16_t q16_pow (
    q16_t base,
    q16_t exp
)

Parameters:

  • base Base in Q16 (must be > 0).
  • exp Exponent in Q16.

Returns:

base^exp in Q16.

function q16_round

Fixed-point round: nearest integer (half rounded up). 

q16_t q16_round (
    q16_t x
)

Parameters:

  • x Input in Q16.

Returns:

Rounded value in Q16.

function q16_rsqrt

Fast inverse square root 1/√x in Q16.16 (Fast Quake/Newton-Raphson algorithm). 

q16_t q16_rsqrt (
    q16_t x
)

Parameters:

  • x Input in Q16 (must be > 0).

Returns:

1/√x in Q16. Returns 0 if x <= 0.

function q16_sin

Sine approximation (5th-order Taylor series). 

q16_t q16_sin (
    q16_t x
)

Parameters:

  • x Angle in Q16 radians.

Returns:

sin(x) in Q16.

function q16_sin_fast

Ultra-fast Parabolic/Chebyshev Sine approximation (<20 CPU cycles). 

q16_t q16_sin_fast (
    q16_t x
)

Parameters:

  • x Angle in Q16 radians.

Returns:

sin(x) in Q16.

function q16_sincos_fast

Simultaneous ultra-fast sine and cosine calculation (<30 CPU cycles). 

void q16_sincos_fast (
    q16_t x,
    q16_t * sin_out,
    q16_t * cos_out
)

Parameters:

  • x Angle in Q16 radians.
  • sin_out Output sin(x) in Q16.
  • cos_out Output cos(x) in Q16.

function q16_sqrt

Fixed-point square root (binary restoring algorithm). 

q16_t q16_sqrt (
    q16_t x
)

Parameters:

  • x Input in Q16 (must be ≥ 0).

Returns:

√x in Q16.

function q16_tan

Tangent: sin(x) / cos(x). 

q16_t q16_tan (
    q16_t x
)

Parameters:

  • x Angle in Q16 radians. Must not be near ±π/2.

Returns:

tan(x) in Q16.

function q16_to_str

Format a Q16 value as a decimal string (e.g. "-12.345"). 

size_t q16_to_str (
    q16_t val,
    char * buf,
    size_t buf_len,
    uint8_t decimals
)

No heap allocation. The caller provides the output buffer.

Parameters:

  • val Value to format.
  • buf Output buffer (must be large enough).
  • buf_len Size of output buffer in bytes.
  • decimals Number of fractional digits (0–4).

Returns:

Number of characters written (excluding NUL), or 0 on error.

function syn_isqrt32

Compute floor of 32-bit unsigned integer square root: ⌊√n⌋. 

uint32_t syn_isqrt32 (
    uint32_t n
)

Parameters:

  • n Unsigned 32-bit integer.

Returns:

⌊√n⌋.

function syn_isqrt64

Compute floor of 64-bit unsigned integer square root: ⌊√n⌋. 

uint64_t syn_isqrt64 (
    uint64_t n
)

Parameters:

  • n Unsigned 64-bit integer.

Returns:

⌊√n⌋.

Public Static Functions Documentation

function q16_abs

Absolute value of a Q16 number. 

static inline q16_t q16_abs (
    q16_t a
)

Parameters:

  • a Input value.

Returns:

|a| in Q16.

function q16_add

Add two Q16 values. 

static inline q16_t q16_add (
    q16_t a,
    q16_t b
)

Parameters:

  • a First operand.
  • b Second operand.

Returns:

Sum in Q16.

function q16_add_sat

Saturating add (clamp to INT32 range). 

static inline q16_t q16_add_sat (
    q16_t a,
    q16_t b
)

Parameters:

  • a First operand.
  • b Second operand.

Returns:

Clamped sum in Q16.

function q16_clamp

Clamp a Q16 value to [lo, hi]. 

static inline q16_t q16_clamp (
    q16_t val,
    q16_t lo,
    q16_t hi
)

Parameters:

  • val Input value.
  • lo Lower bound.
  • hi Upper bound.

Returns:

Clamped value.

function q16_div

Divide two Q16 values. 

static inline q16_t q16_div (
    q16_t a,
    q16_t b
)

Parameters:

  • a Dividend.
  • b Divisor (must not be zero).

Returns:

Quotient in Q16.

function q16_lerp

Linear interpolation: lerp(a, b, t) where t is Q16 in [0, 1.0]. 

static inline q16_t q16_lerp (
    q16_t a,
    q16_t b,
    q16_t t
)

Parameters:

  • a Start value.
  • b End value.
  • t Interpolation factor (Q16, 0 to Q16_ONE).

Returns:

Interpolated value in Q16.

function q16_mul

Multiply two Q16 values. 

static inline q16_t q16_mul (
    q16_t a,
    q16_t b
)

Parameters:

  • a First operand.
  • b Second operand.

Returns:

Product in Q16.

function q16_mul_sat

Saturating multiply. 

static inline q16_t q16_mul_sat (
    q16_t a,
    q16_t b
)

Parameters:

  • a First operand.
  • b Second operand.

Returns:

Clamped product in Q16.

function q16_sub

Subtract two Q16 values. 

static inline q16_t q16_sub (
    q16_t a,
    q16_t b
)

Parameters:

  • a Minuend.
  • b Subtrahend.

Returns:

Difference in Q16.

function q16_sub_sat

Saturating subtract (clamp to INT32 range). 

static inline q16_t q16_sub_sat (
    q16_t a,
    q16_t b
)

Parameters:

  • a Minuend.
  • b Subtrahend.

Returns:

Clamped difference in Q16.

Macro Definition Documentation

define Q16_2_PI

#define Q16_2_PI `411775`

6.28318531 in Q16.16

define Q16_E

#define Q16_E `178145`

2.71828183 in Q16.16

define Q16_FRAC_1000

#define Q16_FRAC_1000 (
    q
) `((int32_t)((((q) & 0xFFFF) * 1000L) >> Q16_SHIFT ))`

Fractional part as 0–999 (for printf: "%d.%03d").

define Q16_FRAC_10000

#define Q16_FRAC_10000 (
    q
) `((int32_t)((((q) & 0xFFFF) * 10000L) >> Q16_SHIFT ))`

Fractional part as 0–9999 (for printf: "%d.%04d").

define Q16_FROM_FLOAT

#define Q16_FROM_FLOAT (
    f
) `(( q16_t )((f) * (1L << Q16_SHIFT )))`

Float literal to Q16 (compile-time only, avoid at runtime).

define Q16_FROM_FRAC

#define Q16_FROM_FRAC (
    num,
    den
) `(( q16_t )(((int64_t)((uint64_t)(int64_t)(num) << Q16_SHIFT )) / (den)))`

Fraction to Q16: Q16_FROM_FRAC(1, 3) ≈ 0.333.

define Q16_FROM_INT

#define Q16_FROM_INT (
    n
) `(( q16_t )((int32_t)(n) * Q16_ONE ))`

Integer to Q16.

define Q16_HALF

#define Q16_HALF `(( q16_t )(1L << ( Q16_SHIFT - 1)))`

0.5 in Q16.16

define Q16_LN2

#define Q16_LN2 `45426`

0.69314718 in Q16.16

define Q16_ONE

#define Q16_ONE `(( q16_t )(1L << Q16_SHIFT ))`

1.0 in Q16.16

define Q16_PI

#define Q16_PI `205887`

3.14159265 in Q16.16

define Q16_PI_2

#define Q16_PI_2 `102944`

1.57079633 in Q16.16

define Q16_SHIFT

#define Q16_SHIFT `16`

Fractional bit count

define Q16_SQRT2

#define Q16_SQRT2 `92682`

1.41421356 in Q16.16

define Q16_TO_INT

#define Q16_TO_INT (
    q
) `((int32_t)((q) >> Q16_SHIFT ))`

Q16 to integer (truncates toward zero).

define Q16_TO_INT_ROUND

#define Q16_TO_INT_ROUND (
    q
) `((int32_t)(((q) + Q16_HALF ) >> Q16_SHIFT ))`

Q16 to integer (rounded).

The documentation for this class was generated from the following file src/syntropic/util/syn_qmath.h