shader-dev

シェーダークラフト

リアルタイムの視覚効果に使える、36 種類の GLSL シェーダー技法（ShaderToy 互換）を網羅する統合スキルです。

呼び出し

/shader-dev <request>

$ARGUMENTS にはユーザーのリクエストが含まれます（例：「ソフトシャドウ付きのレイマーチング SDF シーンを作成する」）。

スキルの構成

shader-dev/
├── SKILL.md                      # Core skill (this file)
├── techniques/                   # Implementation guides (read per routing table)
│   ├── ray-marching.md           # Sphere tracing with SDF
│   ├── sdf-3d.md                 # 3D signed distance functions
│   ├── lighting-model.md         # PBR, Phong, toon shading
│   ├── procedural-noise.md       # Perlin, Simplex, FBM
│   └── ...                       # 34 more technique files
└── reference/                    # Detailed guides (read as needed)
    ├── ray-marching.md           # Math derivations & advanced patterns
    ├── sdf-3d.md                 # Extended SDF theory
    ├── lighting-model.md         # Lighting math deep-dive
    ├── procedural-noise.md       # Noise function theory
    └── ...                       # 34 more reference files

使用方法

1. 技法のルーティング表を確認し、ユーザーのリクエストに合う技法を特定します
2. techniques/ 内の関連ファイルを読みます。各ファイルには、基本原則、実装手順、完全なコードテンプレートが含まれています
3. 数式の導出や高度なパターンなど、より深い理解が必要な場合は、各技法ファイルの末尾にある reference/ への参照リンクを確認します
4. スタンドアロンの HTML ページを生成する際は、以下の WebGL2 適用ルールを適用します

技法のルーティング表

ユーザーが作成したいもの...	主なテクニック	組み合わせるもの
数学に基づく3Dオブジェクト／シーン	ray-marching + sdf-3d	lighting-model、shadow-techniques
複雑な3D形状（ブーリアン演算、ブレンド）	csg-boolean-operations	sdf-3d、ray-marching
3D空間で無限に繰り返すパターン	domain-repetition	sdf-3d、ray-marching
有機的／歪んだ形状	domain-warping	procedural-noise
流体／煙／インクのエフェクト	fluid-simulation	multipass-buffer
パーティクルエフェクト（炎、火花、雪）	particle-system	procedural-noise、color-palette
物理ベースのシミュレーション	simulation-physics	multipass-buffer
ライフゲーム／反応拡散	cellular-automata	multipass-buffer、color-palette
海／水面	water-ocean	atmospheric-scattering、lighting-model
地形／風景	terrain-rendering	atmospheric-scattering、procedural-noise
雲／霧／ボリューム炎	volumetric-rendering	procedural-noise、atmospheric-scattering
空／夕焼け／大気	atmospheric-scattering	volumetric-rendering
リアルなライティング（PBR、Phong）	lighting-model	shadow-techniques、ambient-occlusion
影（ソフト／ハード）	shadow-techniques	lighting-model
アンビエントオクルージョン	ambient-occlusion	lighting-model、normal-estimation
パストレーシング／グローバルイルミネーション	path-tracing-gi	analytic-ray-tracing、multipass-buffer
正確なレイとジオメトリの交差判定	analytic-ray-tracing	lighting-model
ボクセルワールド（Minecraft風）	voxel-rendering	lighting-model、shadow-techniques
ノイズ／FBMテクスチャ	procedural-noise	domain-warping
タイル状の2Dパターン	procedural-2d-pattern	polar-uv-manipulation
ボロノイ／セルパターン	voronoi-cellular-noise	color-palette
フラクタル（Mandelbrot、Julia、3D）	fractal-rendering	color-palette、polar-uv-manipulation
カラーグレーディング／パレット	color-palette	—
ブルーム／トーンマッピング／グリッチ	post-processing	multipass-buffer
マルチパスのピンポンバッファ	multipass-buffer	—
テクスチャ／サンプリングテクニック	texture-sampling	—
カメラ／行列変換	matrix-transform	—
表面法線	normal-estimation	—
極座標／万華鏡	polar-uv-manipulation	procedural-2d-pattern
SDFによる2D形状／UI	sdf-2d	color-palette
プロシージャルオーディオ／音楽	sound-synthesis	—
SDFのテクニック／最適化	sdf-tricks	sdf-3d、ray-marching
アンチエイリアスレンダリング	anti-aliasing	sdf-2d、post-processing
被写界深度／モーションブラー／レンズエフェクト	camera-effects	post-processing、multipass-buffer
高度なテクスチャマッピング／タイル化されないテクスチャ	texture-mapping-advanced	terrain-rendering、texture-sampling
WebGL2シェーダーのエラー／デバッグ	webgl-pitfalls	—

