GPU-accelerated spectrum/waterfall rendering via QRhi (#391) (#698)

* Phase 1: QRhiWidget proof of life for GPU spectrum (#391)

SpectrumWidget conditionally inherits QRhiWidget when AETHER_GPU_SPECTRUM
is enabled. Renders solid dark background via beginPass/endPass. Child
widgets (VfoWidget, OverlayMenu, zoom buttons) composite correctly on
top of the QRhi surface.

- CMake: AETHER_GPU_SPECTRUM option with Qt6::GuiPrivate, Qt6::ShaderTools
- Conditional base class via SPECTRUM_BASE_CLASS macro
- paintEvent wrapped in #ifndef, QRhi stubs in #ifdef
- Validated: renders, child widgets visible, mouse events work

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Phase 2: GPU waterfall + overlay rendering via QRhi (#391)

Waterfall QImage uploaded as RGBA8 texture, rendered as textured quad
with ring buffer scrolling via fragment shader fract(uv.y + offset).
All overlays (grid, FFT, band plan, slices, TNF, spots, scales) painted
into an overlay QImage via QPainter, composited as alpha-blended texture.

Key fix: fract() must be in the fragment shader, not vertex shader.
Per-vertex fract() linearizes between two identical values when the UV
range spans exactly 1.0 (fract(0+offset) == fract(1+offset)), producing
constant UV across the quad. This was likely the same bug that killed
the previous GPU attempt.

Shaders compiled at build time via qt_add_shaders() — no binary .qsb
files in the repo, shader errors are build errors not silent runtime
failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Phase 2: Incremental waterfall row uploads — 97% → 40% CPU (#391)

Replace full 3.5MB QImage upload per frame with per-row incremental
uploads (~6KB each). Track last uploaded row, walk the ring buffer
delta, upload only changed rows with setDestinationTopLeft().

CPU reduction: 97% (QPainter) → 52% (full upload) → 40% (incremental).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Phase 2: Static overlay caching — 97% → 35% CPU (#391)

Split overlay into static (grid, band plan, scales, slices, TNF, spots)
and dynamic (FFT spectrum line) layers. Static overlay only repainted
when markOverlayDirty() is called from state-change methods. Per-frame
work: memcpy cached static, paint FFT on top, upload composite.

Replaced all update() calls with markOverlayDirty() except the two
data paths (updateSpectrum, updateWaterfallRow) which only need a
render, not a static overlay repaint.

CPU progression: 97% (QPainter) → 52% (full upload) → 40% (incremental
waterfall) → 35% (static overlay caching).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Fix non-GPU build: move markOverlayDirty() outside #ifdef

markOverlayDirty() was declared inside #ifdef AETHER_GPU_SPECTRUM but
called from non-guarded code. The method handles both paths internally
so it must be visible regardless of the GPU flag.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Enable GPU spectrum by default, add CI dependencies

AETHER_GPU_SPECTRUM now defaults to ON for shipped binaries. Added
qt6-base-private-dev, qt6-shader-baker, and qt6-shadertools-dev to
the CI Docker image.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Graceful fallback when Qt6::ShaderTools not available

GPU spectrum defaults to ON but falls back to OFF if Qt6::ShaderTools
or Qt6::GuiPrivate aren't found, instead of failing the build. Allows
CI to build successfully while the Docker image is being updated.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Revert graceful fallback — GPU rendering is required

Qt6::ShaderTools and Qt6::GuiPrivate must be present. Build fails
loudly if missing, forcing the CI image to be updated rather than
silently shipping without GPU acceleration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add missing Qt modules to all release workflows

All release builds (AppImage, Windows, macOS DMG, macOS PKG) were
missing qtwebsockets (TCI server), qtshadertools (GPU spectrum).
ARM AppImage also missing serialport, hidapi, fftw3, portaudio,
qt6-base-private-dev.

This is why TCI wasn't in shipped binaries — the aqtinstall modules
list only had qtmultimedia and qtserialport.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update build dependencies with full feature list

All packages listed for Arch, Ubuntu, Fedora, macOS with collapsible
table explaining what each dependency enables. Includes GPU spectrum
(qt6-shadertools), TCI (qt6-websockets), StreamDeck (hidapi), NR2
(fftw3) and all other auto-detected features.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Auto-disable GPU spectrum on Qt < 6.7

QRhiWidget requires Qt 6.7+. CI Docker image has Qt 6.4 (Ubuntu 24.04)
which doesn't have QRhiWidget. GPU spectrum now auto-disables on older
Qt instead of failing the build. Release workflows use Qt 6.7 via
aqtinstall and get GPU enabled.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ten9876

.github/docker/Dockerfile

@@ -18,6 +18,9 @@ RUN apt-get update && apt-get install -y \
     qt6-multimedia-dev \
     qt6-websockets-dev \
     qt6-serialport-dev \
+    qt6-base-private-dev \
+    qt6-shader-baker \
+    qt6-shadertools-dev \
     libgl1-mesa-dev \
     libasound2-dev \
     libfftw3-dev \

.github/workflows/appimage.yml

@@ -42,14 +42,17 @@ jobs:
       - name: Install system Qt (ARM only)
         if: matrix.use_aqt == false
         run: |
-          sudo apt-get install -y qt6-base-dev qt6-multimedia-dev
+          sudo apt-get install -y qt6-base-dev qt6-multimedia-dev \
+            qt6-websockets-dev qt6-serialport-dev qt6-base-private-dev \
+            qt6-shader-baker qt6-shadertools-dev \
+            libhidapi-dev portaudio19-dev libfftw3-dev
 
       - name: Install Qt 6.7 via aqtinstall (x86_64)
         if: matrix.use_aqt == true
         run: |
           pip3 install aqtinstall
           aqt install-qt linux desktop 6.7.3 linux_gcc_64 \
-            -m qtmultimedia \
+            -m qtmultimedia qtwebsockets qtserialport qtshadertools \
             --outputdir ${{ github.workspace }}/Qt
           echo "Qt6_DIR=${{ github.workspace }}/Qt/6.7.3/gcc_64/lib/cmake/Qt6" >> $GITHUB_ENV
           echo "CMAKE_PREFIX_PATH=${{ github.workspace }}/Qt/6.7.3/gcc_64" >> $GITHUB_ENV

.github/workflows/macos-dmg.yml

@@ -22,7 +22,7 @@ jobs:
           host: 'mac'
           target: 'desktop'
           arch: 'clang_64'
-          modules: 'qtmultimedia qtserialport'
+          modules: 'qtmultimedia qtserialport qtwebsockets qtshadertools'
 
       - name: Install build tools
         run: brew install ninja create-dmg autoconf automake libtool

.github/workflows/macos-installer.yml

@@ -24,7 +24,7 @@ jobs:
           host: 'mac'
           target: 'desktop'
           arch: 'clang_64'
-          modules: 'qtmultimedia qtserialport'
+          modules: 'qtmultimedia qtserialport qtwebsockets qtshadertools'
 
       - name: Install build tools
         run: brew install ninja autoconf automake libtool

.github/workflows/windows-installer.yml

@@ -25,7 +25,7 @@ jobs:
           host: 'windows'
           target: 'desktop'
           arch: 'win64_msvc2019_64'
-          modules: 'qtmultimedia qtserialport'
+          modules: 'qtmultimedia qtserialport qtwebsockets qtshadertools'
 
       - name: Install Ninja and Inno Setup
         run: choco install ninja innosetup -y

CMakeLists.txt

@@ -161,6 +161,23 @@ else()
     endif()
 endif()
 
+# GPU-accelerated spectrum/waterfall rendering via QRhi (#391)
+# Requires: Qt 6.7+ (QRhiWidget), Qt6::ShaderTools (build-time shader compilation)
+# Defaults to ON but auto-disables on Qt < 6.7 (e.g. Ubuntu 24.04 ships Qt 6.4).
+option(AETHER_GPU_SPECTRUM "Enable QRhi GPU spectrum rendering" ON)
+if(AETHER_GPU_SPECTRUM)
+    if(Qt6_VERSION VERSION_LESS "6.7")
+        set(AETHER_GPU_SPECTRUM OFF)
+        message(STATUS "GPU spectrum rendering disabled (requires Qt 6.7+, found ${Qt6_VERSION})")
+    else()
+        find_package(Qt6 REQUIRED COMPONENTS ShaderTools)
+        find_package(Qt6GuiPrivate QUIET)
+        message(STATUS "GPU spectrum rendering enabled (QRhi, Qt ${Qt6_VERSION})")
+    endif()
+else()
+    message(STATUS "GPU spectrum rendering disabled (use -DAETHER_GPU_SPECTRUM=ON to enable)")
+endif()
+
 # NVIDIA NIM BNR (Background Noise Removal) — GPU-accelerated neural denoising
 # Requires: grpc++, protobuf, NVIDIA RTX 4000+ GPU, Docker container
 option(ENABLE_BNR "Enable NVIDIA NIM BNR noise removal (requires grpc++)" OFF)
@@ -557,6 +574,21 @@ if(ENABLE_BNR)
     target_link_libraries(AetherSDR PRIVATE ${GRPC_LIBRARIES} ${PROTOBUF_LIBRARIES})
 endif()
 
+if(AETHER_GPU_SPECTRUM)
+    target_compile_definitions(AetherSDR PRIVATE AETHER_GPU_SPECTRUM)
+    if(TARGET Qt6::GuiPrivate)
+        target_link_libraries(AetherSDR PRIVATE Qt6::GuiPrivate)
+    endif()
+    qt_add_shaders(AetherSDR "aether_shaders"
+        PREFIX "/shaders"
+        FILES
+            resources/shaders/texturedquad.vert
+            resources/shaders/texturedquad.frag
+            resources/shaders/overlay.vert
+            resources/shaders/overlay.frag
+    )
+endif()
+
 if(HAVE_PIPEWIRE)
     target_compile_definitions(AetherSDR PRIVATE HAVE_PIPEWIRE)
     message(STATUS "Linux DAX bridge enabled (PulseAudio pipe modules)")

README.md

@@ -66,25 +66,51 @@ Pre-built binaries are available from [Releases](https://github.com/ten9876/Aeth
 
 ## Building from Source
 
-### Dependencies (Linux)
+### Dependencies
+
+Install all dependencies for a full-featured build. Optional packages are noted — the build succeeds without them but the corresponding features are disabled.
 
 ```bash
 # Arch / CachyOS / Manjaro
-sudo pacman -S qt6-base qt6-multimedia cmake ninja pkgconf autoconf automake libtool
+sudo pacman -S qt6-base qt6-multimedia qt6-websockets qt6-serialport \
+  qt6-shadertools cmake ninja pkgconf autoconf automake libtool \
+  fftw portaudio hidapi qtkeychain-qt6
 
 # Ubuntu 24.04+ / Debian / Linux Mint
-sudo apt install qt6-base-dev qt6-multimedia-dev cmake ninja-build pkg-config \
-  autoconf automake libtool gstreamer1.0-pulseaudio gstreamer1.0-plugins-base \
-  libxkbcommon-dev portaudio19-dev libfftw3-dev
+sudo apt install qt6-base-dev qt6-base-private-dev qt6-multimedia-dev \
+  qt6-websockets-dev qt6-serialport-dev qt6-shader-baker qt6-shadertools-dev \
+  cmake ninja-build pkg-config autoconf automake libtool \
+  libfftw3-dev portaudio19-dev libhidapi-dev qtkeychain-qt6-dev \
+  libxkbcommon-dev gstreamer1.0-pulseaudio gstreamer1.0-plugins-base
 
 # Fedora
-sudo dnf install qt6-qtbase-devel qt6-qtmultimedia-devel cmake ninja-build \
-  autoconf automake libtool
+sudo dnf install qt6-qtbase-devel qt6-qtbase-private-devel qt6-qtmultimedia-devel \
+  qt6-qtwebsockets-devel qt6-qtserialport-devel qt6-qtshadertools-devel \
+  cmake ninja-build autoconf automake libtool \
+  fftw3-devel portaudio-devel hidapi-devel qtkeychain-qt6-devel
 
 # macOS (Homebrew)
-brew install qt@6 ninja cmake pkgconf autoconf automake libtool
+brew install qt@6 ninja cmake pkgconf autoconf automake libtool \
+  fftw portaudio hidapi qtkeychain
 ```
 
+<details>
+<summary>What each dependency enables</summary>
+
+| Package | Feature |
+|---------|---------|
+| qt6-base, qt6-multimedia | Core application (required) |
+| qt6-base-private-dev | GPU-accelerated spectrum/waterfall (QRhi) |
+| qt6-shadertools-dev | GPU shader compilation |
+| qt6-websockets-dev | TCI server, FreeDV Reporter spots |
+| qt6-serialport-dev | FlexControl, serial PTT/CW, MIDI controllers |
+| libfftw3-dev | NR2 spectral noise reduction |
+| portaudio19-dev | PortAudio audio backend |
+| libhidapi-dev | StreamDeck, USB HID encoders (RC-28, PowerMate) |
+| qtkeychain-qt6-dev | SmartLink credential persistence |
+
+</details>
+
 > **Linux Mint / Ubuntu note:** If PC audio devices show as "Dummy Output",
 > install `gstreamer1.0-pulseaudio`. For PipeWire systems, also install `gstreamer1.0-pipewire`.
 

resources/shaders/overlay.frag

@@ -0,0 +1,11 @@
+#version 440
+
+layout(location = 0) in vec2 v_uv;
+layout(location = 0) out vec4 fragColor;
+
+layout(binding = 1) uniform sampler2D tex;
+
+void main()
+{
+    fragColor = texture(tex, v_uv);
+}

resources/shaders/overlay.vert

@@ -0,0 +1,12 @@
+#version 440
+
+layout(location = 0) in vec2 position;
+layout(location = 1) in vec2 texcoord;
+
+layout(location = 0) out vec2 v_uv;
+
+void main()
+{
+    gl_Position = vec4(position, 0.0, 1.0);
+    v_uv = texcoord;
+}

resources/shaders/texturedquad.frag

@@ -0,0 +1,20 @@
+#version 440
+
+layout(location = 0) in vec2 v_uv;
+layout(location = 0) out vec4 fragColor;
+
+layout(binding = 1) uniform sampler2D tex;
+
+layout(std140, binding = 0) uniform Uniforms {
+    float rowOffset;
+    float padding1;
+    float padding2;
+    float padding3;
+};
+
+void main()
+{
+    // Apply ring buffer offset per-pixel (not per-vertex, to avoid fract() interpolation issue)
+    vec2 uv = vec2(v_uv.x, fract(v_uv.y + rowOffset));
+    fragColor = texture(tex, uv);
+}