fix: persistence is the trace's own phosphor, not a density behind a stroke

The plotter now deposits every acquisition -- the newest included -- into one grid per trace and
draws no solid trace over it, each grid in that trace's colour and with a one-sweep ceiling (its own
commit, **1b8b55d**). This side needed almost no change of its own, because the colour was already
the trace's and the trace's colour is `RowSet::signal_color()` -- the invariants' one route -- but the
figures it reads back are now per trace:

- **The ceiling is left at the library's default of one sweep**, no longer derived from the fade.
  Deriving it from the steady state is the gain offset the user reported between the latest
  acquisition and the persistent image; a signal crossing the same place every acquisition now settles
  at the trace's colour, at full strength, and the newest sweep reads as the trace it is a picture of.
- **`cells`/`grid_bytes` are the sum over the row's traces** -- one grid each, a trace with no series
  holding none -- and both the probe and the exit dump carry `traces=` beside `rows=`. That is what
  makes the per-signal memory figure read: **556 537 cells and 2.2 MB per signal**, at 8904600 bytes
  over the four one-signal rows of the probe's run.

The probes, re-read on this build (the `verification.md` command, `--rate 500000 --batch 1000`):

    [density-probe] off enabled=0 ... rows=0 traces=0 cells=0 ink=0.0 peak=0.0000
    [density-probe] on enabled=1 ... rows=4 traces=4 cells=2226150 ink=226786.0 peak=1.0000
    [density-probe] step-acquisitions ... peak=1.5000
    [density-probe] time-before ... peak=2.1359
    [density-probe] step-time ... ratio=0.367879
    [density-probe] frame cost: tick 0.62 -> 6.96 ms (184/23 frames), draw 2.02 -> 6.16 ms (177/18)
    [udpscope]   density: frames=748 rows=4 traces=4 cells=2226150 grid_bytes=8904600 ink=489400.2 peak=2.2 upload_bytes=2226150

`on` `peak=1.0000`, `step-acquisitions` `peak=1.5000` and `step-time` `ratio=0.367879` are the legs
that were expected, unchanged; the *draw* mean is now **below** the run before the split (2.02 -> 6.16
against 2.09 -> 20.91), because the solid traces are no longer drawn over the image.

Docs updated with it: the trigger manual page (`persistence` is the trace, one image per signal, the
newest included), the README's persistence section, `invariants-trigger-and-pinning.md` (five rules,
the ceiling and the no-stroke rule among them), `verification.md` and `probe-readings.md` (the lines
above), the trigger panel's comment and tooltips, and the plotter submodule.

`cmake --build build --clean-first -j4`: **0 errors, the documented three warnings** (two
`MathNode::source`, one `-Woverlength-strings` at 12352); `make -C build test-ui` **13 ok**;
`make -C build test-help` **green** (15 pages); the self-check **0 `Gtk-WARNING`/`Gtk-CRITICAL`** and
`gtk warnings: 0`, two `buffer allocated:` lines.
This commit is contained in:
Martino Ferrari committed 2026-10-16 20:21:57 +02:00
1 parent 5e32199597
commit da826f2cb5
11 files changed
+181 -130

No files matched your search

+11 -8
View File
@@ -123,16 +123,19 @@
<section id="persistence">
<title>Persistence: how often the trace has been here</title>
<p><gui>persistence</gui> — the switch in the trigger panel's <gui>Advanced</gui> block — keeps
one <em>image</em> of the last acquisitions instead of their traces. Every acquisition is
accumulated into it, so a cell's brightness means how many of them passed through it: the
sweep on screen is the brightest, the ones behind it add on top, and where several agree the
ink is brighter still. It is off by default.</p>
an <em>image</em> of the last acquisitions instead of their traces. Every acquisition is
accumulated into it, the one on screen included, so a cell's brightness means how many of them
passed through it: the sweep on screen is the brightest, the ones behind it add on top, and
where several agree the ink is brighter still. There is no stroke drawn over the image — the
acquisition on screen <em>is</em> its newest ink — so it fades with the rest in both modes. Each
signal is kept as its own image in that signal's own colour, so where two signals cross the same
place you see both, not one blended line. It is off by default.</p>
<p>Two things make it different from <gui>multiple events</gui> beside it, and the panel offers
both because they answer different questions. <em>It never runs out of room</em>: the image is
the size of the plot on screen, so a display of a thousand acquisitions costs what a display of
one costs, and there is no count to choose. <em>And it fades</em>, in one of two ways —
<gui>fades by</gui> picks them:</p>
both because they answer different questions. <em>It never runs out of room</em>: each signal's
image is the size of the plot on screen, so a display of a thousand acquisitions costs what a
display of one costs — one image per signal, whatever the plot's trace slots — and there is no
count to choose. <em>And it fades</em>, in one of two ways — <gui>fades by</gui> picks them:</p>
<list>
<item><p><gui>acquisitions</gui>: every acquisition keeps
<gui>per acquisition</gui> of what was there before it (0.5, the default, is the schedule a