name: shader-dev
description: 全面的GLSL着色器技术，用于创建惊艳的视觉效果——光线步进、SDF建模、流体模拟、粒子系统、程序化生成、光照、后期处理等等。
license: MIT
metadata:
    version: "1.0"
    category: graphics

Shader Craft

一个覆盖36种GLSL着色器技术（兼容ShaderToy）的统一技能，用于实时视觉效果。

调用方式

/shader-dev <请求>

$ARGUMENTS 包含用户的请求（例如“创建一个带柔和阴影的光线步进SDF场景”）。

技能结构

shader-dev/
├── SKILL.md                      # 核心技能（本文件）
├── techniques/                   # 实现指南（根据路由表读取）
│   ├── ray-marching.md           # 使用SDF进行球体追踪
│   ├── sdf-3d.md                 # 3D符号距离函数
│   ├── lighting-model.md         # PBR、Phong、卡通着色
│   ├── procedural-noise.md       # Perlin、Simplex、FBM
│   └── ...                       # 另外34个技术文件
└── reference/                    # 详细指南（按需读取）
    ├── ray-marching.md           # 数学推导与高级模式
    ├── sdf-3d.md                 # 扩展SDF理论
    ├── lighting-model.md         # 光照数学深度解析
    ├── procedural-noise.md       # 噪声函数理论
    └── ...                       # 另外34个参考文件

使用方法

1. 阅读下方的技术路由表，找出与用户请求匹配的一个或多个技术
2. 从 techniques/ 目录中读取相关文件——每个文件包含核心原理、实现步骤和完整的代码模板
3. 如需更深入的理解（数学推导、高级模式），可跟随每个技术文件底部的引用链接到 reference/
4. 生成独立HTML页面时，应用下方的WebGL2适配规则

技术路由表

技术索引

几何体与SDF

• sdf-2d — 用于形状、UI、抗锯齿渲染的2D符号距离函数
• sdf-3d — 用于实时隐式曲面建模的3D符号距离函数
• csg-boolean-operations — 构造实体几何：并集、差集、交集，支持平滑混合
• domain-repetition — 无限空间重复、折叠、有限平铺
• domain-warping — 用噪声扭曲域以产生有机流动形状
• sdf-tricks — SDF优化、包围盒、二分搜索细化、掏空、分层边缘、调试可视化

光线投射与光照

• ray-marching — 使用SDF进行球体追踪以渲染3D场景
• analytic-ray-tracing — 封闭形式射线-基本体相交（球体、平面、盒体、环面）
• path-tracing-gi — 蒙特卡洛路径追踪实现照片级全局光照
• lighting-model — Phong、Blinn-Phong、PBR（Cook-Torrance）和卡通着色
• shadow-techniques — 硬阴影、柔和阴影（半影估计）、级联阴影
• ambient-occlusion — 基于SDF的环境光遮蔽、屏幕空间环境光遮蔽近似
• normal-estimation — 有限差分法线、四面体技术

模拟与物理

• fluid-simulation — 纳维-斯托克斯流体求解器，包含平流、扩散、压力投影
• simulation-physics — 基于GPU的物理：弹簧、布料、N体引力、碰撞
• particle-system — 无状态和有状态粒子系统（火、雨、火花、星系）
• cellular-automata — 生命游戏、反应扩散（图灵图案）、沙子模拟

自然现象

• water-ocean — 格斯特纳波、FFT海洋、焦散、水下雾
• terrain-rendering — 高度场光线步进、FBM地形、侵蚀
• atmospheric-scattering — 瑞利/米氏散射、神光、SSS近似
• volumetric-rendering — 云、雾、火、爆炸的体积光线步进

程序化生成

• procedural-noise — 值噪声、Perlin、Simplex、Worley、FBM、脊状噪声
• procedural-2d-pattern — 砖块、六边形、Truchet、伊斯兰几何图案
• voronoi-cellular-noise — 沃罗诺伊图、Worley噪声、龟裂地面、晶体
• fractal-rendering — 曼德勃罗集、朱利亚集、3D分形（Mandelbox、Mandelbulb）
• color-palette — 余弦调色板、HSL/HSV/Oklab、动态颜色映射

后处理与基础设施

• post-processing — 辉光、色调映射（ACES、Reinhard）、暗角、色差、故障效果
• multipass-buffer — 乒乓FBO设置、跨帧状态持久化
• texture-sampling — 双线性、双三次、Mipmap、程序化纹理查找
• matrix-transform — 相机观察矩阵、投影、旋转、轨道控制
• polar-uv-manipulation — 极坐标/对数极坐标、万花筒、螺旋映射
• anti-aliasing — SSAA、SDF解析抗锯齿、时间抗锯齿（TAA）、FXAA后处理
• camera-effects — 景深（薄透镜）、运动模糊、镜头畸变、胶片颗粒、暗角
• texture-mapping-advanced — 双平面映射、纹理重复避免、射线差分滤波

音频

• sound-synthesis — GLSL中的程序化音频：振荡器、包络、滤波器、FM合成

调试与验证

• webgl-pitfalls — 常见WebGL2/GLSL错误：fragCoord、main()包装器、函数顺序、宏限制、uniform空值

WebGL2适配规则

所有技术文件使用ShaderToy GLSL风格。生成独立HTML页面时，应用以下适配：

着色器版本与输出

• 使用 canvas.getContext("webgl2")
• 着色器第一行：#version 300 es，片元着色器添加 precision highp float;
• 片元着色器必须声明：out vec4 fragColor;
• 顶点着色器：attribute → in，varying → out
• 片元着色器：varying → in，gl_FragColor → fragColor，texture2D() → texture()

