用途
compiling-wgsl 是一个纯 Python 的 WGSL 工具链,核心为 scripts/forge,仅依赖 numpy(--png 选项另需 pillow)。它用于生成、压缩和转换 WGSL 着色器,主要覆盖三类任务:压缩已有 WGSL、将 GLSL 转换为 WGSL、将 SVG 编译为着色器。
主要能力
- WGSL 压缩:
python3 -m forge minify in.wgsl -o out.wgsl可压缩着色器,典型着色器可保留约 30–35% 的原始字节(语料库实测 34%)。支持--no-aliases跳过别名、--keep a,b保护名称不被重命名或移除。入口点名称、override 名称、绑定编号和属性不会被更改。 - GLSL 转 WGSL:
python3 -m forge glsl shader.frag -o shader.wgsl [--minify]自动识别输入类型:Shadertoy(含 mainImage 且无 main)、WebGL 2(#version 300 es)、WebGL 1(无版本行)、Vulkan GLSL 450(#version 450)。转换通过 naga 的 GLSL 读取器完成;naga 拒绝时改用 glslang 编译为 SPIR-V 再由 naga 翻译(--backend可强制指定)。 - SVG 转着色器:
python3 -m forge svg icon.svg --minify -o icon.wgsl,支持--grid N控制路径坐标步长、--paint-in 4实现逐形状显现动画、--loop循环播放。大型场景会使用形状表(四个以上连续简单形状合并为循环绘制)和存储缓冲区(路径数据超过 8192 个整数时移至 @group(0) @binding(1))。 - Python 场景构建:通过
forge.scene模块以代码方式构建场景,支持动画表达式、SDF 操作(smooth_union、subtract、intersect 等),可输出 WGSL 或参考 SVG 帧。 - 验证工具:
verify.py minify验证压缩结果(naga 校验、Tint 编译、计算着色器逐字节比对);verify.py glsl验证 GLSL 移植(Shadertoy 代码需达到 30 dB PSNR);verify.py svg报告平均误差、PSNR 和墨水比率。
使用方式
设置 export SKILL=/mnt/skills/user/compiling-wgsl,安装依赖 pip install --break-system-packages numpy pillow,安装 naga(cargo install naga-cli)和 glslang(apt-get install -y glslang-tools)。GPU 检查需要 Playwright 的 Chromium,可通过 CHROME_PATH 指定浏览器路径。运行 python3 $SKILL/scripts/selftest.py 进行自检。所有命令需设置 PYTHONPATH=$SKILL/scripts。
适用场景
- 压缩手写或生成的 WGSL 着色器以减少传输字节。
- 将 WebGL/Shadertoy/Vulkan GLSL 移植到 WebGPU 的 WGSL。
- 将图标、图表等 SVG 转换为可渲染的着色器,或构建带动画的程序化场景。
限制
- 不处理 HLSL 或 Metal;HLSL 可先经 DXC 转为 SPIR-V 再由 naga 读取。
- 桌面 OpenGL 的 #version 330 或更旧版本、使用 iChannel 缓冲区的多通道 Shadertoy 代码虽可转换,但多通道管线需宿主代码自行实现。
- SVG 中的 text、image、clipPath、mask、filter、pattern、marker 元素会被跳过,若这些元素承载设计则着色器结果会出错。
- 每个像素需遍历所有路径段,包含数千段的大型场景不适合作为单个着色器。
- 小于 1 KB 的着色器压缩收益有限。
- 抗锯齿按每个形状单一距离计算,细于一个像素的特征可能偏粗(墨水比率 1.03–1.07)。
- 曲线拟合精度默认 0.2(其中十分之一用于曲线拟合),约支持 50 倍放大。
- 整数取模或除法在负操作数上与 WebGL 行为不同,GLSL 中此为未定义行为。
- 部分失败模式有明确诊断,如 naga 30 的模板参数别名问题、Tint 对未使用代码的拒绝、计算着色器竞态等。