fix(renderer): M97 后端判据 —— 静默降级改具名错误,取证通道拒绝降级出图

M97 的入口是一份 macOS M1 真机报告:探测认出了 Apple M1(adapters=1 /
hardware=true),日志却写着 `renderer = auto (wgpu -> tiny-skia)`,看起来
像在跑 CPU。读源码发现那行是**常量**:`probe.rs` 按 `ICED_BACKEND` 未设就把
`"auto (wgpu -> tiny-skia)"` 打出来,与实际后端无关。真正的失败被 iced 吞掉:
`iced_renderer-0.14.0/src/fallback.rs` 的 `Compositor::with_backend` 把 wgpu 的
错误装进 `errors` 向量,tiny-skia 一成功就整体丢弃。

## 判据改为单项,不再交给 iced 回退

`ICED_BACKEND` 现在**永远是单项**(`wgpu` / `tiny-skia`):能跑起来就必定是它;
起不来就必然是 `iced::Error::GraphicsCreationFailed` 里的具名错误。判据是纯函数
`renderer::decide(request, probe, gpu_compiled)`,落在 `renderer/decision.rs`,
表驱动测试逐行钉死 1~6 行 + 「除强制 CPU / 未编 wgpu 外必须留兜底」的守门。
判据表(条件 / 选哪个 / 日志该打什么 / 谁能验证)在 `renderer/mod.rs` 顶部。

## 安全网改成换进程

第一版是「打印错误 → 在本进程再 run() 一次」,Windows 实测直接 panic:
`Create event loop: RecreationAttempt`(winit 一个进程只能建一次事件循环)。
改成 `respawn`:子进程只换 `ICED_BACKEND` + `ULL_GPU_FALLBACK`,父进程透传它的
退出码。子进程看到 `ULL_GPU_FALLBACK` 必须跳过探测,否则会无限递归重开。

## 取证通道不许自己降级

带 `--screenshot`(含 `--screen=gallery`)时 wgpu 起不来就**不出图**、退出码 1,
因为换了后端出的图会撒谎;交互启动才允许降级。每张图的日志现在打**实际**后端
(`[shot] … renderer=wgpu`),以前打的是请求值 `auto`——同一个病(在需要结果的
地方打请求)在仓库里出现了两次,这是第二次。

## 可观测性

- `log` 桥(`renderer/log_bridge.rs`)把 `iced_wgpu` 的
  `Selected: AdapterInfo{…}` 接到 stderr:这是本仓库第一次能自证「真在用 GPU」。
  按 target 分级(`iced_wgpu*` Info、`wgpu*` Warn),否则 Vulkan loader 会刷 90 行噪声。
- `renderer/preflight.rs`(默认关,`ULL_PREFLIGHT=1`):开窗前拿 wgpu 的具名错误。
  实测 Windows RX 6600 XT 上 took=717ms,所以不进默认路径。
- `app/backend.rs` 的档位判据跟着改成读单项;**真降级到 CPU 的那一次面板 α 现在会
  正确强制 1.0**(以前静默降级后仍按 GPU 档判)。

Windows 实测:auto → wgpu + `Selected: AdapterInfo{…backend: Vulkan}` 出图;
`--renderer=cpu` 逐字不变;`WGPU_BACKEND=metal` 造失败 → 具名错误 → 交互路径降级
不崩(首帧 531ms)/ 取证路径拒绝出图 exit 1。macOS Metal 路径需真机复核,
命令与期望日志行写在 `renderer/mod.rs` 的「真机验收」一节。
This commit is contained in:
AskaEth committed 2026-11-03 00:26:55 +08:00
1 parent 45cd44f756
commit 31cdfd5bbd
13 files changed
+1260 -157

No files matched your search

