Headless pictures draw on the GPU, with the viewport's pipelines (CPU rasterizer as last tier) (#1555)

Thanks @jyviko.

apps/solidcraft-cli/Cargo.toml

@@ -21,5 +21,10 @@ path = "src/alias.rs"
 
 [dependencies]
 solidcraft-engine = { workspace = true }
+solidcraft-gpu = { workspace = true }
 solidcraft-mcp = { workspace = true }
 serde_json = { workspace = true }
+
+[dev-dependencies]
+# Snapshot tests decode the pictures to compare them with a tolerance.
+image = { workspace = true }

apps/solidcraft-cli/src/main.rs

@@ -34,7 +34,6 @@ use serde_json::{Value, json};
 mod app_icon;
 
 use solidcraft_engine::Session;
-use solidcraft_engine::render::render_png;
 use solidcraft_engine::view::Guides;
 
 const USAGE: &str = "usage:
@@ -63,6 +62,10 @@ const USAGE: &str = "usage:
   solidcraft-cli mcp [--in design.solidcraft|script.json] [--connect 127.0.0.1:PORT [--token T]] [--allow-path DIR]... [--allow-any-path]
   solidcraft-cli crashes [list [--json] | show <id> | replay <id> | dir | clear [<id>]]
   solidcraft-cli licences
+  solidcraft-cli gpu [--policy auto|hardware|software|cpu]
+      (the GPU adapters a headless render can open, best first, the one the policy picks and the tier it
+       lands on: gpu, gpu-software, or the CPU rasterizer (auto with no adapter, or cpu); the policy defaults
+       to SOLIDCRAFT_GPU, else auto; exits with an error when hardware or software finds no such adapter)
   solidcraft-cli icon --out icon.png [--size 256] | --out icon.ico
 ";
 
