fr_math/pages/releases.html at db7c36b5d5a95b92690a5a81b4d4c324262f294d · deftio/fr_math · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Releases — FR_Math</title>
  <meta name="description" content="FR_Math release history: v2.0.0 precision rewrite and new waveforms, v1.0.3 test coverage, v1.02 initial public release.">
  <link rel="stylesheet" href="assets/main.css">
</head>
<body>

<header id="site-header"></header>

<main class="page-content">
  <div class="wrapper">

<h1>Releases</h1>

<p>Release highlights. For the full per-symbol change log, see
<a href="https://github.com/deftio/fr_math/blob/master/release_notes.md">release_notes.md</a>
in the repo.</p>

<h2>v2.0.5 &mdash; 2026</h2>

<p>Release pipeline fixes. Fixed squash-merge divergence handling and
on-master push/CI sequencing in <code>tools/make_release.sh</code>.</p>

<hr>

<h2>v2.0.4 &mdash; 2026</h2>

<p>CI fix release. Fixed <code>release.yml</code> coverage step, release pipeline
auto-commits badge/version changes, removed conflicting auto-release
job from <code>ci.yml</code>.</p>

<hr>

<h2>v2.0.3 &mdash; 2026</h2>

<p>CI and release pipeline cleanup. Guided release script
(<code>tools/make_release.sh</code>) that validates, merges, tags, and publishes
to PlatformIO and ESP-IDF in one flow.</p>

<hr>

<h2>v2.0.2 &mdash; 2026</h2>

<p>Embedded library publishing support. No functional changes to the
math library &mdash; adds Arduino, PlatformIO, and ESP-IDF package manager
integration.</p>

<ul>
<li>Arduino Library Manager, PlatformIO Registry, and ESP-IDF Component
    Registry metadata files</li>
<li>Reorganized examples with focused Arduino <code>.ino</code> sketches</li>
<li>Added <code>llms.txt</code> and <code>agents.md</code> for AI coding agents</li>
<li>Tag-triggered release workflow (<code>.github/workflows/release.yml</code>)</li>
</ul>

<hr>

<h2>v2.0.1 &mdash; 2026</h2>

<p>Precision and accuracy release. All changes are backward-compatible
with v2.0.0 except where noted.</p>

<h3>Trig output precision</h3>
<ul>
  <li><code>fr_cos_bam</code> / <code>fr_sin_bam</code> now return
      <strong>s15.16</strong> (was s0.15). Exact values at cardinal angles:
      <code>cos(0&deg;) = 65536</code>, <code>cos(90&deg;) = 0</code>.
      <code>FR_TRIG_ONE = 65536</code>.</li>
  <li><code>FR_TanI</code> / <code>fr_tan</code> return s15.16 (was s16.15).
      Saturation is now <code>&pm;INT32_MAX</code>.</li>
  <li>All wrappers updated: <code>FR_Cos</code>, <code>FR_Sin</code>,
      <code>FR_CosI</code>, <code>FR_SinI</code>, <code>FR_TanI</code>,
      <code>FR_Tan</code>.</li>
</ul>

<h3>Inverse trig now returns radians</h3>
<ul>
  <li><code>FR_acos</code>, <code>FR_asin</code>, <code>FR_atan</code>
      gain an <code>out_radix</code> parameter and return radians at that
      radix (was degrees as <code>s16</code>).</li>
  <li><code>FR_atan2(y, x, out_radix)</code> also returns radians.</li>
  <li><code>FR_BAM2RAD</code> macro corrected (was off by a factor of
      1024).</li>
</ul>

<h3>Rounding improvements</h3>
<ul>
  <li><code>FR_FixMuls</code> / <code>FR_FixMulSat</code>: add 0.5 LSB
      (<code>+0x8000</code>) before the <code>&gt;&gt;16</code> shift. Both
      now <strong>round to nearest</strong> instead of truncating.</li>
  <li><code>FR_sqrt</code> / <code>FR_hypot</code>: the internal
      <code>fr_isqrt64</code> now rounds to nearest (remainder &gt; root
      &rarr; +1). Worst-case error drops from &lt;1 LSB to
      <strong>&le; 0.5 LSB</strong>.</li>
</ul>

