Skip to content

archibate/dotfiles-opencode / skills/shader-dev

shader-dev

Verified

Comprehensive GLSL shader techniques for creating stunning visual effects — ray marching, SDF modeling, fluid simulation, particle systems, procedural generation, lighting, post-processing, and more.

FileKindSize
SKILL.mdskill md16.5 KB
reference/ambient-occlusion.mdmarkdown14.5 KB
reference/analytic-ray-tracing.mdmarkdown24.1 KB
reference/anti-aliasing.mdmarkdown2.9 KB
reference/atmospheric-scattering.mdmarkdown27.5 KB
reference/camera-effects.mdmarkdown3.0 KB
reference/cellular-automata.mdmarkdown26.7 KB
reference/color-palette.mdmarkdown19.9 KB
reference/csg-boolean-operations.mdmarkdown17.5 KB
reference/domain-repetition.mdmarkdown17.7 KB
reference/domain-warping.mdmarkdown16.6 KB
reference/fluid-simulation.mdmarkdown18.5 KB
reference/fractal-rendering.mdmarkdown18.2 KB
reference/lighting-model.mdmarkdown29.4 KB
reference/matrix-transform.mdmarkdown18.5 KB
reference/multipass-buffer.mdmarkdown24.8 KB
reference/normal-estimation.mdmarkdown17.2 KB
reference/particle-system.mdmarkdown28.3 KB
reference/path-tracing-gi.mdmarkdown27.5 KB
reference/polar-uv-manipulation.mdmarkdown22.6 KB
reference/post-processing.mdmarkdown23.9 KB
reference/procedural-2d-pattern.mdmarkdown16.3 KB
reference/procedural-noise.mdmarkdown21.7 KB
reference/ray-marching.mdmarkdown15.5 KB
reference/sdf-2d.mdmarkdown27.5 KB
reference/sdf-3d.mdmarkdown26.8 KB
reference/sdf-tricks.mdmarkdown2.6 KB
reference/shadow-techniques.mdmarkdown21.0 KB
reference/simulation-physics.mdmarkdown27.6 KB
reference/sound-synthesis.mdmarkdown23.6 KB
reference/terrain-rendering.mdmarkdown32.2 KB
reference/texture-mapping-advanced.mdmarkdown3.3 KB
reference/texture-sampling.mdmarkdown25.6 KB
reference/volumetric-rendering.mdmarkdown28.1 KB
reference/voronoi-cellular-noise.mdmarkdown17.6 KB
reference/voxel-rendering.mdmarkdown29.2 KB
reference/water-ocean.mdmarkdown20.2 KB
reference/webgl-pitfalls.mdmarkdown1.9 KB
techniques/ambient-occlusion.mdmarkdown11.1 KB
techniques/analytic-ray-tracing.mdmarkdown18.8 KB
techniques/anti-aliasing.mdmarkdown4.5 KB
techniques/atmospheric-scattering.mdmarkdown18.2 KB
techniques/camera-effects.mdmarkdown3.4 KB
techniques/cellular-automata.mdmarkdown19.0 KB
techniques/color-palette.mdmarkdown12.8 KB
techniques/csg-boolean-operations.mdmarkdown15.0 KB
techniques/domain-repetition.mdmarkdown9.7 KB
techniques/domain-warping.mdmarkdown12.5 KB
techniques/fluid-simulation.mdmarkdown46.5 KB
techniques/fractal-rendering.mdmarkdown13.0 KB
techniques/lighting-model.mdmarkdown17.1 KB
techniques/matrix-transform.mdmarkdown12.4 KB
techniques/multipass-buffer.mdmarkdown33.5 KB
techniques/normal-estimation.mdmarkdown9.1 KB
techniques/particle-system.mdmarkdown44.6 KB
techniques/path-tracing-gi.mdmarkdown21.5 KB
techniques/polar-uv-manipulation.mdmarkdown13.2 KB
techniques/post-processing.mdmarkdown30.3 KB
techniques/procedural-2d-pattern.mdmarkdown10.7 KB
techniques/procedural-noise.mdmarkdown16.9 KB
techniques/ray-marching.mdmarkdown13.7 KB
techniques/sdf-2d.mdmarkdown21.2 KB
techniques/sdf-3d.mdmarkdown21.6 KB
techniques/sdf-tricks.mdmarkdown3.4 KB
techniques/shadow-techniques.mdmarkdown24.8 KB
techniques/simulation-physics.mdmarkdown56.2 KB
techniques/sound-synthesis.mdmarkdown17.2 KB
techniques/terrain-rendering.mdmarkdown14.3 KB
techniques/texture-mapping-advanced.mdmarkdown4.3 KB
techniques/texture-sampling.mdmarkdown13.0 KB
techniques/volumetric-rendering.mdmarkdown12.3 KB
techniques/voronoi-cellular-noise.mdmarkdown13.0 KB
techniques/voxel-rendering.mdmarkdown45.2 KB
techniques/water-ocean.mdmarkdown17.8 KB
techniques/webgl-pitfalls.mdmarkdown5.4 KB