片元坐标

• 使用 gl_FragCoord.xy 代替 fragCoord（WebGL2没有内置fragCoord）

// 错误
vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;
// 正确
vec2 uv = (2.0 * gl_FragCoord.xy - iResolution.xy) / iResolution.y;

ShaderToy模板的main()包装器

• ShaderToy使用 void mainImage(out vec4 fragColor, in vec2 fragCoord)
• WebGL2需要标准 void main() 入口点——始终包装mainImage：

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    // 着色器代码...
    fragColor = vec4(col, 1.0);
}

void main() {
    mainImage(fragColor, gl_FragCoord.xy);
}

函数声明顺序

• GLSL要求函数在使用前声明——要么在使用前声明，要么重新排序：

// 错误 — getAtmosphere() 调用了尚未定义的 getSunDirection()
vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // 错误！
vec3 getSunDirection() { return normalize(vec3(1.0)); }

// 正确 — 先定义被调用函数
vec3 getSunDirection() { return normalize(vec3(1.0)); }
vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // 正常

宏限制

• #define 不能使用函数调用——改用 const：

// 错误
#define SUN_DIR normalize(vec3(0.8, 0.4, -0.6))

// 正确
const vec3 SUN_DIR = vec3(0.756, 0.378, -0.567); // 预计算归一化值

脚本标签提取

• 从<script>标签提取着色器源码时，确保#version是第一个字符——使用.trim()：

const fs = document.getElementById('fs').text.trim();

常见陷阱

• 未使用的uniform：编译器可能优化掉未使用的uniform，导致gl.getUniformLocation()返回null——始终以编译器无法优化掉的方式使用uniform
• 循环索引：在循环中使用运行时常量，某些ES版本中不要用#define宏
• 地形函数：像terrainM(vec2)这样的函数需要XZ分量——使用terrainM(pos.xz + offset)而不是terrainM(pos + offset)

HTML页面设置

生成独立HTML页面时：

• Canvas填满整个视口，窗口大小变化时自动调整大小
• 页面背景黑色，无滚动条：body { margin: 0; overflow: hidden; background: #000; }
• 实现ShaderToy兼容的uniform：iTime、iResolution、iMouse、iFrame
• 对于多通效果（Buffer A/B），使用WebGL2帧缓冲 + 乒乓技术（参见multipass-buffer技术）

常见陷阱

JS变量声明顺序（TDZ——导致白屏崩溃）

let/const变量必须在<script>块的顶部声明，在所有引用它们的函数之前：

// 1. 状态变量放在最前面
let frameCount = 0;
let startTime = Date.now();

// 2. Canvas/GL初始化、着色器编译、FBO创建
const canvas = document.getElementById('canvas');
const gl = canvas.getContext('webgl2');
// ...

// 3. 函数和事件绑定放在最后
function resize() { /* 现在可以安全引用frameCount */ }
function render() { /* ... */ }
window.addEventListener('resize', resize);

原因：let/const存在暂时性死区——在声明前引用它们会抛出ReferenceError，导致白屏。

GLSL编译错误（写入着色器后自行检查）

• 函数签名不匹配：调用必须与定义在参数数量和类型上完全匹配。如果定义为 float fbm(vec3 p)，则不能使用 vec2 调用 fbm(uv)
• 保留字作为变量名：不要使用：patch、cast、sample、filter、input、output、common、partition、active
• 严格类型匹配：vec3 x = 1.0 是非法的——应使用 vec3 x = vec3(1.0)；不能使用 .z 访问 vec2
• 结构体上不能用三元运算符：ESSL不允许对结构体类型使用三元运算符——改用 if/else

性能预算

部署环境可能使用有限的GPU能力的头端软件渲染。请保持在以下限制内：

• 光线步进主循环：≤ 128步
• 体积采样/光照内循环：≤ 32步
• FBM八度：≤ 6层
• 每个像素的总嵌套循环迭代次数：≤ 1000（超过此值会冻结浏览器）

快速配方

常见效果组合——由技术模块组装完成的渲染管线。

照片级SDF场景

1. 几何体：sdf-3d（扩展基本体）+ csg-boolean-operations（三次/四次smin）
2. 渲染：ray-marching + normal-estimation（四面体法）
3. 光照：lighting-model（户外三光模型）+ shadow-techniques（改进的柔和阴影）+ ambient-occlusion
4. 大气：atmospheric-scattering（基于高度的带阳光色调的雾）
5. 后期：post-processing（ACES色调映射）+ anti-aliasing（2x SSAA）+ camera-effects（暗角）

有机/生物形态

1. 几何体：sdf-3d（扩展基本体 + 变形算子：扭曲、弯曲）+ csg-boolean（梯度感知smin实现材质混合）
2. 细节：procedural-noise（带导数的FBM）+ domain-warping
3. 表面：lighting-model（通过半Lambert实现的次表面散射近似）

程序化景观

1. 地形：terrain-rendering + procedural-noise（带导数的侵蚀FBM）
2. 纹理：texture-mapping-advanced（双平面映射 + 无平铺）
3. 天空：atmospheric-scattering（瑞利/米氏散射 + 高度雾）
4. 水面：water-ocean（格斯特纳波）+ lighting-model（菲涅尔反射）

风格化2D艺术

1. 形状：sdf-2d（扩展库）+ sdf-tricks（分层边缘、掏空）
2. 颜色：color-palette（余弦调色板）+ polar-uv-manipulation（万花筒）
3. 润色：anti-aliasing（SDF解析抗锯齿）+ post-processing（辉光、色差）

着色器调试技术

可视化调试方法——临时替换输出来诊断问题。