<h3>Improved exp / log accuracy</h3>
<ul>
  <li><strong><code>FR_pow2</code> table expanded</strong> from 17 entries
      (16 segments) to 65 entries (64 segments, 260 bytes). Interpolation
      error drops by ~16&times;.</li>
  <li><strong><code>FR_log2</code> table expanded</strong> from 33 entries
      to 65 entries (6-bit index / 24-bit interpolation). Worst-case error
      &le; 4 LSB at Q16.16.</li>
  <li><strong><code>FR_MULK28</code> macro</strong> added: multiplies any
      fixed-point value by a radix-28 constant using a 64-bit intermediate
      with round-to-nearest. ~9 decimal digits of precision.</li>
  <li><code>FR_EXP</code> and <code>FR_POW10</code> now use
      <code>FR_MULK28</code> for the base conversion instead of shift-only
      macros. Much lower error.</li>
  <li><code>FR_ln</code> and <code>FR_log10</code> also use
      <code>FR_MULK28</code> internally.</li>
  <li><strong><code>FR_EXP_FAST</code></strong> and
      <strong><code>FR_POW10_FAST</code></strong> added as shift-only
      alternatives for 8-bit targets where 64-bit multiply is expensive.</li>
  <li>Four radix-28 constants added: <code>FR_kLOG2E_28</code>,
      <code>FR_krLOG2E_28</code>, <code>FR_kLOG2_10_28</code>,
      <code>FR_krLOG2_10_28</code>.</li>
</ul>

<h3>New utility macros</h3>
<ul>
  <li><code>FR_MIN</code>, <code>FR_MAX</code>, <code>FR_CLAMP</code>
      &mdash; standard min/max/clamp.</li>
  <li><code>FR_DIV(x, xr, y, yr)</code> &mdash; fixed-point division with
      64-bit pre-scaling. Now <strong>rounds to nearest</strong>
      (&le; 0.5 LSB error) instead of truncating.
      <code>FR_DIV_TRUNC</code> preserves the old truncating behaviour
      for backward compatibility. <code>FR_DIV32</code> is the 32-bit-only
      truncating path.</li>
  <li><code>FR_MOD(x, xr, y, yr)</code> &mdash; fixed-point modulus.</li>
</ul>

<h3>Infrastructure</h3>
<ul>
  <li>Docker cross-compile size report (9 targets).</li>
  <li><code>sync_version.sh</code> rewrite &mdash;
      <code>FR_MATH_VERSION_HEX</code> is the single source of truth for
      version numbers.</li>
  <li>CI auto-release job, Dependabot config.</li>
  <li>Documentation audit: 14 errors fixed across header, source, markdown,
      and HTML docs.</li>
</ul>

<h3>Breaking changes from v2.0.0</h3>
<table>
<thead>
<tr><th>Change</th><th>v2.0.0</th><th>v2.0.1</th></tr>
</thead>
<tbody>
<tr><td>sin/cos return type</td><td><code>s16</code> (s0.15)</td><td><code>s32</code> (s15.16)</td></tr>
<tr><td>sin/cos 1.0 value</td><td>32767</td><td>65536 (exact)</td></tr>
<tr><td>tan return format</td><td>s16.15 (radix 15)</td><td>s15.16 (radix 16)</td></tr>
<tr><td>tan saturation</td><td><code>&pm;(32767 &lt;&lt; 15)</code></td><td><code>&pm;INT32_MAX</code></td></tr>
<tr><td>FR_acos/asin signature</td><td><code>(input, radix)</code> &rarr; s16 degrees</td><td><code>(input, radix, out_radix)</code> &rarr; s32 radians</td></tr>
<tr><td>FR_atan signature</td><td><code>(input, radix)</code> &rarr; s16 degrees</td><td><code>(input, radix, out_radix)</code> &rarr; s32 radians</td></tr>
<tr><td>FR_atan2 signature</td><td><code>(y, x)</code> &rarr; s16 degrees</td><td><code>(y, x, out_radix)</code> &rarr; s32 radians</td></tr>
<tr><td>FR_BAM2RAD</td><td>off by 1024&times; (bug)</td><td>correct</td></tr>
<tr><td>FR_DIV rounding</td><td>truncates toward zero</td><td>rounds to nearest (use <code>FR_DIV_TRUNC</code> for old behaviour)</td></tr>
</tbody>
</table>