@@ -75,6 +78,7 @@ fn main() -> ExitCode {
         Some("snapshot") => cmd_snapshot(&args[1..]),
         Some("render") => render::run(&args[1..]),
         Some("exec") => cmd_exec(&args[1..]),
+        Some("gpu") => cmd_gpu(&args[1..]),
         Some("commands") => {
             use std::io::Write as _;
             let mut s = Session::default();
@@ -213,6 +217,7 @@ fn print_json(v: &Value, file: Option<&str>) -> Result<(), String> {
 }
 
 fn cmd_run(args: &[String]) -> Result<(), String> {
+    install_renderer();
     let json_out = json_out(args)?;
     let base = flag(args, "--in");
     let path = positional(args);
@@ -334,13 +339,59 @@ fn cmd_script(args: &[String]) -> Result<(), String> {
     Ok(())
 }
 
+/// `gpu`: the headless adapter survey and the policy's pick.
+fn cmd_gpu(args: &[String]) -> Result<(), String> {
+    use solidcraft_gpu::select::{Policy, survey};
+    let policy = match args {
+        [] => Policy::from_env()?,
+        [flag, v] if flag == "--policy" => Policy::parse(v).ok_or_else(|| format!("--policy must be auto, hardware, software or cpu, not `{v}`"))?,
+        _ => return Err("usage: solidcraft-cli gpu [--policy auto|hardware|software|cpu]".into()),
+    };
+    let s = survey(policy);
+    let chosen = s.chosen.and_then(|i| s.adapters.get(i)).cloned();
+    // The tier pictures land on: a hardware GPU, a software adapter, or the CPU rasterizer.
+    let renderer = s.lands_on.map(|l| l.renderer());
+    println!(
+        "{}",
+        pretty(&json!({
+            "policy": policy.name(),
+            "backends": s.backends,
+            "adapters": s.adapters,
+            "chosen": chosen,
+            "lands_on": s.lands_on,
+            "renderer": renderer,
+        }))
+    );
+    match s.lands_on {
+        Some(solidcraft_gpu::select::Landing::Cpu) => {
+            eprintln!("warning: {}", solidcraft_engine::capture::CPU_WARNING);
+            Ok(())
+        }
+        Some(_) => Ok(()),
+        None => Err(format!("no adapter qualifies under the {} policy", policy.name())),
+    }
+}
+
+/// Draw this process's pictures (snapshots, MCP screenshots, saved thumbnails) on the GPU with the
+/// viewport's pipelines: the headless device the `SOLIDCRAFT_GPU` policy picks, opened on the first
+/// picture; under `auto` with no qualifying adapter (or `cpu`), the CPU rasterizer, and the
+/// picture says so. Under `hardware` or `software` with no such adapter a picture fails with an
+/// error that names the policy.
+fn install_renderer() {
+    solidcraft_engine::capture::install(std::sync::Arc::new(|scene, cam, w, h| {
+        let (rgba, renderer) = solidcraft_gpu::capture::headless_rgba(scene, cam, w, h)?;
+        Ok(solidcraft_engine::capture::Picture { rgba, renderer })
+    }));
+}
+
 fn cmd_snapshot(args: &[String]) -> Result<(), String> {
+    install_renderer();
     known_flags("snapshot", args, &["--in", "--out", "--width", "--height", "--view", "--camera"], &["--no-grid", "--no-axes"])?;
     if positional(args).is_none() && flag(args, "--in").is_none() {
         return Err(USAGE.to_string());
     }
     let out = flag(args, "--out").ok_or("snapshot needs --out FILE.png")?;
-    let size = |name: &str, default: usize| match flag(args, name) {
+    let size = |name: &str, default: u32| match flag(args, name) {
         None => Ok(default),
         Some(x) => x.parse().ok().filter(|n| (16..=8192).contains(n)).ok_or_else(|| format!("{name} must be 16 to 8192 pixels, not `{x}`")),
     };
@@ -364,9 +415,14 @@ fn cmd_snapshot(args: &[String]) -> Result<(), String> {
     let cam = s.camera.unwrap_or_else(|| solidcraft_engine::view::home_camera(&s));
     let guides = Guides { grid: !args.iter().any(|a| a == "--no-grid"), axes: !args.iter().any(|a| a == "--no-axes") };
     let scene = solidcraft_engine::view::scene_with_guides(&s, &cam, s.section, guides);
-    let png = render_png(&scene, &cam, w, h).ok_or("render failed")?;
-    std::fs::write(out, &png).map_err(|e| format!("{out}: {e}"))?;
-    println!("{}", pretty(&json!({"path": out, "width": w, "height": h, "bytes": png.len()})));
+    let png = solidcraft_engine::capture::png(&scene, &cam, w, h)?;
+    std::fs::write(out, &png.bytes).map_err(|e| format!("{out}: {e}"))?;
+    let mut reply = json!({"path": out, "width": w, "height": h, "bytes": png.bytes.len(), "renderer": png.renderer});
+    if let Some(w) = solidcraft_engine::capture::warning(png.renderer) {
+        eprintln!("warning: {w}");
+        reply["warning"] = json!(w);
+    }
+    println!("{}", pretty(&reply));
     Ok(())
 }
 
@@ -412,6 +468,7 @@ fn ico(images: &[(usize, Vec<u8>)]) -> Result<Vec<u8>, String> {
 }
 
 fn cmd_exec(args: &[String]) -> Result<(), String> {
+    install_renderer();
     let id = args.first().ok_or_else(|| USAGE.to_string())?;
     let p: Value = match args.get(1) {
         Some(t) => serde_json::from_str(t).map_err(|e| format!("params: {e}"))?,
@@ -427,6 +484,7 @@ fn cmd_exec(args: &[String]) -> Result<(), String> {
 /// a running app's control port. stdout carries only protocol messages. Files the agent's tool
 /// calls reach are confined to `solidcraft_mcp::agent_scope` unless `--allow-any-path` is given.
 fn cmd_mcp(args: &[String]) -> Result<(), String> {
+    install_renderer();
     let scope = (!args.iter().any(|a| a == "--allow-any-path"))
         .then(|| solidcraft_mcp::agent_scope(flags(args, "--allow-path").into_iter().map(std::path::PathBuf::from)));
     if let Some(s) = &scope {

apps/solidcraft-cli/tests/run_results.rs

@@ -151,11 +151,20 @@ fn snapshot_runs_its_script_on_the_in_design() {
         json_output(cli().arg("snapshot").args(args).arg("--out").arg(&png).args(["--width", "64", "--height", "48"]).output().unwrap());
         std::fs::read(&png).unwrap()
     };
-    let alone = shot("alone.png", &[shifted.as_os_str()]);
-    let on_base = shot("on_base.png", &[shifted.as_os_str(), "--in".as_ref(), base.as_os_str()]);
-    let base_only = shot("base.png", &["--in".as_ref(), base.as_os_str()]);
-    assert_ne!(alone, on_base, "the script ran on the --in design");
-    assert_ne!(base_only, on_base);
+    // Pictures are drawn on the GPU: without an adapter only the option checks below run.
+    match solidcraft_gpu::capture::shared() {
+        Ok(_) => {
+            let alone = shot("alone.png", &[shifted.as_os_str()]);
+            let on_base = shot("on_base.png", &[shifted.as_os_str(), "--in".as_ref(), base.as_os_str()]);
+            let base_only = shot("base.png", &["--in".as_ref(), base.as_os_str()]);
+            assert_ne!(alone, on_base, "the script ran on the --in design");
+            assert_ne!(base_only, on_base);
+        }
+        Err(e @ solidcraft_gpu::GpuError::NoAdapter(_)) if std::env::var_os("SOLIDCRAFT_REQUIRE_GPU").is_none() => {
+            eprintln!("pictures left out: {e}")
+        }
+        Err(e) => panic!("{e}"),
+    }
     for (bad, says) in [(["--frobnicate", "1"], "doesn't take --frobnicate"), (["--width", "wide"], "--width must be 16 to 8192")] {
         let output = cli().arg("snapshot").arg(&base).arg("--out").arg(dir.0.join("x.png")).args(bad).output().unwrap();
         assert_eq!(output.status.code(), Some(1));

apps/solidcraft-cli/tests/snapshot_camera.rs

@@ -1,6 +1,8 @@
 //! `snapshot` frames its picture like the MCP `screenshot`: from a camera, a view saved in the
 //! design or one the script applies itself, and without the ground grid and the origin's axes
-//! when asked (the grid lies on Z 0 and cuts through a part that straddles it).
+//! when asked (the grid lies on Z 0 and cuts through a part that straddles it). Pictures are drawn
+//! on the GPU and compared with a tolerance; without a GPU adapter the tests that draw are skipped
+//! with the reason printed (`SOLIDCRAFT_REQUIRE_GPU=1` makes that a failure).
 
 use std::path::{Path, PathBuf};
 use std::process::{Command, Output};
@@ -12,7 +14,52 @@ use solidcraft_mcp::{Headless, Server};
 
 static NEXT: AtomicUsize = AtomicUsize::new(0);
 
-const SIZE: (usize, usize) = (160, 100);
+/// Whether pictures can be drawn here; installs the renderer the CLI installs, so the MCP
+/// `screenshot` in this process draws as `solidcraft-cli mcp` does.
+fn gpu() -> bool {
+    match solidcraft_gpu::capture::shared() {
+        Ok(c) => {
+            solidcraft_engine::capture::install(std::sync::Arc::new(move |scene, cam, w, h| {
+                c.rgba(scene, cam, w, h).map(|rgba| solidcraft_engine::capture::Picture { rgba, renderer: c.renderer() }).map_err(|e| e.to_string())
+            }));
+            true
+        }
+        Err(e @ solidcraft_gpu::GpuError::NoAdapter(_)) if std::env::var_os("SOLIDCRAFT_REQUIRE_GPU").is_none() => {
+            eprintln!("skipping: {e}");
+            false
+        }
+        Err(e) => panic!("{e}"),
+    }
+}
+
+/// A PNG's size and RGBA pixels.
+fn decode(png: &[u8]) -> (u32, u32, Vec<u8>) {
+    let img = image::load_from_memory_with_format(png, image::ImageFormat::Png).unwrap().to_rgba8();
+    (img.width(), img.height(), img.into_raw())
+}
+
+/// Pixels of two same-sized pictures that differ by more than a little in some channel.
+fn differing(a: &[u8], b: &[u8]) -> usize {
+    let ((wa, ha, a), (wb, hb, b)) = (decode(a), decode(b));
+    assert_eq!((wa, ha), (wb, hb), "pictures of different sizes");
+    a.as_chunks::<4>().0.iter().zip(b.as_chunks::<4>().0).filter(|(p, q)| p.iter().zip(q.iter()).any(|(x, y)| x.abs_diff(*y) > 16)).count()
+}
+
+/// The same picture: GPU output may differ by a few levels or a stray edge pixel between drivers.
+#[track_caller]
+fn assert_same(a: &[u8], b: &[u8], what: &str) {
+    let (n, total) = (differing(a, b), (SIZE.0 * SIZE.1) as usize);
+    assert!(n * 500 <= total, "{what}: {n} of {total} pixels differ");
+}
+
+/// Different pictures: more than stray pixels differ.
+#[track_caller]
+fn assert_differs(a: &[u8], b: &[u8], what: &str) {
+    let n = differing(a, b);
+    assert!(n >= 20, "{what}: only {n} pixels differ");
+}
+
+const SIZE: (u32, u32) = (160, 100);
 
 fn camera() -> Value {
     json!({"target": [20, 0, 0], "yaw": 0.6, "pitch": 0.25, "distance": 100})
@@ -88,32 +135,38 @@ impl Drop for Scratch {
 /// not the home view the option used to be ignored for.
 #[test]
 fn a_camera_frames_the_picture_as_the_mcp_screenshot_does() {
+    if !gpu() {
+        return;
+    }
     let dir = Scratch::new();
     let script = dir.script("part.json", &[]);
     let home = dir.snapshot(&script, "home.png", &[]);
     let json = camera().to_string();
     let shot = dir.snapshot(&script, "camera.png", &["--camera", &json]);
-    assert_ne!(shot, home, "--camera was ignored");
-    assert_eq!(shot, dir.mcp(&script, "mcp-camera.png", json!({"camera": camera()})));
+    assert_differs(&shot, &home, "--camera was ignored");
+    assert_same(&shot, &dir.mcp(&script, "mcp-camera.png", json!({"camera": camera()})), "the MCP screenshot");
     // A perspective camera too, and a different eye gives a different picture.
     let mut near = camera();
     near["fov"] = json!(0.6);
     let perspective = dir.snapshot(&script, "perspective.png", &["--camera", &near.to_string()]);
-    assert_ne!(perspective, shot);
-    assert_eq!(perspective, dir.mcp(&script, "mcp-perspective.png", json!({"camera": near})));
+    assert_differs(&perspective, &shot, "perspective");
+    assert_same(&perspective, &dir.mcp(&script, "mcp-perspective.png", json!({"camera": near})), "the MCP perspective screenshot");
 }
 
 /// `--view` also takes a view saved in the design, which is the camera it was saved with; a
 /// standard view still looks as it did.
 #[test]
 fn a_saved_view_is_its_camera_and_a_standard_view_is_unchanged() {
+    if !gpu() {
+        return;
+    }
     let dir = Scratch::new();
     let script = dir.script("part.json", &[]);
     let json = camera().to_string();
     let by_camera = dir.snapshot(&script, "camera.png", &["--camera", &json]);
     let saved = dir.snapshot(&script, "saved.png", &["--view", "Detail"]);
-    assert_eq!(saved, by_camera);
-    assert_eq!(saved, dir.mcp(&script, "mcp-saved.png", json!({"view": "Detail"})));
+    assert_same(&saved, &by_camera, "the saved view");
+    assert_same(&saved, &dir.mcp(&script, "mcp-saved.png", json!({"view": "Detail"})), "the MCP saved view");
     // A standard view frames the model from its direction, as before: the home camera turned.
     let top = dir.snapshot(&script, "top.png", &["--view", "top"]);
     let mut s = Session::default();
@@ -121,32 +174,38 @@ fn a_saved_view_is_its_camera_and_a_standard_view_is_unchanged() {
     let mut cam = solidcraft_engine::view::home_camera(&s);
     cam.set_view(solidcraft_engine::render::StandardView::Top);
     let scene = solidcraft_engine::view::scene(&s, &cam);
-    assert_eq!(top, solidcraft_engine::render::render_png(&scene, &cam, SIZE.0, SIZE.1).unwrap());
-    assert_eq!(top, dir.mcp(&script, "mcp-top.png", json!({"view": "top"})));
-    assert_ne!(top, saved);
+    assert_same(&top, &solidcraft_engine::capture::png(&scene, &cam, SIZE.0, SIZE.1).unwrap().bytes, "the home camera turned to the top");
+    assert_same(&top, &dir.mcp(&script, "mcp-top.png", json!({"view": "top"})), "the MCP top view");
+    assert_differs(&top, &saved, "top and the saved view");
     let iso = dir.snapshot(&script, "iso.png", &["--view", "iso"]);
-    assert_eq!(iso, dir.snapshot(&script, "home.png", &[]));
-    assert_ne!(iso, top);
+    assert_same(&iso, &dir.snapshot(&script, "home.png", &[]), "iso is home");
+    assert_differs(&iso, &top, "iso and top");
 }
 
 /// A script that applies a view itself (as an MCP `execute` of `view.apply` does) sets the camera
 /// of its snapshot; `--view` and `--camera` still decide when given.
 #[test]
 fn a_script_can_carry_its_camera() {
+    if !gpu() {
+        return;
+    }
     let dir = Scratch::new();
     let script = dir.script("carried.json", &[json!({"command": "view.apply", "params": {"camera": camera()}})]);
     let plain = dir.script("plain.json", &[]);
     let carried = dir.snapshot(&script, "carried.png", &[]);
-    assert_eq!(carried, dir.snapshot(&plain, "by-camera.png", &["--camera", &camera().to_string()]));
-    assert_ne!(carried, dir.snapshot(&plain, "home.png", &[]));
+    assert_same(&carried, &dir.snapshot(&plain, "by-camera.png", &["--camera", &camera().to_string()]), "the carried camera");
+    assert_differs(&carried, &dir.snapshot(&plain, "home.png", &[]), "the carried camera and home");
     let top = dir.snapshot(&script, "top.png", &["--view", "top"]);
-    assert_eq!(top, dir.snapshot(&plain, "plain-top.png", &["--view", "top"]));
+    assert_same(&top, &dir.snapshot(&plain, "plain-top.png", &["--view", "top"]), "--view decides");
 }
 
 /// The grid and the axes each go when asked, and a render without both from any side shows the
 /// model alone: an empty design is then the same blank picture from every camera.
 #[test]
 fn the_grid_and_the_axes_can_be_left_out() {
+    if !gpu() {
+        return;
+    }
     let dir = Scratch::new();
     let script = dir.script("part.json", &[]);
     let json = camera().to_string();
@@ -161,7 +220,7 @@ fn the_grid_and_the_axes_can_be_left_out() {
         let different = [&all, &no_grid, &no_axes, &bare];
         for (i, a) in different.iter().enumerate() {
             for b in &different[i + 1..] {
-                assert_ne!(a, b, "{view:?}: two pictures are the same");
+                assert_differs(a, b, &format!("{view:?}: two of the pictures"));
             }
         }
         // The same as the MCP's `grid` and `axes`.
@@ -173,15 +232,151 @@ fn the_grid_and_the_axes_can_be_left_out() {
             a.as_object_mut().unwrap().extend(extra.as_object().unwrap().clone());
             dir.mcp(&script, out, a)
         };
-        assert_eq!(no_grid, mcp(json!({"grid": false}), "mcp-no-grid.png"));
-        assert_eq!(no_axes, mcp(json!({"axes": false}), "mcp-no-axes.png"));
-        assert_eq!(bare, mcp(json!({"grid": false, "axes": false}), "mcp-bare.png"));
+        assert_same(&no_grid, &mcp(json!({"grid": false}), "mcp-no-grid.png"), "the MCP's grid: false");
+        assert_same(&no_axes, &mcp(json!({"axes": false}), "mcp-no-axes.png"), "the MCP's axes: false");
+        assert_same(&bare, &mcp(json!({"grid": false, "axes": false}), "mcp-bare.png"), "the MCP's bare picture");
     }
     let empty = dir.0.join("empty.json");
     std::fs::write(&empty, json!({"commands": []}).to_string()).unwrap();
     let blank = |view: &str, out: &str| dir.snapshot(&empty, out, &["--view", view, "--no-grid", "--no-axes"]);
-    assert_eq!(blank("top", "blank-top.png"), blank("front", "blank-front.png"));
-    assert_ne!(blank("top", "blank-top.png"), dir.snapshot(&empty, "top.png", &["--view", "top"]));
+    assert_same(&blank("top", "blank-top.png"), &blank("front", "blank-front.png"), "blank from every side");
+    assert_differs(&blank("top", "blank-top.png"), &dir.snapshot(&empty, "top.png", &["--view", "top"]), "blank and the grid");
+}
+
+/// A snapshot of a box shows its silhouette where the camera puts it: the pixels that differ
+/// from an empty design's picture (same camera, no grid or axes) span the box's corners projected
+/// to pixels, within the edge and silhouette lines' width.
+#[test]
+fn a_snapshot_shows_the_part_where_the_camera_puts_it() {
+    if !gpu() {
+        return;
+    }
+    let dir = Scratch::new();
+    let part = dir.0.join("box.json");
+    let empty = dir.0.join("empty.json");
+    let corner = [10.0, -20.0, -15.0];
+    let size = [60.0, 40.0, 30.0];
+    std::fs::write(
+        &part,
+        json!({"commands": [{"command": "solid.box", "params": {"length": size[0], "width": size[1], "height": size[2], "corner": corner}}]})
+            .to_string(),
+    )
+    .unwrap();
+    std::fs::write(&empty, json!({"commands": []}).to_string()).unwrap();
+    for cam in [
+        camera(),
+        json!({"target": [40, 0, 0], "yaw": 0.0, "pitch": 0.0, "distance": 160}),
+        json!({"target": [40, 0, 0], "yaw": -0.4, "pitch": 0.5, "distance": 150, "fov": 0.6}),
+    ] {
+        let args = ["--camera", &cam.to_string(), "--no-grid", "--no-axes"];
+        let (_, _, with) = decode(&dir.snapshot(&part, "part.png", &args));
+        let (_, _, without) = decode(&dir.snapshot(&empty, "empty.png", &args));
+        // The part's pixels: where the picture differs from the empty one.
+        let (mut lo, mut hi) = ([u32::MAX; 2], [0u32; 2]);
+        for (i, (p, q)) in with.as_chunks::<4>().0.iter().zip(without.as_chunks::<4>().0).enumerate() {
+            if p.iter().zip(q.iter()).any(|(x, y)| x.abs_diff(*y) > 24) {
+                let (x, y) = (i as u32 % SIZE.0, i as u32 / SIZE.0);
+                lo = [lo[0].min(x), lo[1].min(y)];
+                hi = [hi[0].max(x), hi[1].max(y)];
+            }
+        }
+        assert!(lo[0] <= hi[0], "{cam}: the part is not in the picture");
+        // Where the camera puts the corners.
+        let mut s = solidcraft_engine::Session::default();
+        s.execute("view.apply", &json!({"camera": cam})).unwrap();
+        let c = s.camera.unwrap();
+        let vp = c.view_proj(f64::from(SIZE.0) / f64::from(SIZE.1), 1000.0);
+        let (mut elo, mut ehi) = ([f64::MAX; 2], [f64::MIN; 2]);
+        for k in 0..8 {
+            let p = solidcraft_engine::geom::Vec3::new(
+                corner[0] + size[0] * f64::from(k & 1),
+                corner[1] + size[1] * f64::from((k >> 1) & 1),
+                corner[2] + size[2] * f64::from((k >> 2) & 1),
+            );
+            let q = vp.apply(p);
+            let (x, y) = ((q[0] / q[3] + 1.0) * 0.5 * f64::from(SIZE.0), (1.0 - q[1] / q[3]) * 0.5 * f64::from(SIZE.1));
+            elo = [elo[0].min(x), elo[1].min(y)];
+            ehi = [ehi[0].max(x), ehi[1].max(y)];
+        }
+        let near = |got: u32, want: f64| (f64::from(got) - want).abs() <= 2.5;
+        assert!(
+            near(lo[0], elo[0]) && near(lo[1], elo[1]) && near(hi[0] + 1, ehi[0]) && near(hi[1] + 1, ehi[1]),
+            "{cam}: the part spans pixels {lo:?}..={hi:?}, its corners project to {elo:?}..{ehi:?}"
+        );
+    }
+}
+
+/// `snapshot` under a `SOLIDCRAFT_GPU` policy: its reply and stderr.
+fn snapshot_under(dir: &Scratch, script: &Path, out: &str, policy: &str) -> Output {
+    Command::new(env!("CARGO_BIN_EXE_solidcraft-cli"))
+        .env("SOLIDCRAFT_GPU", policy)
+        .arg("snapshot")
+        .arg(script)
+        .arg("--out")
+        .arg(dir.0.join(out))
+        .args(["--width", &SIZE.0.to_string(), "--height", &SIZE.1.to_string(), "--view", "top"])
+        .output()
+        .unwrap()
+}
+
+/// The last tier: `SOLIDCRAFT_GPU=cpu` draws with the CPU rasterizer whatever adapters there are,
+/// says so (`renderer: cpu` and a warning that overlays are not drawn), and the picture is the
+/// rasterizer's own.
+#[test]
+fn a_forced_cpu_snapshot_is_the_cpu_rasterizers_and_says_so() {
+    let dir = Scratch::new();
+    let script = dir.script("part.json", &[]);
+    let output = snapshot_under(&dir, &script, "cpu.png", "cpu");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(output.status.success(), "{stderr}");
+    let reply: Value = serde_json::from_slice(&output.stdout).unwrap();
+    assert_eq!(reply["renderer"], "cpu", "{reply}");
+    assert!(reply["warning"].as_str().is_some_and(|w| w.contains("not drawn")), "{reply}");
+    assert!(stderr.contains("CPU rasterizer"), "{stderr}");
+    let mut s = Session::default();
+    s.run_script(&serde_json::from_slice(&std::fs::read(&script).unwrap()).unwrap()).unwrap();
+    let mut cam = solidcraft_engine::view::home_camera(&s);
+    cam.set_view(solidcraft_engine::render::StandardView::Top);
+    let scene = solidcraft_engine::view::scene(&s, &cam);
+    let cpu = solidcraft_engine::render::render_png(&scene, &cam, SIZE.0 as usize, SIZE.1 as usize).unwrap();
+    assert_eq!(std::fs::read(dir.0.join("cpu.png")).unwrap(), cpu);
+}
+
+/// `hardware` (and `software`) never fall to the CPU rasterizer: without such an adapter the
+/// snapshot fails, naming the policy, and writes nothing; with one it says it was drawn on the GPU.
+/// `auto` lands where `solidcraft-cli gpu` says it does.
+#[test]
+fn a_strict_policy_never_falls_to_the_cpu() {
+    let dir = Scratch::new();
+    let script = dir.script("part.json", &[]);
+    let survey = |policy: &str| {
+        let o = Command::new(env!("CARGO_BIN_EXE_solidcraft-cli")).args(["gpu", "--policy", policy]).output().unwrap();
+        (o.status.success(), serde_json::from_slice::<Value>(&o.stdout).unwrap_or(Value::Null))
+    };
+    for policy in ["hardware", "software"] {
+        let (found, report) = survey(policy);
+        let output = snapshot_under(&dir, &script, &format!("{policy}.png"), policy);
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        if found {
+            assert!(output.status.success(), "{policy}: {stderr}");
+            let reply: Value = serde_json::from_slice(&output.stdout).unwrap();
+            assert_eq!(reply["renderer"], report["renderer"], "{policy}: {reply}");
+            assert_ne!(reply["renderer"], "cpu");
+        } else {
+            assert_eq!(report["lands_on"], Value::Null, "{policy}: {report}");
+            assert_eq!(output.status.code(), Some(1), "{policy}: {stderr}");
+            assert!(stderr.contains(&format!("`{policy}` policy")) && stderr.contains("solidcraft-cli gpu"), "{policy}: {stderr}");
+            assert!(!dir.0.join(format!("{policy}.png")).exists());
+        }
+    }
+    let (found, report) = survey("auto");
+    assert!(found, "auto always lands somewhere: {report}");
+    let output = snapshot_under(&dir, &script, "auto.png", "auto");
+    assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr));
+    let reply: Value = serde_json::from_slice(&output.stdout).unwrap();
+    assert_eq!(reply["renderer"], report["renderer"], "{reply} vs {report}");
+    let (_, cpu) = survey("cpu");
+    assert_eq!((cpu["lands_on"].clone(), cpu["renderer"].clone()), (json!("cpu"), json!("cpu")), "{cpu}");
 }
 
 #[test]

apps/solidcraft-web/src/main.rs

@@ -491,6 +491,8 @@ mod web {
                             install_app: Some(crate::install::service(&cc.egui_ctx)),
                             ..Default::default()
                         };
+                        // Thumbnails of saves and start-page cards.
+                        solidcraft_ui_egui::gpu::install_cpu_picture_renderer();
                         let mut app = SolveApp::new(Session::default(), services);
                         if let Some(p) = cc.storage.and_then(|s| solidcraft_ui_egui::prefs::stored(|k| s.get_string(k))) {
                             app.load_prefs(&p);

apps/solidcraft/src/main.rs

@@ -567,6 +567,7 @@ fn main() -> eframe::Result {
                 eprintln!("SolidCraft graphics: {:?}, MSAA {}x (requested {}x)", rs.adapter.get_info().backend, rs.msaa_samples, samples);
                 solidcraft_engine::crash::phase("viewport pipelines (shader compile)");
                 app.set_wgpu(rs, DEPTH_BITS, STENCIL_BITS, rs.msaa_samples);
+                solidcraft_ui_egui::gpu::install_picture_renderer(rs);
                 // The graphics driver is loaded now; it may have put its own exception filter
                 // in front of ours.
                 #[cfg(target_os = "windows")]