techniques/normal-estimation.md

View on GitHub
## WebGL2 Adaptation Requirements

**IMPORTANT: GLSL Type Strictness Warning**:
- GLSL is a strongly typed language with **no `string` type**; using string types is forbidden
- Common illegal types: `string`, `int` (can only use `int` literals, cannot declare variable types as `int`)
- vec2/vec3/vec4 cannot be implicitly converted between each other; explicit construction is required
- Float precision: `highp float` (recommended), `mediump float`, `lowp float`

The code templates in this document use ShaderToy GLSL style. When generating standalone HTML pages, you must adapt for WebGL2:

- Use `canvas.getContext("webgl2")`
- Shader first line: `#version 300 es`, add `precision highp float;` in fragment shader
- Vertex shader: `attribute` -> `in`, `varying` -> `out`
- Fragment shader: `varying` -> `in`, `gl_FragColor` -> custom `out vec4 fragColor`, `texture2D()` -> `texture()`
- ShaderToy's `void mainImage(out vec4 fragColor, in vec2 fragCoord)` must be adapted to the standard `void main()` entry point

# SDF Normal Estimation

## Use Cases

- Lighting calculations in raymarching rendering pipelines (diffuse, specular, Fresnel, etc.)
- Any 3D scene based on SDF distance fields (fractals, parametric surfaces, boolean geometry, procedural terrain)
- Edge detection and contour rendering (Laplacian value as a byproduct of normal sampling)
- Prerequisite for ambient occlusion (AO) computation

## Core Principles

The gradient of an SDF `nabla f(p)` points in the direction of fastest distance increase, which is the outward surface normal. Numerical differentiation approximates the gradient:

$$\vec{n} = \text{normalize}\left(\nabla f(p)\right)$$

Three main strategies:

| Method | Samples | Accuracy | Recommendation |
|--------|---------|----------|----------------|
| Forward difference | 4 | O(epsilon) | Simple scenes |
| Central difference | 6 | O(epsilon^2) | When symmetry is needed |
| **Tetrahedron method** | **4** | **Between the two** | **Preferred** |

Key parameter epsilon: commonly `0.0005 ~ 0.001`; for advanced scenes, multiply by ray distance `t` for adaptive scaling.

## Implementation Steps

### Step 1: Define SDF Scene Function

```glsl
float map(vec3 p) {
    float d = length(p) - 1.0; // unit sphere
    return d;
}
```

### Step 2: Choose Differentiation Method

#### Method A: Forward Difference -- 4 Samples

```glsl
const float EPSILON = 1e-3;

vec3 getNormal(vec3 p) {
    vec3 n;
    n.x = map(vec3(p.x + EPSILON, p.y, p.z));
    n.y = map(vec3(p.x, p.y + EPSILON, p.z));
    n.z = map(vec3(p.x, p.y, p.z + EPSILON));
    return normalize(n - map(p));
}
```

#### Method B: Central Difference -- 6 Samples

```glsl
vec3 getNormal(vec3 p) {
    vec2 o = vec2(0.001, 0.0);
    return normalize(vec3(
        map(p + o.xyy) - map(p - o.xyy),
        map(p + o.yxy) - map(p - o.yxy),
        map(p + o.yyx) - map(p - o.yyx)
    ));
}
```