<hr>

<h2>v2.0.0 &mdash; 2026</h2>

<p>The first major revision in more than twenty years. v2 is a
bug-fix, precision, and feature release with a full test suite and
99% line coverage.</p>

<h3>64-bit safety</h3>

<p>v1 defined <code>s32</code> as <code>signed long</code>, which is
64 bits on LP64 platforms (Linux x64, macOS arm64). Every
fixed-point path that assumed <code>s32</code> was exactly 32 bits
silently produced wrong results on desktop hosts. v2 migrates all
typedefs to <code>&lt;stdint.h&gt;</code>
(<code>int8_t</code>&hellip;<code>int32_t</code>). C99 is now
mandatory.</p>

<h3>Numerical fixes</h3>

<ul>
  <li><code>FR_FixMulSat</code> / <code>FR_FixMuls</code>: rewritten
      on an <code>int64_t</code> fast path with explicit saturation;
      v1 had an algebraic bug in the sign-combination logic.</li>
  <li><code>FR_log2</code> / <code>FR_ln</code> / <code>FR_log10</code>:
      new leading-bit-position + 33-entry mantissa table with linear
      interpolation. v1 returned wrong values for non-power-of-2
      inputs.</li>
  <li><code>FR_pow2</code> / <code>FR_EXP</code> / <code>FR_POW10</code>:
      corrected floor-toward-&minus;&infin; integer-part extraction.
      v1 gave wrong answers for negative non-integer inputs.</li>
  <li><code>FR_atan2</code>: v1 was a placeholder that returned
      garbage. v2 is a correct octant-reduced arctan with max error
      &le; 1&deg;. The vestigial <code>radix</code> argument was
      dropped.</li>
  <li><code>FR_atan</code>, <code>FR_Tan</code>, <code>FR_TanI</code>:
      wiring and overflow fixes.</li>
  <li><code>FR_printNumD/F/H</code>: fixed undefined behaviour on
      <code>INT_MIN</code> and a broken fraction extraction in the
      v1 code.</li>
  <li><code>FR_DEG2RAD</code> / <code>FR_RAD2DEG</code>: macro bodies
      were swapped in v1. v2 fixes them and adds missing parentheses.</li>
</ul>

<h3>New functionality</h3>

<ul>
  <li><strong>Radian-native trig</strong>: <code>fr_sin</code>,
      <code>fr_cos</code>, <code>fr_tan</code>,
      <code>fr_sin_bam</code>, <code>fr_cos_bam</code>,
      <code>fr_sin_deg</code>, <code>fr_cos_deg</code>. Uses a new
      129-entry quadrant cosine table with round-to-nearest linear
      interpolation. Max error &le; 1 LSB of s0.15 (~3e&minus;5).</li>
  <li><strong>BAM macros</strong>: <code>FR_DEG2BAM</code>,
      <code>FR_BAM2DEG</code>, <code>FR_RAD2BAM</code>,
      <code>FR_BAM2RAD</code>. BAM (16 bits per full circle) is the
      natural integer representation for phase accumulators and
      gives zero quantisation at the wraparound.</li>
  <li><strong>Square root and hypot</strong>: <code>FR_sqrt</code>
      uses a digit-by-digit integer isqrt on <code>int64_t</code>;
      <code>FR_hypot</code> computes <code>sqrt(x&sup2; + y&sup2;)</code>
      with no intermediate overflow across the full <code>s32</code>
      range.</li>
  <li><strong>Wave generator family</strong>: <code>fr_wave_sqr</code>,
      <code>fr_wave_pwm</code>, <code>fr_wave_tri</code>,
      <code>fr_wave_saw</code>, <code>fr_wave_tri_morph</code>,
      <code>fr_wave_noise</code>. All are stateless and take a
      <code>u16</code> BAM phase. Suitable for embedded audio, LFOs,
      and control signals.</li>
  <li><strong>ADSR envelope generator</strong>: linear-segment
      attack/decay/sustain/release with s1.30 internal state so very
      long durations at high sample rates still have non-zero
      per-sample increments.</li>
  <li><strong>Compile-time table size</strong>:
      <code>-DFR_TRIG_TABLE_BITS=8</code> doubles table precision at
      the cost of a larger (257-entry) table. Default is 7 / 129
      entries.</li>
