shader-art-coding

着色器艺术编程

将着色器创作视为视觉工程：从预期图像入手，选择能实现它的最简数学模型，分阶段构建，并通过调试视图验证每个阶段。

工作流

1. 目标。 描述图像：主体、相机与取景、主要形体、材质、光照、运动。
2. 路径。 从 references/subject-routing.md 中选择渲染模型和起始模板： 2D 距离场（海报、图标、图案）、SDF 光线步进（物体、角色）、高度场步进 （景观）、体积积分（云、烟、火）。
3. 从库中组装。 使用 python3 scripts/glsl_tools.py search <words> 或 references/library-index.md 查找构建模块，并按名称调用。不要粘贴或重新推导库中的代码；这些代码已通过测试。
4. 快速生成首张图像。 先处理坐标、背景、一个基本图形和一盏灯。然后添加调试视图。
5. 按顺序优化： 比例、构图、材质区分、光照、氛围、色彩、抗锯齿、性能。
6. 打包并检查。 python3 scripts/glsl_tools.py bundle shader.glsl -o out.glsl 会内联实际用到的函数。 python3 scripts/glsl_tools.py check out.glsl 会对其进行检查，并在已安装 glslangValidator 时编译。 修复所有错误，然后交付 out.glsl。

从此技能的目录运行脚本。只需要 Python 3。

约定

• 坐标： vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;，因此一个像素的大小为 2.0 / iResolution.y。
• 场景接口： vec2 map(vec3 p) 返回 vec2(distance, materialId)。raymarch、calcNormal、 softShadow、calcAO 和 sdfThickness 都使用它。
• 调试： #define DEBUG_MODE 0，其中 0 表示最终效果，1 表示距离场，2 表示法线，3 表示 ID，4 表示步数，5 表示遮罩， 6 表示光照项。
• 颜色管线： 在线性空间中计算光照，并使用 srgbToLinear 解码选取的颜色。然后进行曝光，再执行色调映射 （每个 AA 采样默认使用 tonemapAgX），再计算平均值，随后只调用一次 linearToSrgb，最后调用 ditherTPDF。
• 距离： 遵循 @exact / @bound / @approx 标签。如果形变使 Lipschitz 常数大于 1，则除以该距离，或降低 raymarch 的 stepScale。

硬性规则（违反会导致 Shadertoy/WebGL 出错）

• 不要使用 #version 行、自定义 uniform、gl_FragColor / texture2D / iGlobalTime。
• 不要对结构体使用 ?:。使用 vec2(distance, id) 或 if。
• 浮点字面量必须带小数：2.0 * PI、clamp(x, 0.0, 1.0)。
• 不要使用 fract(sin(...) * 43758.5453) 哈希。请使用 hash12 / hash22 / hash33（整数 PCG）。即使移植时要求“保持外观”，也要替换它们：正弦哈希的确切图案在不同 GPU 之间本就不同，而对相同的整数单元格 ID 使用 PCG 哈希，生成的噪声外观一致。check 会将正弦哈希报告为错误。
• 防范 NaN 来源：atan(0, 0)、负数的 pow、负数的 sqrt、normalize(vec3(0))。
• 不要在非均匀分支和循环中使用 dFdx / fwidth，或改用显式像素大小。

参考资料路由

只阅读任务所需内容：

文件	阅读时机
references/subject-routing.md	从主题（“水母”“山脉”）着手时；将正式名称映射到主题
references/library-index.md	选择函数时：列出库中每个函数的签名、精确度和用途
references/sdf-library-guide.md	建模时：精确度等级、混合、邻居检查式重复、变形限制、WebGL 陷阱
references/rendering-pipeline.md	光照配置、阴影/AO、天空与雾、体积、色调映射、抗锯齿、性能
references/noise-use-cases.md	选择 Perlin/值噪声/单纯形/细胞噪声，fBm/脊状/波纹/扭曲/混合方案、游戏用例和一手来源代码链接
references/procedural-buildings.md	地块 ID、建筑体量、退界/屋顶、立面筛选、城市重复和游戏集成
references/terrain-production.md	地形表示、设计山谷、坡度/海拔材质、追踪限制、分块和 LOD
references/water-quality.md	高质量海洋/沿海水体、波浪导数、菲涅耳/折射/吸收、泡沫、预设和引擎侧升级
references/shader-workflow.md	从头到尾规划复杂着色器；审查清单
references/composition-and-debugging.md	图像难以辨认，或视觉效果不对时
references/formula-cookbook.md	多步骤方案：模块化单元格晶格、地形合成、有机组合
references/formula-code-couples-sdf.md	有机和模块化 SDF 特征的公式到代码
references/formula-code-couples-terrain.md	高度场、密度场、累积、大气
references/formula-code-couples-materials.md	遮罩、调色板、光照项、润色、运动

templates/ 中的模板是完整且经过渲染验证的起点（图库见仓库 README）： raymarch-sdf.glsl、terrain.glsl、ocean.glsl、volumetric-clouds.glsl、sdf-2d-poster.glsl、 pattern-swatches.glsl、noise-progression.glsl、noise-terrain-map.glsl、procedural-city.glsl、 alpine-valley.glsl、coastal-water.glsl。

输出要求

编写着色器时：

• 提供打包好的、可直接粘贴到 Shadertoy 的代码，其中包含 mainImage(out vec4 fragColor, in vec2 fragCoord)。
• 除非用户提供纹理，否则避免使用纹理。
• 包含 DEBUG_MODE 开关，并将美术控制项命名为顶部的常量。
• 最后附上简短的调节指南：说明哪些常量控制尺度、柔和度、颜色、光照和运动。
• 说明着色器是否经过编译检查，以及检查方式。
• 对建筑/地形/水体，区分已实现功能与引擎侧升级。不要把高度场称为洞穴生成器，不要把材质窗口称为建模凹槽，也不要把程序化泡沫/焦散遮罩称为流体/光照模拟。
• 对质量相关请求，说明目标和预算，提供预设/调试视图，并检查渲染输出。 为重要模板预设添加 // @variant QUALITY=3（或其他已定义的整数宏），以便 CI 编译并渲染这些预设。添加细节前，先保留地平线/岸线接触效果并做好时间滤波。

改进现有着色器时：

• 确定其渲染模型和瓶颈。
• 保留原有意图和接口。
• 先修正正确性，再提升可读性、视觉质量和速度。
• 指出有风险的改动（坐标尺度、材质 ID、循环次数）。