テクニック一覧

ジオメトリとSDF

• sdf-2d — 図形、UI、アンチエイリアスレンダリング向けの2D符号付き距離関数
• sdf-3d — リアルタイムの陰関数曲面モデリング向けの3D符号付き距離関数
• csg-boolean-operations — 立体幾何学的構成：滑らかなブレンドによる和、差、積
• domain-repetition — 無限空間の反復、折り畳み、限定的なタイル化
• domain-warping — ノイズで定義域を歪ませ、有機的で流れるような形状を作成
• sdf-tricks — SDFの最適化、境界ボリューム、二分探索による精緻化、中空化、レイヤー状のエッジ、デバッグ用可視化

レイキャスティングとライティング

• ray-marching — 3Dシーンのレンダリング向けの、SDFを使った球面トレーシング
• analytic-ray-tracing — レイとプリミティブ（球、平面、ボックス、トーラス）の閉形式交差判定
• path-tracing-gi — 写実的なグローバルイルミネーション向けのモンテカルロ・パストレーシング
• lighting-model — Phong、Blinn-Phong、PBR（Cook-Torrance）、トゥーンシェーディング
• shadow-techniques — ハードシャドウ、ソフトシャドウ（半影の推定）、カスケードシャドウ
• ambient-occlusion — SDFベースのAO、スクリーンスペースAO近似
• 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 — レンガ、六角形、トリュシェ、イスラム幾何学模様
• voronoi-cellular-noise — ボロノイ図、Worleyノイズ、ひび割れた大地、結晶
• fractal-rendering — マンデルブロ集合、ジュリア集合、3Dフラクタル（Mandelbox、Mandelbulb）
• color-palette — コサインパレット、HSL/HSV/Oklab、動的な色マッピング

ポストプロセスとインフラストラクチャ

• post-processing — ブルーム、トーンマッピング（ACES、Reinhard）、ビネット、色収差、グリッチ
• multipass-buffer — ピングポンFBOのセットアップ、フレーム間の状態保持
• texture-sampling — バイリニア、バイキュービック、ミップマップ、プロシージャルテクスチャの参照
• matrix-transform — カメラのルックアット、投影、回転、オービットコントロール
• polar-uv-manipulation — 極座標／対数極座標、万華鏡、螺旋マッピング
• anti-aliasing — SSAA、SDF解析的AA、時間的アンチエイリアス（TAA）、FXAAポストプロセス
• camera-effects — 被写界深度（薄レンズ）、モーションブラー、レンズ歪み、フィルムグレイン、ビネット
• texture-mapping-advanced — 二平面マッピング、テクスチャ反復の回避、レイ微分フィルタリング

オーディオ

• sound-synthesis — GLSLによるプロシージャルオーディオ：オシレーター、エンベロープ、フィルター、FM合成

デバッグと検証

• webgl-pitfalls — よくあるWebGL2/GLSLエラー：fragCoord、main()ラッパー、関数の順序、マクロの制限、uniform null

WebGL2への適応ルール

すべてのテクニックファイルでは、ShaderToyのGLSLスタイルを使用します。スタンドアロンのHTMLページを生成する場合は、次の適応を行ってください。

シェーダーバージョンと出力

• canvas.getContext("webgl2")を使用します
• シェーダーの1行目は#version 300 esとし、フラグメントシェーダーにはprecision highp float;を追加します
• フラグメントシェーダーではout vec4 fragColor;を宣言する必要があります
• 頂点シェーダー：attribute → in、varying → out
• フラグメントシェーダー：varying → in、gl_FragColor → fragColor、texture2D() → texture()

フラグメント座標

• fragCoord の代わりに gl_FragCoord.xy を使用してください（WebGL2 には組み込みの fragCoord はありません）

// WRONG
vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;
// CORRECT
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) {
    // shader code...
    fragColor = vec4(col, 1.0);
}

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

関数の宣言順序

• GLSL では関数を使用する前に宣言する必要があります。使用前に宣言するか、順序を入れ替えてください：

// WRONG — getAtmosphere() calls getSunDirection() before it's defined
vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // Error!
vec3 getSunDirection() { return normalize(vec3(1.0)); }

// CORRECT — define callee first
vec3 getSunDirection() { return normalize(vec3(1.0)); }
vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // Works

マクロの制限

• #define では関数呼び出しを使用できません。代わりに const を使用してください：

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

// CORRECT
const vec3 SUN_DIR = vec3(0.756, 0.378, -0.567); // Pre-computed normalized value

スクリプトタグからの抽出

• <script> タグからシェーダーソースを抽出する際は、#version が最初の文字になるようにしてください。.trim() を使用してください：

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

よくある落とし穴