+89 -31
View File
@@ -7,38 +7,50 @@
//! 请求是 `Auto`,实际是 tiny-skia(CPU)——如果面板 α / 玻璃的降级判据只看请求值,
//! D36 明写的「CPU 档面板 α 强制 1.0」**恰好在它最该生效的场景失效**(复审 r1 P2-2)。
//!
//! 所以判据统一走 [`effective_backend`]:它把 `ICED_BACKEND` 的候选列表翻译回 [`Backend`]。
//! 所以判据统一走 [`effective_backend`]:它把 `ICED_BACKEND` 翻译回 [`Backend`]。
//! 这里是**唯一**的翻译点,别在别处再读一遍环境变量。
//!
//! ## M97 之后这条链是准的(以前不是)
//!
//! 以前 `ICED_BACKEND` 可能是**候选列表**(`wgpu,tiny-skia`),运行期 wgpu 静默回退到
//! tiny-skia 时这个变量还停在 wgpu ⇒ 本模块按 **GPU 档**判 ⇒ **半透明在 CPU 渲染器上照开**。
//! 也就是说「静默降级」不只让日志说谎,还让 D36 的降级判据一起说谎。
//!
//! 现在 `ICED_BACKEND` **永远是单项**([`crate::renderer::Kind`]),而且 `app::boot` 的重试
//! 在降级重开前会把它改成 `tiny-skia`,于是:**真降级到 CPU 的那一次,面板 α 会正确地强制 1.0**。
//!
//! ## 已知边界(诚实登记)
//!
//! `ICED_BACKEND="wgpu,tiny-skia"` 表示「优先 wgpu,拿不到适配器再回退 tiny-skia」。运行期到底
//! 选了谁只有渲染器自己知道,本 crate 拿不到(iced 0.14 没有公开的「当前后端」查询)。
//! 这种机器按 **GPU 档**判(面板 α 生效);如果 wgpu 在运行期回退到 tiny-skia,面板 α 会
//! 在 CPU 渲染器上生效——成本比 D27 的顾虑略高,但不会画错。要彻底收口得让 iced 暴露实际后端。
//! `iced` 0.14 没有公开的「当前后端」查询,所以本模块读的仍是**我们请求的那一项**。
//! 单项 + 重试([`crate::renderer`] 判据表第 8 行)把「请求 ≠ 实际」的窗口压到只剩一种:
//! 重试那次自己也失败——那时候进程会带着具名错误退出,不会带着错的档位继续画。
use crate::renderer::Kind;
use crate::Backend;
/// `ICED_BACKEND` 的候选列表 → 实际档位(纯函数,好测)。
/// `ICED_BACKEND` 的取值 → 后端(纯函数,好测)。
///
/// | `ICED_BACKEND` | 含义(`probe::backend_env` 的产物) | 结论 |
/// 逗号列表按**首项**解释:兼容 M97 之前写下的值(以及外部手设的实验值),
/// 但本 crate 不再产出那种值(守门测试见 `probe::tests::apply_writes_exactly_one_backend`)。
#[must_use]
pub(super) fn parse_kind(env: &str) -> Option<Kind> {
match env.trim().split(',').next()?.trim() {
"tiny-skia" => Some(Kind::TinySkia),
"wgpu" => Some(Kind::Wgpu),
_ => None,
}
}
/// `ICED_BACKEND` → 实际档位(纯函数,好测)。
///
/// | `ICED_BACKEND` | 含义(`probe::apply` 的产物) | 结论 |
/// |---|---|---|
/// | `tiny-skia` | 只有 CPU 候选(`--software-renderer` / 未编 wgpu / Auto 无线程硬件) | [`Backend::Cpu`] |
/// | `wgpu,tiny-skia` | 点名要 GPU(保留回退) | [`Backend::Gpu`] |
/// | `tiny-skia,wgpu` | Auto + 有 wgpu 无硬件(CPU 起步、wgpu 兜底) | [`Backend::Cpu`] |
/// | 未设 | Auto + 有硬件(交给 iced 默认顺序) | 请求值(`Auto`) |
/// | `tiny-skia` | 只有 CPU(`--renderer=cpu` / 未编 wgpu / 探测无硬件 / wgpu 失败后重开) | [`Backend::Cpu`] |
/// | `wgpu` | 判据表第 3、6 行:起步就是 GPU(起不来会打印具名错误并重开成 `tiny-skia`) | [`Backend::Gpu`] |
/// | 未设 / 别的值 | 不是本 crate 写的(外部手设 / M97 之前的旧进程) | 请求值(不猜) |
#[must_use]
pub(super) fn backend_from_env(request: Backend, env: Option<&str>) -> Backend {
let Some(list) = env.map(str::trim).filter(|value| !value.is_empty()) else {
return request;
};
// 候选列表的第一项就是起步渲染器:`tiny-skia` 起步 = CPU 档(D36 的降级对象)。
let first = list.split(',').next().unwrap_or(list).trim();
match first {
"tiny-skia" => Backend::Cpu,
"wgpu" => Backend::Gpu,
_ => request,
}
env.and_then(parse_kind).map_or(request, Kind::tier)
}
/// 本进程实际生效的后端(判据 = `probe::apply` 写下的 `ICED_BACKEND`)。
@@ -47,25 +59,49 @@ pub(super) fn effective_backend(request: Backend) -> Backend {
backend_from_env(request, std::env::var("ICED_BACKEND").ok().as_deref())
}
/// 本进程实际生效的**后端名**(`None` = 变量没写 / 不认识)。
///
/// 与 [`effective_backend`] 的区别:那个给「档位」,这个给「名字」,用于**取证日志**
/// (`[shot] … renderer=wgpu`)。两张图分辨不出 GPU/CPU 的时候,靠的就是这一行。
#[must_use]
pub(super) fn effective_kind() -> Option<Kind> {
std::env::var("ICED_BACKEND")
.ok()
.as_deref()
.and_then(parse_kind)
}
#[cfg(test)]
mod tests {
use super::backend_from_env;
use crate::Backend;
use unlucky_presenter::prefs::{PANEL_ALPHA_MIN, WINDOW_ALPHA_MIN};
/// 抓得住:`probe::backend_env` 的每一种产物都被翻译成正确的档位(含最容易踩的
/// 「Auto + 没独显」= `tiny-skia,wgpu` → CPU)。
/// 抓不住:运行期 wgpu 真回退到 tiny-skia 的情况(iced 没暴露实时候选,见模块文档)。
/// 抓得住:`probe::apply` 现在产出的**每一种单项值**都被翻译成正确的档位,
/// 且 M97 之前写下的逗号列表仍按首项解释(向后兼容)。
/// 抓不住:运行期重试降级那一刻的时序(那由 `app::boot` 的重试保证,见 `renderer` 判据表第 8 行)。
#[test]
fn every_iced_backend_list_maps_to_a_tier() {
fn every_iced_backend_value_maps_to_a_tier() {
// 本 crate 现在只产单项(`probe::tests::apply_writes_exactly_one_backend` 守这一条)。
assert_eq!(
backend_from_env(Backend::Auto, Some("tiny-skia")),
Backend::Cpu
Backend::Cpu,
"M97 判据表第 5 行:探测无硬件 ⇒ CPU 档"
);
assert_eq!(
backend_from_env(Backend::Auto, Some("tiny-skia,wgpu")),
backend_from_env(Backend::Auto, Some("wgpu")),
Backend::Gpu,
"M97 判据表第 6 行:有硬件 ⇒ GPU 档"
);
assert_eq!(
backend_from_env(Backend::Cpu, Some("tiny-skia")),
Backend::Cpu,
"Auto + 无硬件:CPU 起步 ⇒ CPU 档"
"强制 CPU 也是 CPU 档"
);
// 兼容 M97 之前的逗号列表(外部手设 / 旧进程留下):按首项解释。
assert_eq!(
backend_from_env(Backend::Auto, Some("tiny-skia,wgpu")),
Backend::Cpu
);
assert_eq!(
backend_from_env(Backend::Auto, Some("wgpu,tiny-skia")),
@@ -75,7 +111,7 @@ mod tests {
backend_from_env(Backend::Gpu, Some("wgpu,tiny-skia")),
Backend::Gpu
);
// 未设 / 空白:保持请求值(Auto + 有硬件 ⇒ 交给 iced,按 GPU 档判)。
// 未设 / 空白:保持请求值(不是本 crate 写的,不猜)。
assert_eq!(backend_from_env(Backend::Auto, None), Backend::Auto);
assert_eq!(backend_from_env(Backend::Auto, Some(" ")), Backend::Auto);
// 不认识的取值不猜:保留请求值。
@@ -94,7 +130,7 @@ mod tests {
fn auto_with_a_software_renderer_forces_the_panel_opaque() {
use crate::pages::appearance::alpha::{effective_glass, effective_panel_alpha};
let backend = backend_from_env(Backend::Auto, Some("tiny-skia,wgpu"));
let backend = backend_from_env(Backend::Auto, Some("tiny-skia"));
assert_eq!(backend, Backend::Cpu);
assert_eq!(
effective_panel_alpha(backend, 0.55),
@@ -106,8 +142,30 @@ mod tests {
assert!(crate::platform::effective_window_alpha(backend, 0.8).is_some());
// 反方向:GPU 档不做这个降级(否则「强制」就没意义了)。
let gpu = backend_from_env(Backend::Auto, Some("wgpu,tiny-skia"));
let gpu = backend_from_env(Backend::Auto, Some("wgpu"));
assert_eq!(effective_panel_alpha(gpu, 0.55), 0.55);
assert!((PANEL_ALPHA_MIN - 0.4).abs() < 1e-9 && (WINDOW_ALPHA_MIN - 0.08).abs() < 1e-9);
}
/// **M97 的新守门**:wgpu 失败重开成 `tiny-skia` 之后,档位必须跟着变成 CPU 档。
///
/// 这是修之前做不到的一条:那时变量停在 `wgpu,tiny-skia`,静默回退到 tiny-skia 之后
/// 判据仍然读 `Gpu` ⇒ 半透明在 CPU 渲染器上照开。现在 `app::boot` 重开前会改写这个值,
/// 这条测试钉的是「改写成 tiny-skia 之后判据确实翻转」。
#[test]
fn retry_fallback_flips_the_tier_to_cpu() {
use crate::pages::appearance::alpha::effective_panel_alpha;
let before = backend_from_env(Backend::Auto, Some("wgpu"));
assert_eq!(before, Backend::Gpu);
assert_eq!(effective_panel_alpha(before, 0.55), 0.55);
let after = backend_from_env(Backend::Auto, Some("tiny-skia"));
assert_eq!(after, Backend::Cpu);
assert_eq!(
effective_panel_alpha(after, 0.55),
1.0,
"D36:真降级到 CPU 后,面板 α 必须强制 1.0"
);
}
}
+123 -4
View File
@@ -1,4 +1,13 @@
//! 启动:后端探测 → 字体求值 → `iced::application(..).run()`。
//!
//! ## M97:`run()` 为什么要重试
//!
//! `ICED_BACKEND` 现在永远是**单项**(见 [`crate::renderer`] 的判据表)。单项的代价是
//! iced 不再自己做回退,于是「wgpu 起不来」会变成 `iced::Error::GraphicsCreationFailed`
//! ——**这正是我们要的**:那里面装着 wgpu 的具名错误(哪个 backend、卡在 adapter 还是 device)。
//! 拿到它以后打印、然后换 `tiny-skia` 重开一次,安全网照样在,但降级不再是静默的。
//!
//! 重试只在起步项真的失败时发生,而且**只重试一次**;字体栈不重算(那是启动最贵的一段)。
use std::time::Instant;
@@ -9,6 +18,7 @@ use unlucky_design::color::SchemeFlavor;
use crate::cli::Options;
use crate::fonts;
use crate::probe;
use crate::renderer::{self, Decision, Kind};
use crate::theme::Families;
use super::message::Message;
@@ -19,7 +29,7 @@ use super::{MIN_SIZE, WINDOW_SIZE};
pub(crate) fn run(options: Options) -> iced::Result {
let _ = STARTED.set(Instant::now());
boot_probe(&options);
let decision = boot_probe(&options);
let font_started = Instant::now();
let resolved = fonts::resolve();
@@ -41,6 +51,92 @@ pub(crate) fn run(options: Options) -> iced::Result {
eprintln!("[shot] 未指定主题,按 Light 出图(D30 可复现;CI 冒烟依赖这条默认值)");
}
let flavor = options.capture_flavor().unwrap_or(SchemeFlavor::Light);
// 起步后端起不来时**换一个进程**重开(winit 不允许在本进程重建事件循环,见
// `renderer::run_once` 的文档)。具名原因在换进程之前就打到同一个 stderr 上了。
match launch(&options, families, flavor, decision.primary) {
Err(iced::Error::GraphicsCreationFailed(error)) => {
renderer::report_failure(decision.primary, &error);
match decision.fallback {
// 交互启动:安全网优先,降级重开,用户还能用。
Some(fallback) if options.screenshot.is_none() => {
respawn(decision.primary, fallback)
}
// 取证启动(`--screenshot`):**拒绝降级出图**。图是要拿去下结论的,
// 换了后端出的图会撒谎——以前就是这么把 CPU 截图当 GPU 结论用的。
Some(_) => {
eprintln!(
"[gpu] 拒绝降级出图:本次是取证启动(--screenshot {}),换后端出的图会撒谎。",
options
.screenshot
.as_ref()
.map_or_else(String::new, |path| path.display().to_string())
);
eprintln!(
"[gpu] 想用 CPU 出图请显式加 --renderer=cpu / --software-renderer(CI 就是这么跑的)。"
);
Err(iced::Error::GraphicsCreationFailed(error))
}
None => Err(iced::Error::GraphicsCreationFailed(error)),
}
}
other => other,
}
}
/// 安全网:起一个**新进程**用 `fallback` 后端重开,然后带着它的退出码退出。
///
/// 为什么必须是新进程:winit 一个进程只能建一次事件循环
/// (`iced_winit-0.14.1/src/lib.rs:81` → `Create event loop: RecreationAttempt`)。
///
/// 只在**交互启动**时走到这里;取证启动(`--screenshot`)宁可红着退出也不换后端出图
/// (判据表第 8 行 vs 第 9 行——**这两条路的策略不同,别合成一条**)。
///
/// ## `ULL_GPU_FALLBACK` 是防自杀循环的唯一闸门
///
/// 子进程看到 [`renderer::FALLBACK_ENV`] **必须跳过探测**(`boot_probe` 的第一段),换成
/// `tiny-skia` 直接跑;否则子进程会算出和父进程一样的结论(auto + 有硬件 → wgpu)、再失败、
/// 再 respawn —— **无限递归重开**。这种循环极难复现也极难诊断(每次重开都像是「刚刚启动」),
/// 所以闸门放在探测入口的第一个分支,不放在 respawn 那一侧。
fn respawn(failed: Kind, fallback: Kind) -> ! {
let exe = std::env::current_exe().unwrap_or_else(|err| {
eprintln!("[gpu] 降级重开失败:拿不到自身路径({err})");
std::process::exit(2);
});
eprintln!(
"[gpu] 降级 → {}({} 已失败,原因见上两行;换一个进程重开:winit 不允许同进程建两次事件循环)。\
下一次的日志从 `[probe] 本次是降级重开` 开始。",
fallback.name(),
failed.name()
);
let status = std::process::Command::new(exe)
.args(std::env::args().skip(1))
.env(renderer::FALLBACK_ENV, fallback.env_value())
.env("ICED_BACKEND", fallback.env_value())
.status();
// 退出码**透传**子进程的:上层脚本/CI 靠它判断这次到底是成功还是失败。
// 子进程被信号杀掉时 `code()` 是 `None`(Unix 才有),那种情况退回 2,别假装成功。
let code = match status {
Ok(status) => status.code().unwrap_or(2),
Err(err) => {
eprintln!("[gpu] 降级重开失败:{err}");
2
}
};
std::process::exit(code)
}
/// 按一次后端启动 iced。`backend` 决定这次写进 `ICED_BACKEND` 的唯一一项。
fn launch(
options: &Options,
families: Families,
flavor: SchemeFlavor,
backend: Kind,
) -> iced::Result {
std::env::set_var("ICED_BACKEND", backend.env_value());
let boot_options = options.clone();
let application = iced::application(
@@ -80,8 +176,26 @@ pub(crate) fn run(options: Options) -> iced::Result {
}
}
/// 渲染后端探测 + 写 `ICED_BACKEND`。
fn boot_probe(options: &Options) {
/// 渲染后端探测 + 写 `ICED_BACKEND`,返回判据产物(供 `run` 决定要不要换进程重开)。
fn boot_probe(options: &Options) -> Decision {
// 本进程是「上一步失败后重开」的那一次:别再探一次(会得到同一个结论,然后无限重开)。
if let Some(kind) = renderer::forced_fallback() {
std::env::set_var("ICED_BACKEND", kind.env_value());
let decision = Decision {
primary: kind,
fallback: None,
reason: "fallback-after-failure",
};
eprintln!(
"[probe] 本次是降级重开({}={}):跳过探测 -> ICED_BACKEND={}",
renderer::FALLBACK_ENV,
kind.env_value(),
kind.env_value()
);
eprintln!("[probe] {}", decision.describe());
return decision;
}
let probe_started = Instant::now();
// 只有 `auto` 需要探测:`cpu` 与 `gpu` 的决策与「有没有硬件 GPU」无关,
// 而枚举 13 个适配器在本机要 0.65~1.2 s(实测),纯属白花。
@@ -92,7 +206,11 @@ fn boot_probe(options: &Options) {
probe::Probe::default()
};
let probe_ms = probe_started.elapsed().as_secs_f64() * 1000.0;
probe::apply(options.backend, &probe);
// `ULL_PREFLIGHT=1` 时先自己验一遍 wgpu(判据表第 7 行);默认不跑,见 preflight 模块文档。
let preflight = renderer::preflight::run_if_requested();
let decision = probe::apply_with_preflight(options.backend, &probe, preflight.as_ref());
if cfg!(feature = "gpu") {
if needs_probe {
eprintln!("[probe] 探测耗时 {probe_ms:.0} ms(wgpu 实例 + 全后端适配器枚举)");
@@ -103,6 +221,7 @@ fn boot_probe(options: &Options) {
);
}
}
decision
}
/// 默认字体(正文档解析出来的族)。
+3 -1
View File
@@ -36,6 +36,7 @@ use unlucky_presenter::router::Route;
use unlucky_presenter::theme::CONFIG_POLL_TICKS;
use crate::pages;
use crate::renderer::Kind;
use super::message::{route_of, Message};
use super::state::{App, IDLE_TICK, TICK, TICK_MS, WATCH_WINDOW};
@@ -326,11 +327,12 @@ impl App {
match crate::shot::save(screenshot, &path) {
Ok(summary) => {
eprintln!("{}", summary.describe());
// M97:打**实际**后端名(`wgpu`/`tiny-skia`),不是请求值——`renderer=auto` 曾经出现在每张验收图的日志里。
eprintln!(
"[shot] screen={} theme={} renderer={} route={:?}",
self.options.screen.name(),
crate::shot::flavor_slug(&self.ui),
self.options.backend.note(),
super::backend::effective_kind().map_or("?", Kind::name),
self.state.route()
);
}