#### Method C: Tetrahedron Method -- 4 Samples (Recommended)

```glsl
// Classic tetrahedron method, coefficient 0.5773 ~ 1/sqrt(3)
vec3 calcNormal(vec3 pos) {
    float eps = 0.0005;
    vec2 e = vec2(1.0, -1.0) * 0.5773;
    return normalize(
        e.xyy * map(pos + e.xyy * eps) +
        e.yyx * map(pos + e.yyx * eps) +
        e.yxy * map(pos + e.yxy * eps) +
        e.xxx * map(pos + e.xxx * eps)
    );
}
```

### Step 3: Apply to Lighting

```glsl
vec3 pos = ro + rd * t;        // hit point
vec3 nor = calcNormal(pos);    // surface normal

vec3 lightDir = normalize(vec3(1.0, 4.0, -4.0));
float diff = max(dot(nor, lightDir), 0.0);
vec3 col = vec3(0.8) * diff;
```

## Complete Code Template

```glsl
// SDF Normal Estimation — Complete ShaderToy Template

#define MAX_STEPS 128
#define MAX_DIST 100.0
#define SURF_DIST 0.001
#define NORMAL_METHOD 2      // 0=forward diff, 1=central diff, 2=tetrahedron

// ---- SDF Scene Definition ----
float map(vec3 p) {
    float sphere = length(p - vec3(0.0, 1.0, 0.0)) - 1.0;
    float ground = p.y;
    return min(sphere, ground);
}

// ---- Normal Estimation ----

vec3 normalForward(vec3 p) {
    float eps = 0.001;
    float d = map(p);
    return normalize(vec3(
        map(p + vec3(eps, 0.0, 0.0)),
        map(p + vec3(0.0, eps, 0.0)),
        map(p + vec3(0.0, 0.0, eps))
    ) - d);
}

vec3 normalCentral(vec3 p) {
    vec2 e = vec2(0.001, 0.0);
    return normalize(vec3(
        map(p + e.xyy) - map(p - e.xyy),
        map(p + e.yxy) - map(p - e.yxy),
        map(p + e.yyx) - map(p - e.yyx)
    ));
}

vec3 normalTetra(vec3 p) {
    float eps = 0.0005;
    vec2 e = vec2(1.0, -1.0) * 0.5773;
    return normalize(
        e.xyy * map(p + e.xyy * eps) +
        e.yyx * map(p + e.yyx * eps) +
        e.yxy * map(p + e.yxy * eps) +
        e.xxx * map(p + e.xxx * eps)
    );
}

vec3 calcNormal(vec3 p) {
#if NORMAL_METHOD == 0
    return normalForward(p);
#elif NORMAL_METHOD == 1
    return normalCentral(p);
#else
    return normalTetra(p);
#endif
}

// ---- Raymarching ----
float raymarch(vec3 ro, vec3 rd) {
    float t = 0.0;
    for (int i = 0; i < MAX_STEPS; i++) {
        vec3 p = ro + rd * t;
        float d = map(p);
        if (d < SURF_DIST || t > MAX_DIST) break;
        t += d;
    }
    return t;
}

// ---- Main Function ----
void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;

    vec3 ro = vec3(0.0, 2.0, -5.0);
    vec3 rd = normalize(vec3(uv, 1.5));

    float t = raymarch(ro, rd);
    vec3 col = vec3(0.0);

    if (t < MAX_DIST) {
        vec3 pos = ro + rd * t;
        vec3 nor = calcNormal(pos);

        vec3 sunDir = normalize(vec3(0.8, 0.4, -0.6));
        float diff = clamp(dot(nor, sunDir), 0.0, 1.0);
        float amb = 0.5 + 0.5 * nor.y;
        vec3 ref = reflect(rd, nor);
        float spec = pow(clamp(dot(ref, sunDir), 0.0, 1.0), 16.0);

        col = vec3(0.18) * amb + vec3(1.0, 0.95, 0.85) * diff + vec3(0.5) * spec;
    } else {
        col = vec3(0.5, 0.7, 1.0) - 0.5 * rd.y;
    }

    col = pow(col, vec3(0.4545));
    fragColor = vec4(col, 1.0);
}
```