• 未使用のユニフォーム：コンパイラーが未使用のユニフォームを最適化で削除し、gl.getUniformLocation() が null を返す場合があります。コンパイラーが最適化で削除できない方法で、必ずユニフォームを使用してください
• ループインデックス：一部の ES バージョンでは、ループ内で #define マクロではなく実行時定数を使用してください
• 地形関数：terrainM(vec2) のような関数には XZ 成分が必要です。terrainM(pos + offset) ではなく terrainM(pos.xz + offset) を使用してください

HTML ページのセットアップ

スタンドアロンの HTML ページを生成する場合：

• キャンバスをビューポート全体に広げ、ウィンドウのリサイズ時に自動でサイズを変更します
• ページの背景を黒にし、スクロールバーを非表示にします：body { margin: 0; overflow: hidden; background: #000; }
• ShaderToy 互換のユニフォームを実装します：iTime、iResolution、iMouse、iFrame
• マルチパスエフェクト（Buffer A/B）には、WebGL2 のフレームバッファーとピンポン方式を使用します（multipass-buffer のテクニックを参照）

よくある落とし穴

JS 変数の宣言順序（TDZ — 白い画面のクラッシュを引き起こします）

let／const 変数は、それらを参照する関数より前に、<script> ブロックの先頭で宣言する必要があります：

// 1. State variables FIRST
let frameCount = 0;
let startTime = Date.now();

// 2. Canvas/GL init, shader compile, FBO creation
const canvas = document.getElementById('canvas');
const gl = canvas.getContext('webgl2');
// ...

// 3. Functions and event bindings LAST
function resize() { /* can now safely reference frameCount */ }
function render() { /* ... */ }
window.addEventListener('resize', resize);

理由：let／const には一時的なデッドゾーンがあるため、宣言前に参照すると ReferenceError が発生し、画面が白くなります。

GLSL コンパイルエラー（シェーダー記述後に自己チェックしてください）

• 関数シグネチャの不一致：呼び出しは、引数の数と型が定義と完全に一致する必要があります。float fbm(vec3 p) と定義されている場合、vec2 の uv を使って fbm(uv) と呼び出すことはできません
• 予約語を変数名に使用：次の語は使用しないでください：patch、cast、sample、filter、input、output、common、partition、active
• 型の厳密な一致：vec3 x = 1.0 は無効です。vec3 x = vec3(1.0) を使用してください。また、vec2 の .z にアクセスすることはできません
• 構造体に対する三項演算子は使用不可：ESSL では構造体型に三項演算子を使用できません。代わりに if／else を使用してください

パフォーマンス予算

デプロイ環境では、GPU 性能が限られたヘッドレスのソフトウェアレンダリングが使用される場合があります。次の上限を守ってください：

• レイマーチングのメインループ：≤ 128 ステップ
• ボリュームサンプリング／ライティングの内部ループ：≤ 32 ステップ
• FBM オクターブ数：≤ 6 層
• ピクセルあたりのネストされたループの反復合計：≤ 1000（これを超えるとブラウザーがフリーズします）

クイックレシピ

よく使われるエフェクトの組み合わせです。テクニックモジュールを組み合わせて、レンダリングパイプライン全体を構成します。

写実的な SDF シーン

1. ジオメトリ：sdf-3d（拡張プリミティブ）＋ csg-boolean-operations（cubic／quartic 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（拡張プリミティブ＋変形演算子：twist、bend）＋ 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 分析的 AA）+ post-processing（ブルーム、色収差）

シェーダーのデバッグ手法

視覚的なデバッグ方法 — 問題を診断するために、出力を一時的に置き換えます。

確認項目	コード	見るべき点
サーフェス法線	col = nor * 0.5 + 0.5;	滑らかなグラデーション = 法線が正しい状態、縞模様 = イプシロンが大きすぎる状態
レイマーチのステップ数	col = vec3(float(steps) / float(MAX_STEPS));	赤いホットスポット = パフォーマンスのボトルネック、均一な色 = 無駄な反復
深度／距離	col = vec3(t / MAX_DIST);	ヒット距離が正しいか確認します
UV 座標	col = vec3(uv, 0.0);	座標マッピングを確認します
SDF 距離場	col = (d > 0.0 ? vec3(0.9,0.6,0.3) : vec3(0.4,0.7,0.85)) * (0.8 + 0.2*cos(150.0*d));	SDF の帯とゼロ交差を可視化します
チェッカーパターン（UV）	col = vec3(mod(floor(uv.x*10.)+floor(uv.y*10.), 2.0));	UV の歪みや継ぎ目を確認します
ライティングのみ	col = vec3(shadow); または col = vec3(ao);	影／AO の寄与を切り分けます
マテリアル ID	col = palette(matId / maxMatId);	マテリアルの割り当てを確認します