</ul>

<h3>New documentation</h3>

<ul>
  <li><a href="guide/api-reference.html">API Reference</a> &mdash;
      complete per-symbol reference with inputs, outputs, radix
      handling, and worst-case error.</li>
  <li><code>CONTRIBUTING.md</code> &mdash; PR expectations,
      portability rules, commit format.</li>
  <li><code>tools/interp_analysis.html</code> &mdash; interactive
      Chart.js comparison of seven interpolation methods on the trig
      table.</li>
  <li>This documentation site (the one you&rsquo;re reading).</li>
</ul>

<h3>Breaking changes</h3>

<ul>
  <li><code>FR_NUM(i, f, r)</code> &rarr; <code>FR_NUM(i, f, d,
      r)</code>. The v1 form was broken (it ignored <code>f</code>
      entirely), so any caller was already getting wrong results.</li>
  <li><code>FR_atan2(y, x, radix)</code> &rarr; <code>FR_atan2(y,
      x)</code>. The <code>radix</code> parameter was vestigial.</li>
  <li><code>FR_RESULT</code> and the <code>FR_E_*</code> codes are
      gone. <code>inv()</code> returns <code>bool</code>;
      <code>add()</code> / <code>sub()</code> /
      <code>setrotate()</code> return <code>void</code>. Math
      functions use named sentinels <code>FR_DOMAIN_ERROR</code>,
      <code>FR_OVERFLOW_POS</code>, <code>FR_OVERFLOW_NEG</code>.</li>
  <li><code>FR_SQUARE</code> and <code>FR_FIXMUL32u</code> removed
      &mdash; use <code>FR_FixMuls</code> / <code>FR_FixMulSat</code>,
      which now have an <code>int64_t</code> fast path and work at any
      radix.</li>
  <li><code>FR_NO_INT64</code> and <code>FR_NO_STDINT</code> build
      flags removed. Every modern C99 toolchain ships
      <code>&lt;stdint.h&gt;</code> and 64-bit arithmetic.</li>
</ul>

<h3>Test suite</h3>

<p>v2 ships with <strong>42 tests</strong> across six test binaries
and a characterisation suite (<code>test_tdd.cpp</code>) that pins
numerical behaviour to bit-exact reference values. Overall line
coverage is <strong>99%</strong> on the library sources.</p>

<h2>v1.0.3 &mdash; 2025</h2>

<p>Test-coverage release. Overall line coverage went from 4% to 72%
with four new test files
(<code>test_comprehensive.c</code>,
<code>test_overflow_saturation.c</code>,
<code>test_full_coverage.c</code>,
<code>test_2d_complete.cpp</code>). Added a GitHub Actions CI with
multi-platform (Linux, macOS) and multi-compiler (gcc, clang)
matrices, cross-compilation for ARM and RISC-V, and 32-bit
compatibility testing.</p>

<p>Also fixed a broken <code>FR_atan</code> implementation, corrected
<code>FR_PI</code> / <code>FR_2PI</code> / <code>FR_E</code>
declarations to use <code>const</code>, and fixed
<code>XFormPtI</code> test assumptions.</p>

<h2>v1.02 &mdash; first public release</h2>

<p>Basic fixed-point operations, 2D transforms, and integer-degree
trigonometry. This is the version that shipped inside the original
Palm Pilot Inkstorm application.</p>

<h2>v1.01 &mdash; internal development</h2>

<p>Naming conventions cleanup and an initial test framework. Never
released publicly.</p>

<h2>Timeline</h2>

<p>FR_Math has been in continuous service since <strong>2000</strong>,
when it was written to run 2D graphics transforms on 16&nbsp;MHz 68k
Palm Pilots for Trumpetsoft&rsquo;s <em>Inkstorm</em>. It has since
been ported to ARM, x86, MIPS, RISC-V, and a menagerie of 8- and
16-bit embedded targets. v2.0.0 is the first major revision with a
full test suite, a bit-exact numerical specification, and CI on
every push.</p>

  </div>
</main>

<footer id="site-footer"></footer>

<script src="assets/site.js"></script>
</body>
</html>