## Common Variants

### Variant 1: NuSan Reverse-Offset Forward Difference

```glsl
// Reverse-offset forward difference
vec2 noff = vec2(0.001, 0.0);
vec3 normal = normalize(
    map(pos) - vec3(
        map(pos - noff.xyy),
        map(pos - noff.yxy),
        map(pos - noff.yyx)
    )
);
```

### Variant 2: Adaptive Epsilon (Distance Scaling)

```glsl
// Adaptive epsilon based on ray distance
vec3 calcNormal(vec3 pos, float t) {
    float precis = 0.001 * t;
    vec2 e = vec2(1.0, -1.0) * precis;
    return normalize(
        e.xyy * map(pos + e.xyy) +
        e.yyx * map(pos + e.yyx) +
        e.yxy * map(pos + e.yxy) +
        e.xxx * map(pos + e.xxx)
    );
}
```

### Variant 3: Large Epsilon for Rounding / Anti-Aliasing

```glsl
// Large epsilon for rounding / anti-aliasing
vec3 getNormal(vec3 p) {
    vec2 e = vec2(0.015, -0.015); // intentionally large epsilon
    return normalize(
        e.xyy * map(p + e.xyy) +
        e.yyx * map(p + e.yyx) +
        e.yxy * map(p + e.yxy) +
        e.xxx * map(p + e.xxx)
    );
}
```

### Variant 4: Anti-Inlining Loop

```glsl
// Anti-inlining loop — reduces compile time for complex SDFs
#define ZERO (min(iFrame, 0))

vec3 calcNormal(vec3 p, float t) {
    vec3 n = vec3(0.0);
    for (int i = ZERO; i < 4; i++) {
        vec3 e = 0.5773 * (2.0 * vec3(
            (((i + 3) >> 1) & 1),
            ((i >> 1) & 1),
            (i & 1)
        ) - 1.0);
        n += e * map(p + e * 0.001 * t);
    }
    return normalize(n);
}
```

### Variant 5: Normal + Edge Detection

```glsl
// Central difference + Laplacian edge detection
float edge = 0.0;
vec3 normal(vec3 p) {
    vec3 e = vec3(0.0, det * 5.0, 0.0);

    float d1 = de(p - e.yxx), d2 = de(p + e.yxx);
    float d3 = de(p - e.xyx), d4 = de(p + e.xyx);
    float d5 = de(p - e.xxy), d6 = de(p + e.xxy);
    float d  = de(p);

    edge = abs(d - 0.5 * (d2 + d1))
         + abs(d - 0.5 * (d4 + d3))
         + abs(d - 0.5 * (d6 + d5));
    edge = min(1.0, pow(edge, 0.55) * 15.0);

    return normalize(vec3(d1 - d2, d3 - d4, d5 - d6));
}
```

## Performance & Composition

**Performance**:
- Default to tetrahedron method (4 samples, better accuracy than forward difference)
- Only switch to central difference (6 samples) when jagged normal artifacts appear
- Use anti-inlining loop (Variant 4) for complex SDFs to avoid compile time explosion
- Epsilon recommended `0.0005 ~ 0.001`; best practice is adaptive `eps * t`
- Too small (< 1e-5) produces floating-point noise; too large (> 0.05) loses detail
- Reuse SDF sampling results when multiple types of information are needed at the same position (e.g., Variant 5)

**Common combinations**:
- **Normal + Soft Shadow**: `calcSoftShadow(pos + nor * 0.01, sunDir, 16.0)` -- normal offset at start point to avoid self-intersection
- **Normal + AO**: Multi-step SDF sampling along the normal to estimate occlusion
- **Normal + Fresnel**: `pow(clamp(1.0 + dot(nor, rd), 0.0, 1.0), 5.0)`
- **Normal + Bump Mapping**: Overlay texture gradient perturbation on SDF normals
- **Normal + Triplanar Mapping**: Use `abs(nor)` components as triplanar blend weights

## Further Reading

For complete step-by-step tutorials, mathematical derivations, and advanced usage, see [reference](../reference/normal-estimation.md)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall