WallpaperMachine的shader翻译术：naga如何将Wallpaper Engine着色器转成Metal语言

WallpaperMachine 是一款免费开源的 Mac 壁纸应用，它把 Wallpaper Engine 的 scene、video、web 壁纸带到 macOS 桌面。其中 scene 壁纸的灵魂就是一堆由作者手写的着色器（shader），而 macOS 只听得懂 Metal 语言——WallpaperMachine 用 naga 这套 shader 翻译流水线，把两种语言之间的一切差异悄悄抹平。本文带你完整看懂这套"翻译术"的工作原理。

为什么需要"翻译"？

Wallpaper Engine 的 scene 壁纸里，着色器作者写的是自己的一套方言：

• 语法接近 GLSL，但混着 HLSL 风格的调用（比如mul、tex2D）；
• 纹理资源固定叫g_Texture0、g_Texture1……；
• 还有#require LightingV1这类专属指令，要求运行时补上光照函数。

而 macOS（尤其是 Apple silicon）渲染管线的着色器语言是Metal Shading Language（MSL），资源通过[[texture(N)]]、[[buffer(N)]]这样的属性注解绑定，两者几乎没有直接互换的可能。

所以 WallpaperMachine 在渲染器里放了一个专门的 shader 层——wm-shadercrate，它的全部工作可以概括为一句话：Wallpaper Engine 着色器文本进，Metal Shading Language 和反射信息出。

翻译流水线：四步走

整条流水线定义在 Renderer/Shader/src/pipeline/mod.rs，一个请求进去，一个编译好的程序出来，共四步：

1. 预处理（prepare）：展开#include、#define等宏，解析[COMBO]、[TEXTURE]等元数据注释，生成最终阶段的着色器文本；
2. 合法化（legalize）：把两个阶段（vertex / fragment）放在一起统一处理，重写采样调用、规划 uniform 块、给纹理和 varying 接口分配位置，输出一版"干净的标准 GLSL"；
3. 编译（compile）：把合法化后的 GLSL 交给naga——这是翻译术的核心，下面细说；
4. 反射（reflect）：描述翻译结果里每个纹理槽、uniform 块成员、顶点输入分别落在 Metal 的哪个 slot，让宿主引擎按图索骥地绑定资源。

任何一步失败都会立刻停下并返回带行号、带上下文的诊断信息，而不是给你一个崩溃。

主角登场：naga 做了什么

naga 是 Rust 图形生态（wgpu）里的 shader 翻译库，支持多种着色器语言的前端与后端。WallpaperMachine 把naga 29.0.3的补丁版直接放进仓库（见 ThirdParty/naga/），只启用glsl-in（GLSL 前端）和msl-out（Metal 后端）两个 feature，依赖声明在 Renderer/Shader/Cargo.toml。

在 Renderer/Shader/src/backend/mod.rs 中，naga 承担了三个角色：

• GLSL 前端：把合法化后的文本解析成 naga 的中间表示（IR）；
• 校验器：用全量校验标志检查 IR 是否合法（入口点是否存在、类型是否匹配等）；
• Metal 写器：针对指定入口点写出 MSL 文本，目标是 Metal 2.0（见 MSL_VERSION 定义）。

写之前还有一个关键动作：Metal slot 分配——按资源在同一命名空间内的声明顺序，给每个 buffer、texture、sampler 排上从 0 开始的编号，并先于校验执行，这样"Metal 目标吃不下这个资源"能被明确报出来。

用一张图感受一下这条链路的产出——1.6 版之后，所有场景均由 Native Metal 绘制：

一次真实的翻译长什么样

把上面的步骤串起来，作者写的方言着色器会经历这样的变化（简化示意）：

// 作者的着色器（Wallpaper Engine 方言） float4 frag = tex2D(g_Texture0, uv); gl_FragColor = float4(frag.rgb, 1.0);

经过宏展开、合法化、naga 翻译后，最终变成大致这样的 MSL：

// 翻译产物（Metal 语言） fragment color main0(uint vid [[vertex_id]], texture2d<float> t0 [[texture(1)]], sampler s0 [[sampler(1)]]) { float4 frag = t0.sample(s0, uv); return color(frag.rgb, 1.0); }

tex2D拆成了texture2d+sampler两个独立资源并排好 slot，gl_FragColor换成了函数返回值，uniform 则统一打包成一个 constant buffer。这些规则的细节（浮点%如何映射到fmod、vec2参与加减如何补零、整数与浮点比较按谁算……）都记录在 Renderer/Shader/NOTES.md 里，堪称一份"翻译规则全档案"。

如何保证翻译不出错

翻译最怕的不是报错，而是"悄悄画错"。WallpaperMachine 为此做了大量验证：

• 语料全量扫描：随仓库附带的 159 个内置 shader 程序和数百个 Steam Workshop shader，全部走完整流水线编译到 Metal 并用系统 Metal 编译器复检（通过率数字记录在 NOTES.md 的 Step 5 部分）；
• GPU 数值比对：把fmod、矩阵求逆、截断等易错运算写在小 kernel 里，Metal 跑出来的值和 HLSL 参考实现逐一比对（tests/gpu_probe.rs，可选开启）；
• 缓存键与编译器身份：每个编译产物带 SHA-256 缓存键和类似2:naga-29.0.3-msl2.0-untransformed的身份标识，naga 版本或规则一变，缓存自动失效重建，杜绝"旧译文"残留；
• 恶意输入测试：几十万组篡改、截断、token 汤输入，验证任何输入都不会让编译器崩溃或栈溢出。

对普通用户来说，这些意味着：同一个 scene 壁纸在 Mac 上呈现的效果，和 Wallpaper Engine 原版高度一致；编译结果会被缓存（可手动清理，见 docs/features/scene-rendering.md 的 shader cache 小节），第二次加载同一壁纸不再重复翻译。

想深入源码？从这里开始

小结

🔹 Wallpaper Engine 的着色器不能直接跑在 macOS 上，WallpaperMachine 用wm-shader层把它翻译出来； 🔹 前段是自主实现的预处理与合法化，负责抹平方言差异； 🔹 后段交给naga：GLSL 前端 → IR 校验 → Metal 写器，产出 MSL 与资源绑定信息； 🔹 语料扫描、GPU 数值比对、缓存键身份共同保证了翻译的可靠性与效果一致性。

下次你的 Mac 桌面上粒子飞舞、光影流动时，背后正是这套"翻译术"在工作。🖥️