feat(slint): wgpu fragment-shader underlay spike for ImmersiveView

Swap the winit renderer femtovg(GL) -> femtovg-wgpu (+ unstable-wgpu-28,
slint pinned =1.16.1) and render a WGSL plasma fragment shader into a wgpu
texture composited under ImmersiveView. The shader is fed by the existing
30fps visualizer drain (sub-bass energy + decayed transient) and toggled
in-view with the 'g' key via ImmersiveState.shader-mode; when active it
replaces the atmosphere + mode panels as the bottom layer, chrome stays on
top. Device/queue captured from Slint's rendering notifier so Image::try_from
shares Slint's wgpu device.

Phase 0 spike: validates the app-wide renderer swap with no font/UI/tray
regression. Pending macOS Metal smoke before the swap lands on slint-mvp.

cc
This commit is contained in:
vicrodh committed 2026-06-14 10:59:56 -06:00
1 parent b03c8fcb5c
commit e46e85546a
8 files changed
+835 -41

No files matched your search

+13 -3
View File
@@ -11,16 +11,26 @@ name = "qbz-slint"
path = "src/main.rs"
[dependencies]
# femtovg renderer, pinned >=1.16 for the femtovg text-rendering fixes
# femtovg renderer, pinned =1.16.1 for the femtovg text-rendering fixes
# (slint-ui/slint #5177 pixel-grid alignment + #11335 0.5px tearing /
# inconsistent glyph spacing). Skia never received that treatment.
slint = { version = "1.16", default-features = false, features = [
#
# WGPU UNDERLAY SPIKE (feature/wgpu-underlay-spike branch only): the renderer is
# swapped femtovg(GL) -> femtovg-wgpu so we can render WGSL fragment shaders into
# a wgpu texture composited under the ImmersiveView. femtovg-wgpu is the SAME
# femtovg rasterizer on a wgpu backend, so the text fixes above are KEPT. This is
# the one consequential, app-wide change being validated by the spike. The exact
# version is pinned to =1.16.1 because the wgpu_28 module / GraphicsAPI::WGPU28 /
# require_wgpu_28 are behind an `unstable-*` flag that may change on a minor bump.
# To A/B against the GL build: `git checkout slint-mvp`.
slint = { version = "=1.16.1", default-features = false, features = [
"std",
"backend-winit",
"renderer-femtovg",
"renderer-femtovg-wgpu",
"renderer-software",
"accessibility",
"compat-1-2",
"unstable-wgpu-28",
] }
# Direct access to the winit backend for the system tray: WinitWindowAccessor
# (hide/show the OS window without quitting the event loop) and, later, the
+38
View File
@@ -88,6 +88,8 @@ mod recently;
mod scrobble;
mod scrobbler_settings;
mod search;
// WGPU UNDERLAY SPIKE: GPU fragment-shader background for ImmersiveView.
mod shader_underlay;
mod settings;
mod share;
mod sidebar;
@@ -3941,6 +3943,17 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
let tokio_rt = tokio::runtime::Runtime::new()?;
let _enter = tokio_rt.enter();
// WGPU UNDERLAY SPIKE: select a wgpu-capable backend BEFORE the first window
// is created. require_wgpu_28 forces the winit backend (the only one that
// honours a graphics-API request) — which the app already uses, so the tray's
// WinitWindowAccessor stays valid. The renderer is femtovg-wgpu (Cargo.toml),
// so the femtovg text pipeline is preserved. Automatic config lets Slint init
// wgpu (downlevel-webgl2 limits — fine for fragment-only shaders). If this
// ever fails on the owner's GPU/driver, that failure IS the spike result.
slint::BackendSelector::new()
.require_wgpu_28(slint::wgpu_28::WGPUConfiguration::default())
.select()?;
let window = AppWindow::new()?;
// FONT TEST (slint-mvp): render with bundled Inter 18pt. Inter is a
// clean, screen-tuned UI face; combined with the femtovg #5177/#11335
@@ -3976,6 +3989,31 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
// opens. Must run on the UI thread before window.run().
visualizer::install(&window, &app_runtime);
// WGPU UNDERLAY SPIKE: capture Slint's own wgpu Device/Queue at RenderingSetup
// so shader_underlay allocates its texture + submits on the SAME device Slint
// renders with (mandatory for Image::try_from). The render itself happens in
// the 30fps drain (visualizer.rs). Only one rendering notifier is allowed per
// window; the shader underlay owns it. Errors here are non-fatal — the shader
// just stays dark and the rest of the UI is unaffected.
if let Err(e) = window
.window()
.set_rendering_notifier(move |state, graphics_api| {
match state {
slint::RenderingState::RenderingSetup => {
if let slint::GraphicsAPI::WGPU28 { device, queue, .. } = graphics_api {
crate::shader_underlay::setup(device.clone(), queue.clone());
}
}
slint::RenderingState::RenderingTeardown => {
crate::shader_underlay::teardown();
}
_ => {}
}
})
{
log::warn!("[shader] set_rendering_notifier failed: {e:?} — underlay disabled");
}
// MusicBrainz cache — opens a SQLite store at
// <data-dir>/qbz/cache/musicbrainz_cache.db so artist metadata
// and relationships persist across sessions (matches Tauri's
+244
View File
@@ -0,0 +1,244 @@
//! WGPU UNDERLAY SPIKE — GPU fragment-shader background for the ImmersiveView.
//!
//! Validates the renderer-swap path (`renderer-femtovg` GL -> `renderer-femtovg-wgpu`)
//! by rendering a WGSL fragment shader into a wgpu texture and handing it back to
//! Slint as an `Image` (the texture-into-scene shape from Slint's upstream
//! `wgpu_texture` example). The texture is bound to an `Image` placed at the
//! bottom of `ImmersiveView`'s z-stack (see ui/immersive/ImmersiveView.slint).
//!
//! Lifecycle:
//! * `setup()` is called once by the rendering notifier in main.rs at
//! `RenderingState::RenderingSetup`, with Slint's OWN wgpu Device/Queue —
//! mandatory so `Image::try_from` operates on the same device Slint renders
//! with. It builds the pipeline + uniform buffer + bind group (persistent).
//! * `render_frame()` is called from the 30 fps drain in visualizer.rs while a
//! shader scene is active. It renders one frame into a FRESH texture (the
//! documented upstream pattern — avoids read-while-write aliasing) and
//! returns an `Image`. The caller sets it on `ImmersiveState.shader-texture`.
//! * `teardown()` clears the state at `RenderingState::RenderingTeardown`.
//!
//! All three run on the UI thread (notifier + Timer share it), so the state lives
//! in a `thread_local`. This file is downstream of the read-only visualizer feed
//! and touches NONE of the protected audio backend.
use std::cell::RefCell;
use slint::wgpu_28::wgpu;
use slint::Image;
/// Offscreen render target size. The `Image` is shown with `image-fit: fill`, so
/// the immersive viewport stretches this to fit. A plasma is organic/soft, so a
/// fixed 720p target is plenty sharp for the spike (HiDPI-correct sizing is a
/// Phase-1 concern, not a spike gate).
const TEX_W: u32 = 1280;
const TEX_H: u32 = 720;
const TEX_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;
/// Mirrors the WGSL `Uniforms` struct (ui/shaders/plasma.wgsl). `#[repr(C)]` +
/// explicit padding keeps it vec4-aligned (32 bytes) for std140 uniform layout.
#[repr(C)]
#[derive(Clone, Copy)]
struct Uniforms {
time: f32,
energy0: f32,
transient: f32,
_pad0: f32,
res_x: f32,
res_y: f32,
_pad1: f32,
_pad2: f32,
}
/// View `Uniforms` as raw bytes for `Queue::write_buffer`. Sound: `Uniforms` is
/// `#[repr(C)]`, all-`f32`, no padding holes with undefined values we read back —
/// every byte is part of a defined `f32` field.
fn uniforms_bytes(u: &Uniforms) -> &[u8] {
unsafe {
std::slice::from_raw_parts(
(u as *const Uniforms) as *const u8,
std::mem::size_of::<Uniforms>(),
)
}
}
struct RenderState {
device: wgpu::Device,
queue: wgpu::Queue,
pipeline: wgpu::RenderPipeline,
uniform_buf: wgpu::Buffer,
bind_group: wgpu::BindGroup,
start: std::time::Instant,
}
thread_local! {
static STATE: RefCell<Option<RenderState>> = const { RefCell::new(None) };
}
/// Build the persistent pipeline from Slint's device/queue. Called once at
/// `RenderingSetup`. Idempotent-ish: a second call rebuilds (cheap; only happens
/// if the rendering surface is torn down and re-created).
pub fn setup(device: wgpu::Device, queue: wgpu::Queue) {
let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: Some("qbz-plasma-shader"),
source: wgpu::ShaderSource::Wgsl(include_str!("../ui/shaders/plasma.wgsl").into()),
});
let bgl = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
label: Some("qbz-shader-bgl"),
entries: &[wgpu::BindGroupLayoutEntry {
binding: 0,
visibility: wgpu::ShaderStages::FRAGMENT,
ty: wgpu::BindingType::Buffer {
ty: wgpu::BufferBindingType::Uniform,
has_dynamic_offset: false,
min_binding_size: None,
},
count: None,
}],
});
let uniform_buf = device.create_buffer(&wgpu::BufferDescriptor {
label: Some("qbz-shader-uniforms"),
size: std::mem::size_of::<Uniforms>() as u64,
usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let bind_group = device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("qbz-shader-bg"),
layout: &bgl,
entries: &[wgpu::BindGroupEntry {
binding: 0,
resource: uniform_buf.as_entire_binding(),
}],
});
let pipeline_layout = device.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
label: Some("qbz-shader-pl"),
bind_group_layouts: &[&bgl],
// wgpu 28.x: replaces `push_constant_ranges`. We use none.
immediate_size: 0,
});
let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
label: Some("qbz-shader-pipeline"),
layout: Some(&pipeline_layout),
vertex: wgpu::VertexState {
module: &module,
entry_point: Some("vs_main"),
compilation_options: wgpu::PipelineCompilationOptions::default(),
buffers: &[],
},
primitive: wgpu::PrimitiveState::default(),
depth_stencil: None,
multisample: wgpu::MultisampleState::default(),
fragment: Some(wgpu::FragmentState {
module: &module,
entry_point: Some("fs_main"),
compilation_options: wgpu::PipelineCompilationOptions::default(),
targets: &[Some(wgpu::ColorTargetState {
format: TEX_FORMAT,
blend: None,
write_mask: wgpu::ColorWrites::ALL,
})],
}),
multiview_mask: None,
cache: None,
});
STATE.with(|s| {
*s.borrow_mut() = Some(RenderState {
device,
queue,
pipeline,
uniform_buf,
bind_group,
start: std::time::Instant::now(),
});
});
log::info!("[shader] wgpu underlay pipeline ready ({TEX_W}x{TEX_H} {TEX_FORMAT:?})");
}
/// Drop the pipeline at surface teardown.
pub fn teardown() {
STATE.with(|s| *s.borrow_mut() = None);
log::info!("[shader] wgpu underlay torn down");
}
/// Render one frame into a fresh texture and return it as a Slint `Image`.
/// Returns `None` before `setup()` has run. Driven at 30 fps from visualizer.rs.
pub fn render_frame(energy0: f32, transient: f32) -> Option<Image> {
STATE.with(|s| {
let borrow = s.borrow();
let st = borrow.as_ref()?;
let uniforms = Uniforms {
time: st.start.elapsed().as_secs_f32(),
energy0,
transient,
_pad0: 0.0,
res_x: TEX_W as f32,
res_y: TEX_H as f32,
_pad1: 0.0,
_pad2: 0.0,
};
st.queue
.write_buffer(&st.uniform_buf, 0, uniforms_bytes(&uniforms));
// Fresh target each frame. Image::try_from REQUIRES Rgba8Unorm/Srgb +
// TEXTURE_BINDING | RENDER_ATTACHMENT (Slint graphics/wgpu_28.rs).
let texture = st.device.create_texture(&wgpu::TextureDescriptor {
label: Some("qbz-shader-target"),
size: wgpu::Extent3d {
width: TEX_W,
height: TEX_H,
depth_or_array_layers: 1,
},
mip_level_count: 1,
sample_count: 1,
dimension: wgpu::TextureDimension::D2,
format: TEX_FORMAT,
usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::RENDER_ATTACHMENT,
view_formats: &[],
});
let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
let mut encoder = st
.device
.create_command_encoder(&wgpu::CommandEncoderDescriptor {
label: Some("qbz-shader-encoder"),
});
{
let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
label: Some("qbz-shader-pass"),
color_attachments: &[Some(wgpu::RenderPassColorAttachment {
view: &view,
depth_slice: None,
resolve_target: None,
ops: wgpu::Operations {
load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
store: wgpu::StoreOp::Store,
},
})],
depth_stencil_attachment: None,
timestamp_writes: None,
occlusion_query_set: None,
// wgpu 28.x render passes also carry the multiview layer mask;
// we don't use multiview (single 2D target), so None.
multiview_mask: None,
});
pass.set_pipeline(&st.pipeline);
pass.set_bind_group(0, &st.bind_group, &[]);
pass.draw(0..3, 0..1);
}
st.queue.submit(Some(encoder.finish()));
match Image::try_from(texture) {
Ok(img) => Some(img),
Err(e) => {
log::warn!("[shader] Image::try_from failed: {e:?}");
None
}
}
})
}
+24 -1
View File
@@ -25,7 +25,7 @@ use qbz_audio::visualizer::{spawn_visualizer_thread, VizFrame, VizSink};
use slint::{ComponentHandle, Model, ModelRc, VecModel};
use crate::adapter::SlintAdapter;
use crate::{AppWindow, VisualizerState};
use crate::{AppWindow, ImmersiveState, VisualizerState};
/// Single-slot, latest-wins frame store shared with the FFT producer thread.
/// Each cell holds at most the most recent frame for that stream; the UI drain
@@ -102,6 +102,12 @@ pub fn install(window: &AppWindow, runtime: &Arc<AppRuntime<SlintAdapter>>) {
// ~30 fps drain on the UI thread: copy the latest frames into the models.
let weak = window.as_weak();
let timer = slint::Timer::default();
// WGPU UNDERLAY SPIKE: latest sub-bass + transient kept across ticks so the
// shader animates smoothly (its own time accumulator) and only *reacts* at
// 30 fps. `last_tr` decays each tick so a one-frame transient produces a
// visible multi-frame flash (matching how SpectrumPanel decays it).
let mut last_e0 = 0.0f32;
let mut last_tr = 0.0f32;
timer.start(
slint::TimerMode::Repeated,
std::time::Duration::from_millis(33),
@@ -115,6 +121,7 @@ pub fn install(window: &AppWindow, runtime: &Arc<AppRuntime<SlintAdapter>>) {
for (i, v) in b.iter().enumerate() {
energy.set_row_data(i, *v);
}
last_e0 = b[0];
}
if let Some(b) = cells.spectral.lock().unwrap().take() {
for (i, v) in b.iter().enumerate() {
@@ -130,6 +137,22 @@ pub fn install(window: &AppWindow, runtime: &Arc<AppRuntime<SlintAdapter>>) {
if let Some(w) = weak.upgrade() {
w.global::<VisualizerState>().set_transient(x);
}
last_tr = x.max(last_tr);
}
// WGPU UNDERLAY SPIKE: render one GPU shader frame into the wgpu
// texture and hand it to ImmersiveState. Only runs while a shader
// scene is active (shader-mode > 0); otherwise zero GPU cost. The
// device/queue were captured by the rendering notifier (main.rs);
// render_frame is a no-op until that fires.
last_tr *= 0.85;
if let Some(w) = weak.upgrade() {
let imm = w.global::<ImmersiveState>();
if imm.get_shader_mode() > 0 {
if let Some(img) = crate::shader_underlay::render_frame(last_e0, last_tr) {
imm.set_shader_texture(img);
}
}
}
},
);
@@ -566,6 +566,15 @@ export component ImmersiveView inherits Rectangle {
VisualizerState.set-enabled(false);
return accept;
}
// WGPU UNDERLAY SPIKE: 'g' (GPU) toggles the shader scene on/off in
// place so the owner can A/B the shader vs the existing atmosphere /
// panels in a single run. Remove (or repurpose to a real picker)
// once the spike is validated.
if (event.text == "g" || event.text == "G") {
ImmersiveState.shader-mode = ImmersiveState.shader-mode > 0 ? 0 : 1;
root.wake();
return accept;
}
return reject;
}
focus-timer := Timer {
@@ -593,8 +602,23 @@ export component ImmersiveView inherits Rectangle {
changed mouse-y => { root.wake(); }
}
// (1) Bottom: moving blurred-art atmosphere.
ImmersiveAtmosphere {
// (0) WGPU UNDERLAY SPIKE: the GPU fragment-shader texture, the bottom-most
// layer when a shader scene is active. ADR-010 conditional mount. When
// shader-mode > 0 it REPLACES the atmosphere (layer 1) and the mode panels
// (layer 2) so the shader is the visible background; the chrome below stays
// on top. Driven at ~30 fps from src/visualizer.rs -> shader_underlay.
if ImmersiveState.shader-mode > 0: Image {
x: 0px;
y: 0px;
width: 100%;
height: 100%;
image-fit: fill;
source: ImmersiveState.shader-texture;
}
// (1) Bottom: moving blurred-art atmosphere. Hidden while a shader scene is
// active (the shader owns the background layer instead).
if ImmersiveState.shader-mode == 0: ImmersiveAtmosphere {
source-image: ImmersiveState.bg-image;
fallback-image: NowPlayingState.artwork-large.width > 0
? NowPlayingState.artwork-large
@@ -606,7 +630,7 @@ export component ImmersiveView inherits Rectangle {
// (ADR-010). Mode 0 = Album Reactive (the only real foreground this
// session). Modes 1/2/3 mount NO foreground — the atmosphere is the
// explicit placeholder until those sessions land.
if ImmersiveState.mode == 0: AlbumReactivePanel {
if ImmersiveState.shader-mode == 0 && ImmersiveState.mode == 0: AlbumReactivePanel {
x: 0px;
y: 0px;
viewport-width: root.width;
@@ -614,7 +638,7 @@ export component ImmersiveView inherits Rectangle {
}
// (2b) Static mode foreground (mode == 1) — calm centered now-playing
// card over the atmosphere. Same conditional-mount pattern (ADR-010).
if ImmersiveState.mode == 1: StaticPanel {
if ImmersiveState.shader-mode == 0 && ImmersiveState.mode == 1: StaticPanel {
x: 0px;
y: 0px;
viewport-width: root.width;
@@ -626,7 +650,7 @@ export component ImmersiveView inherits Rectangle {
// click, no 3D / reflection / gradient / 500ms reflow). True-3D rotateY/
// perspective remains deferred to a wgpu/Skia session. Same conditional-mount
// + viewport-prop contract as the siblings (ADR-010).
if ImmersiveState.mode == 2: CoverflowPanel {
if ImmersiveState.shader-mode == 0 && ImmersiveState.mode == 2: CoverflowPanel {
x: 0px;
y: 0px;
viewport-width: root.width;
@@ -639,7 +663,7 @@ export component ImmersiveView inherits Rectangle {
// ALREADY driven on open (the mode-0 AlbumReactivePanel reads
// VisualizerState.energy from the same enabled tap). Same conditional-mount +
// viewport-prop contract as the siblings (ADR-010).
if ImmersiveState.mode == 3: SpectrumPanel {
if ImmersiveState.shader-mode == 0 && ImmersiveState.mode == 3: SpectrumPanel {
x: 0px;
y: 0px;
viewport-width: root.width;
+73
View File
@@ -0,0 +1,73 @@
// WGPU UNDERLAY SPIKE — plasma fragment shader.
//
// One fullscreen-triangle pass. The fragment stage is a classic sin-field
// plasma, audio-reactive via the sub-bass energy (u.energy0) and a decayed
// transient (u.transient). This shader's only job is to prove the GPU
// fragment-shader path works end to end (renderer swap -> wgpu texture ->
// Slint Image), NOT to be a final look. The Neon/Audio-Cube catalog replaces
// it once the spike is validated.
//
// CPU side: src/shader_underlay.rs. Uniform layout must stay in lockstep with
// the `Uniforms` #[repr(C)] struct there (vec4-aligned, 32 bytes).
struct Uniforms {
time: f32,
energy0: f32,
transient: f32,
_pad0: f32,
resolution: vec2<f32>,
_pad1: vec2<f32>,
};
@group(0) @binding(0) var<uniform> u: Uniforms;
struct VsOut {
@builtin(position) clip: vec4<f32>,
@location(0) uv: vec2<f32>,
};
@vertex
fn vs_main(@builtin(vertex_index) vid: u32) -> VsOut {
// Oversized triangle covering the whole clip space (the classic
// fullscreen-triangle trick — no vertex buffer needed).
var verts = array<vec2<f32>, 3>(
vec2<f32>(-1.0, -1.0),
vec2<f32>( 3.0, -1.0),
vec2<f32>(-1.0, 3.0),
);
let p = verts[vid];
var out: VsOut;
out.clip = vec4<f32>(p, 0.0, 1.0);
out.uv = p * 0.5 + vec2<f32>(0.5, 0.5);
return out;
}
@fragment
fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
let t = u.time;
let bass = clamp(u.energy0, 0.0, 1.0);
let tr = clamp(u.transient, 0.0, 1.0);
// Plasma field: bass widens the spatial frequency so the pattern "breathes".
let scale = 3.0 + bass * 6.0;
let p = in.uv * scale;
var v = 0.0;
v += sin(p.x * 3.0 + t);
v += sin((p.y * 3.0 + t) * 0.7);
v += sin((p.x + p.y) * 2.0 + t * 1.3);
let cx = p.x + 0.5 * sin(t * 0.4);
let cy = p.y + 0.5 * cos(t * 0.6);
v += sin(sqrt(cx * cx + cy * cy) * 6.0 + t);
v = v * 0.25;
let pi = 3.14159265;
let r = sin(v * pi + 0.0) * 0.5 + 0.5;
let g = sin(v * pi + 2.094) * 0.5 + 0.5;
let b = sin(v * pi + 4.188) * 0.5 + 0.5;
var col = vec3<f32>(r, g, b);
// Bass lifts overall brightness; a transient adds a brief white flash.
col = col * (0.55 + bass * 0.85) + vec3<f32>(tr * 0.6);
col = clamp(col, vec3<f32>(0.0), vec3<f32>(1.0));
return vec4<f32>(col, 1.0);
}
+10
View File
@@ -2977,6 +2977,16 @@ export global ImmersiveState {
// Defaults = the Svelte cyan -> purple until the art resolves.
in property <color> spectrum-primary: #00dcc8;
in property <color> spectrum-secondary: #9632ff;
// WGPU UNDERLAY SPIKE: a GPU fragment shader rendered into a wgpu texture by
// src/shader_underlay.rs and handed back here each drain tick. `shader-mode`
// selects the scene: 0 = OFF (use the existing atmosphere + panels), >0 = a
// shader scene (1 = plasma spike). When >0 the atmosphere + the mode panels
// are hidden so the shader is the visible background; the auto-hide chrome
// (mode picker + compact player) stays on top. Toggle in-view with the 'g'
// key during the spike.
in property <image> shader-texture;
in-out property <int> shader-mode: 0;
}
// Now-playing / transport state. The Rust playback poll loop pushes the