Choppy frequency scrolling on wide displays: full ~0.5 GB waterfall-history reprojected on every pan step

[svabi79]

Summary

On wide displays, horizontal frequency scrolling (mouse wheel) of the panadapter is choppy because the entire waterfall history image is reprojected on the CPU on every pan step — even though that history is only ever displayed during time-scrollback, never in the live view.

At ultrawide widths the history image is enormous: capacity is kWaterfallHistoryMs (20 min) ÷ 50 ms/row = 24 000 rows, so at ~4860 px wide it is ~0.5 GB (4860 × 24000 × 4). reprojectWaterfall() runs a QPainter::drawImage over both the visible waterfall and this full history image on every center-frequency change (SpectrumWidget.cpp reprojectWaterfall).

Evidence (instrumented, RTX 4090 / i9-13900K, 4860×… panadapter)

Timing the two reprojections separately during a 10 s scroll:

WfReprojectSplit visMs=3.21 visPx=4860x728 histMs=107.52 histPx=4860x24000
WfReprojectSplit visMs=2.99 visPx=4860x728 histMs=101.96 histPx=4860x24000
...
histMs: n=91 min=73 max=118 avg=108     <- full history reproject, per pan step
visMs:  n=91 max=4.0 avg=3.3            <- visible waterfall reproject

The history reprojection (avg 108 ms/step) is ~33× the visible one and blows the 16 ms frame budget ~7×. Built-in PerfSummary telemetry during continuous scrolling confirmed the user-visible effect:

metric (continuous-scroll windows)	value
uiLagMaxMs	110–164 ms
panAgeP95Ms / wfAgeP95Ms	120–155 ms
renderP95Ms (GPU)	6–8 ms ✅ (GPU is healthy)

The GPU render path is not the bottleneck; the synchronous CPU history reproject on the main thread is.

Impact

Frequency scrolling stutters badly on wide/ultrawide panadapters; the wider the window, the worse (cost scales with pixel width). The live view does not even use the history image, so the work is entirely wasted during normal tuning.

Root cause

reprojectWaterfall() keeps the full history continuously aligned to the current frequency frame so newly-appended rows stay consistent. That correctness goal is real, but paying ~0.5 GB of drawImage per pan step to maintain it — for data only shown on time-scrollback — is the wrong trade.

Proposed fix (PR to follow)

Reproject the visible waterfall immediately (cheap, ~3 ms) but defer + coalesce the history reprojection: remember the net transform and apply it once after scrolling settles (debounced), pausing history appends while pending and flushing on demand before a viewport rebuild (time-scrollback). The live view is visually unchanged.

After-fix telemetry (continuous scroll, up to 49 tune-cmds/s): uiLagMaxMs 27–38 ms, panAgeP95Ms/wfAgeP95Ms 24–30 ms — a 4–5× improvement. A small residual (one ~108 ms reproject per scroll gesture, on stop) remains and will be tracked separately.

Related

Distinct root cause from #3283 (which covers QPainter widget rasterization and GPU texture re-upload); this is specifically the history-image reprojection. Cross-referencing for the broader perf picture.

Environment

Windows 11, Qt 6.8.3 (msvc2022_64), RTX 4090 / i9-13900K, ultrawide (5144×1440). Platform-independent code path (reprojectWaterfall is plain Qt) — affects all platforms with wide panadapters.

[aethersdr-agent]

Triage: confirmed, root cause verified in source → maintainer-review

Thanks for the exceptionally thorough report — the instrumentation, split timing, and PerfSummary before/after made this easy to confirm. I read the code and your analysis holds.

Root cause (verified)

reprojectWaterfall() reprojects both images on every center-frequency change:

• src/gui/SpectrumWidget.cpp:2566-2567 — the lambda is invoked on m_waterfall (visible, cheap) and m_waterfallHistory (the full history buffer).
• The history buffer is sized to waterfallHistoryCapacityRows() = kWaterfallHistoryMs (20 min) / msPerRow (:1934-1939, kWaterfallHistoryMs at SpectrumWidget.h:794), i.e. ~24 000 rows. At ultrawide widths that's the ~0.5 GB QPainter::drawImage you measured.
• reprojectWaterfall() is called from every tuning path: setFrequencyRange() large-shift (:2680) and small-nudge (:2724), plus zoom/pan/wheel paths at :4435/:4485/:4985/:5151.

Crucially, the history image is only ever read in rebuildWaterfallViewport() (:2200-2225), which runs on time-scrollback (setWaterfallLive(false) / scroll-offset change). The live render path draws from m_waterfall, never m_waterfallHistory. So the per-pan-step history reproject is, as you say, entirely wasted work during normal tuning.

Proposed fix

Decouple the two reprojections in reprojectWaterfall():

1. Visible: keep reprojectImage(m_waterfall) synchronous (your ~3 ms).
2. History: instead of reprojecting inline, accumulate the net transform (compose pending old→new center/bandwidth) into pending state and arm a debounce timer; reproject once after scrolling settles.
3. While a history reproject is pending, pause appends in appendWaterfallHistoryRow() (:2176) — the history simply gets a short gap during the gesture — to avoid mixing old-frame and new-frame rows.
4. Flush on demand (apply the coalesced transform, then resume appends) at the single consumer, rebuildWaterfallViewport() (:2200), so time-scrollback always sees a correctly-aligned history. Also flush in clearDisplay()/resize paths that touch m_waterfallHistory.

The live view is visually unchanged; correctness for scrollback is preserved because the only reader is gated on a flush. This matches your measured 4–5× improvement, with the known residual (one ~108 ms reproject per gesture, on stop) to be tracked separately — note that the priority: medium here reflects the wasted-work hot path, not that residual.

Classification

• bug, spectrum + GUI, priority: medium
• Platform-independent (reprojectWaterfall is plain Qt), so no platform label — agrees with your env note.
• Cross-referenced Performance: ~92% of CPU is QPainter software rasterization; sluggish pan drag is a full-window sibling repaint #3283 (distinct: widget rasterization + GPU texture re-upload vs. this history-image reproject).

Handoff

Root cause and the only history consumer are both confirmed in source. Fix is localized to SpectrumWidget (reprojectWaterfall, appendWaterfallHistoryRow, rebuildWaterfallViewport, plus pending-transform state + a debounce timer in the header). The reporter already prototyped this approach with telemetry. Ready for implementation authorization (aetherclaude-eligible) if you concur.

---

_{🤖 aethersdr-agent · cost: $0.8394 · model: claude-opus-4-8}

---

_{📍 Citation health check (Foundry Constitution Principle I): 1 resolved, 1 unresolved against /Users/aetherclaude/workspace/AetherSDR at origin/main.}

Unresolved citations (1)

Citation	Reason
SpectrumWidget.h:794	file not found in workspace