@3driseai/3drise-viewer 0.1.7 → 0.1.8

package/dist/shaders/glsl/terrainCore.glsl.js

@@ -0,0 +1,625 @@
+/**
+ * Shared terrain core. Imported by TerrainMaterial and available to anything else
+ * that needs to know where the ground is.
+ *
+ * Nothing here is per-type in the sense of separate code paths for separate
+ * renderers: the four landforms are one fBm with different shaping operators,
+ * selected by `u_terrainType`, exactly as the three volumetric cloud types are
+ * one marcher with different vertical profiles.
+ *
+ * These chunks assume three's `<common>` has already been included — PI and
+ * saturate come from there, and re-declaring them next to it is a compile error.
+ * `skyLib` from `cloudCore.glsl` is included alongside, so terrain, sky and
+ * clouds are lit by literally the same atmosphere function.
+ *
+ * ## The performance shape of this file
+ *
+ * Two decisions dominate the cost of everything below, and both were made after
+ * measuring rather than guessing:
+ *
+ * 1. **The height field carries its own derivative.** `terrainSample` returns the
+ *    surface gradient alongside the height, so a normal costs ONE evaluation
+ *    instead of the five a central difference needs. The chain rule is carried
+ *    through the domain warp, the contrast curve and every landform operator.
+ * 2. **The hash is arithmetic, not trigonometric.** `sin`-based hashing is the
+ *    default everywhere online and it is a trap at this call volume: four hashes
+ *    per octave, nine octaves, several evaluations per pixel puts it into the
+ *    billions of transcendentals per frame.
+ */
+/** Every uniform the height field and the shading read. */
+export const terrainUniforms = /* glsl */ `
+uniform int   u_terrainType;
+
+uniform float u_elevation;
+uniform float u_seaLevel;
+uniform float u_baseScale;      // 1 / featureSize
+uniform int   u_octaves;
+uniform float u_lacunarity;
+uniform float u_gain;
+uniform float u_ridge;
+uniform float u_warpStrength;
+uniform float u_warpScale;
+uniform float u_erosion;
+uniform float u_terraces;
+uniform float u_terraceSharp;
+uniform vec2  u_bearingDir;
+uniform float u_duneFreq;       // 2pi / duneWavelength
+uniform float u_duneAsym;
+uniform float u_plateau;
+uniform float u_valleyDepth;
+uniform float u_valleyWidth;
+
+uniform float u_cellSize;
+uniform float u_curvature;
+
+// surface
+uniform vec3  u_lowColor, u_midColor, u_rockColor, u_peakColor;
+uniform float u_slopeRockStart, u_slopeRockEnd;
+uniform float u_peakLevel, u_peakBlend, u_peakSlopeFalloff;
+uniform float u_macroVariation, u_macroScale;
+uniform float u_detailStrength, u_detailScale, u_detailFade;
+uniform float u_roughness, u_specular;
+
+// lighting. u_skyAmbient and u_groundAmbient come from useCloudSun through
+// applySunUniforms - the same objects that light the clouds. They are constant
+// across the frame, so computing them on the CPU rather than calling skyRadiance
+// per pixel removes an acos, a pow and three exps from every fragment.
+uniform vec3  u_skyAmbient;
+uniform vec3  u_groundAmbient;
+uniform float u_ambient, u_bounce, u_sunShadow, u_shadowSoftness;
+uniform float u_shadowDistance;
+uniform float u_fogDensity, u_exposure;
+uniform int   u_shadowSteps;
+`;
+/**
+ * Gradient noise with an analytic derivative.
+ *
+ * The derivative does two jobs. It is what makes `u_erosion` possible — real
+ * erosion strips material where water runs fastest, so damping each octave by the
+ * slope the octaves below it have already accumulated flattens valley floors and
+ * leaves ridges sharp. And it is what lets the surface normal fall out of the
+ * height evaluation for free instead of costing four extra ones.
+ *
+ * The hash is Hoskins-style: a few multiplies and fracts. The usual
+ * `fract(sin(dot(p, k)) * 43758.5453)` costs two transcendentals per component,
+ * and there are four hashes per octave — at nine octaves and several evaluations
+ * per shaded point that alone was most of the frame.
+ */
+export const terrainNoise = /* glsl */ `
+vec2 tHash(vec2 p){
+  vec3 p3 = fract(vec3(p.xyx) * vec3(0.1031, 0.1030, 0.0973));
+  p3 += dot(p3, p3.yzx + 33.33);
+  return -1.0 + 2.0 * fract((p3.xx + p3.yz) * p3.zy);
+}
+
+/** x = value in [-1,1], yz = d(value)/d(input). */
+vec3 tNoised(vec2 x){
+  vec2 i = floor(x);
+  vec2 f = fract(x);
+
+  vec2 u  = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);
+  vec2 du = 30.0 * f * f * (f * (f - 2.0) + 1.0);
+
+  vec2 ga = tHash(i + vec2(0.0, 0.0));
+  vec2 gb = tHash(i + vec2(1.0, 0.0));
+  vec2 gc = tHash(i + vec2(0.0, 1.0));
+  vec2 gd = tHash(i + vec2(1.0, 1.0));
+
+  float va = dot(ga, f - vec2(0.0, 0.0));
+  float vb = dot(gb, f - vec2(1.0, 0.0));
+  float vc = dot(gc, f - vec2(0.0, 1.0));
+  float vd = dot(gd, f - vec2(1.0, 1.0));
+
+  float k = va - vb - vc + vd;
+  float v = va + u.x * (vb - va) + u.y * (vc - va) + u.x * u.y * k;
+  vec2  d = ga + u.x * (gb - ga) + u.y * (gc - ga) + u.x * u.y * (ga - gb - gc + gd)
+          + du * (u.yx * k + vec2(vb, vc) - va);
+  return vec3(v, d);
+}
+
+float tNoise(vec2 x){ return tNoised(x).x; }
+`;
+/**
+ * The height field, and its gradient.
+ *
+ * `lodCell` is the world size of the cell being shaded, and every octave whose
+ * wavelength has fallen below a couple of those cells is faded out and then
+ * skipped. That is doing two jobs at once: it is the antialiasing (a ring 12 km
+ * out cannot resolve 4 m detail, and sampling it anyway is what makes distant
+ * terrain crawl), and it is most of the cost saving, because the outer rings —
+ * which carry three quarters of the vertices — run four octaves instead of nine.
+ */
+export const terrainHeight = /* glsl */ `
+#define TERRAIN_MOUNTAINS 0
+#define TERRAIN_DUNES     1
+#define TERRAIN_HILLS     2
+#define TERRAIN_CANYON    3
+
+#define TERRAIN_MAX_OCTAVES 12
+
+/** Normalised fBm in [0,1], derivative-damped, with d/d(worldXZ) in grad. */
+float terrainFbmD(vec2 p, float lodCell, out vec2 grad){
+  vec2 q = p * u_baseScale;
+
+  // Domain warp. Without it fBm reads as fBm: blobs with no direction and no
+  // drainage. Warping the sample point by a slower copy of the same noise bends
+  // ridge lines into the branching curves erosion actually produces.
+  //
+  // Its Jacobian is carried rather than assumed to be the identity. That shortcut
+  // is the usual one and it shows: at warpStrength 0.3 the normal is wrong by up
+  // to 30% precisely where the warp bends a ridge, which is where the eye goes.
+  vec2 qw = q;
+  mat2 J = mat2(1.0, 0.0, 0.0, 1.0);
+  if (u_warpStrength > 0.0){
+    vec3 w0 = tNoised(q * u_warpScale + vec2(11.3, 5.7));
+    vec3 w1 = tNoised(q * u_warpScale + vec2(-7.1, 19.2));
+    qw = q + vec2(w0.x, w1.x) * u_warpStrength;
+    float k = u_warpStrength * u_warpScale;
+    // Columns, so that (v * J) evaluates transpose(J) * v - which is the chain
+    // rule direction we need, and GLSL ES 1.00 has no transpose().
+    J = mat2(1.0 + k * w0.y, k * w1.y,
+             k * w0.z,       1.0 + k * w1.z);
+  }
+
+  float amp = 1.0;
+  float freq = 1.0;
+  float sum = 0.0;
+  float norm = 0.0;
+  vec2  gradW = vec2(0.0);   // d(sum) / d(qw)
+  vec2  slope = vec2(0.0);   // bounded erosion accumulator, octave-local units
+
+  // Wavelength of the first octave, in world units.
+  float wl = 1.0 / max(u_baseScale, 1e-9);
+
+  for (int i = 0; i < TERRAIN_MAX_OCTAVES; i++){
+    if (i >= u_octaves) break;
+
+    // Fade an octave out as its wavelength approaches the shading cell, then
+    // stop. Popping it off with a hard test leaves a visible ring where the
+    // clipmap level changes; fading is what makes the transition invisible.
+    float limit = 2.0 * lodCell;
+    float fade = clamp(wl / max(limit, 1e-4) - 1.0, 0.0, 1.0);
+    if (fade <= 0.001) break;
+
+    // A constant per-octave offset rather than a rotation matrix: rotating the
+    // domain would need the transpose applied to the derivative as well, and the
+    // offset decorrelates the octaves just as effectively.
+    vec3 n = tNoised(qw * freq + float(i) * vec2(37.13, 61.91));
+    float v = n.x;
+    vec2  g = n.yz;
+
+    // Ridge shaping, with the chain rule carried through so both the erosion term
+    // and the surface normal still see a true slope. 1 - |v| folds the noise about
+    // zero; squaring sharpens the crest.
+    if (u_ridge > 0.0){
+      // Ramp the fold in by octave. 1 - |v| is C1-discontinuous along the whole
+      // v = 0 contour, and on octave 0 that contour is a kilometre-long smooth
+      // arc - so the crease runs right across the terrain and reads as a
+      // modelling seam, not as a ridge. Found by baking presets to heightmaps
+      // and hillshading them, where the arcs are unmistakable; on the lit
+      // terrain they hide as a suspiciously straight shadow edge.
+      //
+      // A crest only reads as a crest at a scale where a crest is plausible, so
+      // the base octave stays smooth, the next is half folded and everything
+      // finer is fully ridged. Sharpness at the scales that matter is unchanged.
+      float ridgeAmt = u_ridge * clamp(float(i) * 0.5, 0.0, 1.0);
+      float s = sign(v);
+      float r = 1.0 - abs(v);
+      float rv = r * r * 2.0 - 1.0;
+      vec2  rg = -4.0 * r * s * g;
+      v = mix(v, rv, ridgeAmt);
+      g = mix(g, rg, ridgeAmt);
+    }
+
+    // The erosion term. Slope accumulated so far suppresses everything finer.
+    // Deliberately fed the OCTAVE-LOCAL derivative, not the frequency-scaled one:
+    // scaled, it grows like lacunarity^i, the damping collapses by the third
+    // octave and every finer octave vanishes - a terrain that is flat however high
+    // its elevation is set. Its own derivative is ignored, which is the standard
+    // approximation and invisible at these amplitudes.
+    float damp = 1.0 / (1.0 + u_erosion * 1.5 * dot(slope, slope));
+    float wgt = amp * damp * fade;
+
+    sum   += wgt * v;
+    norm  += amp * fade;
+    gradW += wgt * g * freq;
+    slope += g * amp * damp;
+
+    amp  *= u_gain;
+    freq *= u_lacunarity;
+    wl   /= u_lacunarity;
+  }
+
+  float inv = 1.0 / max(norm, 1e-4);
+
+  // Contrast, and it is not a taste knob.
+  //
+  // Dividing by the summed amplitude is the textbook normalisation and it is
+  // wrong for terrain: octaves of gradient noise almost never align, so the sum
+  // lands in about a quarter of the range the divisor assumes and the field comes
+  // out spanning 0.45-0.69 instead of 0-1. A 1400 m elevation then renders as a
+  // 320 m swell, and no amount of extra octaves fixes it because they are being
+  // divided away too. Measured against the height field directly: 3.2 recovers
+  // roughly 740 m of the 1400, which is a real range at a real grade.
+  //
+  // The soft clamp rather than a hard one, so a peak that would overshoot rolls
+  // off instead of arriving with a flat top.
+  float t = sum * inv * 3.2;
+  float rs = inversesqrt(1.0 + t * t);
+
+  // d(height)/d(qw) -> d/d(q) via the warp Jacobian -> d/d(world).
+  vec2 dqw = gradW * (0.5 * 3.2 * rs * rs * rs * inv);
+  grad = (dqw * J) * u_baseScale;
+
+  return 0.5 + 0.5 * t * rs;
+}
+
+/**
+ * Height above sea level in world units at a world XZ, and the surface gradient
+ * d(height)/d(worldXZ). The normal is normalize(vec3(-grad.x, 1, -grad.y)).
+ *
+ * Curvature is deliberately NOT applied here. It is a view-relative bend applied
+ * at the vertex, and folding it in would make the height field depend on where
+ * the camera is — which the shadow march and the normals both sample, and would
+ * mean a shadow that moves when you turn your head.
+ */
+float terrainSample(vec2 p, float lodCell, out vec2 grad){
+  vec2 gh;
+  float h = terrainFbmD(p, lodCell, gh);
+
+  if (u_terrainType == TERRAIN_DUNES){
+    // Dunes are a wave train transverse to the wind, not a noise field. The fBm
+    // bends the crest lines and sets how tall each dune is; the sine is the dune.
+    vec2 d = vec2(u_bearingDir.y, -u_bearingDir.x);
+    float phase  = dot(p, d) * u_duneFreq + 7.0 * h;
+    vec2  dphase = d * u_duneFreq + 7.0 * gh;
+
+    float u  = 0.5 + 0.5 * sin(phase);
+    vec2  du = 0.5 * cos(phase) * dphase;
+
+    // Asymmetry: a real dune is a long windward ramp and a short slip face at the
+    // angle of repose. Raising the crest to a power does that in one instruction.
+    float k  = mix(1.0, 3.2, u_duneAsym);
+    float us = max(u, 1e-4);
+    float s  = pow(us, k);
+    vec2  ds = k * pow(us, k - 1.0) * du;
+
+    // The envelope keeps dune height varying across the field rather than
+    // stamping one ridge repeated to the horizon.
+    float env = 0.45 + 0.55 * h;
+    float a = 0.15 + 0.5 * h;
+    float b = s * env;
+    vec2  da = 0.5 * gh;
+    vec2  db = ds * env + s * 0.55 * gh;
+    h  = mix(a, b, 0.8);
+    gh = mix(da, db, 0.8);
+  }
+  else if (u_terrainType == TERRAIN_CANYON){
+    // Canyon country is a plateau with things taken out of it, not a mountain
+    // range. Flatten the top first, then cut.
+    float om = 1.0 - h;
+    float mesa = mix(h, 1.0 - om * om * om, u_plateau);
+    float dmf  = mix(1.0, 3.0 * om * om, u_plateau);
+
+    // Channel network: ridged noise is near 1 along its zero set, which is a
+    // connected branching line — a drainage network, for free.
+    vec3  cn  = tNoised(p * (u_baseScale * 1.7) + vec2(4.2, -9.1));
+    float ch  = 1.0 - abs(cn.x);
+    vec2  dch = -sign(cn.x) * cn.yz * (u_baseScale * 1.7);
+
+    float e0 = 1.0 - u_valleyWidth;
+    float ct = clamp((ch - e0) / max(1.0 - e0, 1e-4), 0.0, 1.0);
+    float carve  = ct * ct * (3.0 - 2.0 * ct);
+    float dcarve = 6.0 * ct * (1.0 - ct) / max(1.0 - e0, 1e-4);
+
+    h  = mesa - u_valleyDepth * carve;
+    gh = dmf * gh - (u_valleyDepth * dcarve) * dch;
+  }
+
+  // Sedimentary banding. Applied after shaping, so it bands the finished landform
+  // rather than the raw noise.
+  if (u_terraces >= 0.5){
+    float n = u_terraces;
+
+    // The aliasing bound is HORIZONTAL, not vertical. What aliases is how far
+    // across the ground a riser takes to climb, and that scales with the
+    // landform's own size divided by the number of bands stacked on it. Widening
+    // the riser is not enough on its own either: smoothstep(0, 1, fr) still has a
+    // flat spot at each end, so a "fully softened" terrace is still a staircase.
+    // Fade all the way to the identity ramp, which is the un-terraced surface.
+    float featureSize = 1.0 / max(u_baseScale, 1e-9);
+    float soft = clamp(lodCell * n * 8.0 / featureSize, 0.0, 1.0);
+    float w = max(1.0 - 0.95 * u_terraceSharp, 0.02);
+
+    float x  = h * n;
+    float fr = fract(x);
+    float ct = clamp(fr / w, 0.0, 1.0);
+    float k   = mix(ct * ct * (3.0 - 2.0 * ct), fr, soft);
+    float dk  = mix(6.0 * ct * (1.0 - ct) / w, 1.0, soft);
+
+    h  = (floor(x) + k) / n;
+    gh = dk * gh;
+  }
+
+  grad = gh * u_elevation;
+  return u_seaLevel + u_elevation * h;
+}
+
+/**
+ * Height only, and a genuinely separate path rather than terrainSample with the
+ * gradient thrown away.
+ *
+ * This is the shadow march's inner loop - fourteen calls per shaded point - and
+ * it is the one place where paying for a derivative nobody reads actually shows
+ * up. No warp Jacobian, no gradient accumulation, no chain rule through the
+ * shaping: about half the work of the full sample.
+ */
+float terrainHeightAt(vec2 p, float lodCell){
+  vec2 q = p * u_baseScale;
+  if (u_warpStrength > 0.0){
+    q += vec2(
+      tNoise(q * u_warpScale + vec2(11.3, 5.7)),
+      tNoise(q * u_warpScale + vec2(-7.1, 19.2))
+    ) * u_warpStrength;
+  }
+
+  float amp = 1.0, freq = 1.0, sum = 0.0, norm = 0.0;
+  vec2  slope = vec2(0.0);
+  float wl = 1.0 / max(u_baseScale, 1e-9);
+
+  for (int i = 0; i < TERRAIN_MAX_OCTAVES; i++){
+    if (i >= u_octaves) break;
+    float limit = 2.0 * lodCell;
+    float fade = clamp(wl / max(limit, 1e-4) - 1.0, 0.0, 1.0);
+    if (fade <= 0.001) break;
+
+    vec3 n = tNoised(q * freq + float(i) * vec2(37.13, 61.91));
+    float v = n.x;
+    vec2  g = n.yz;
+    if (u_ridge > 0.0){
+      // Same octave ramp as the derivative path above - the two must agree or a
+      // height query and the rendered surface disagree by the fold amount.
+      float ridgeAmt = u_ridge * clamp(float(i) * 0.5, 0.0, 1.0);
+      float sg = sign(v);
+      float r = 1.0 - abs(v);
+      v = mix(v, r * r * 2.0 - 1.0, ridgeAmt);
+      g = mix(g, -4.0 * r * sg * g, ridgeAmt);
+    }
+    float damp = 1.0 / (1.0 + u_erosion * 1.5 * dot(slope, slope));
+    sum   += amp * damp * fade * v;
+    norm  += amp * fade;
+    slope += g * amp * damp;
+
+    amp  *= u_gain;
+    freq *= u_lacunarity;
+    wl   /= u_lacunarity;
+  }
+
+  float t = (sum / max(norm, 1e-4)) * 3.2;
+  float h = 0.5 + 0.5 * t * inversesqrt(1.0 + t * t);
+
+  if (u_terrainType == TERRAIN_DUNES){
+    vec2 d = vec2(u_bearingDir.y, -u_bearingDir.x);
+    float u = 0.5 + 0.5 * sin(dot(p, d) * u_duneFreq + 7.0 * h);
+    float s = pow(max(u, 1e-4), mix(1.0, 3.2, u_duneAsym));
+    h = mix(0.15 + 0.5 * h, s * (0.45 + 0.55 * h), 0.8);
+  }
+  else if (u_terrainType == TERRAIN_CANYON){
+    float om = 1.0 - h;
+    float mesa = mix(h, 1.0 - om * om * om, u_plateau);
+    float ch = 1.0 - abs(tNoise(p * (u_baseScale * 1.7) + vec2(4.2, -9.1)));
+    h = mesa - u_valleyDepth * smoothstep(1.0 - u_valleyWidth, 1.0, ch);
+  }
+
+  if (u_terraces >= 0.5){
+    float n = u_terraces;
+    float featureSize = 1.0 / max(u_baseScale, 1e-9);
+    float soft = clamp(lodCell * n * 8.0 / featureSize, 0.0, 1.0);
+    float w = max(1.0 - 0.95 * u_terraceSharp, 0.02);
+    float x = h * n;
+    float fr = fract(x);
+    h = (floor(x) + mix(smoothstep(0.0, w, fr), fr, soft)) / n;
+  }
+
+  return u_seaLevel + u_elevation * h;
+}
+
+vec3 terrainNormal(vec2 grad){
+  return normalize(vec3(-grad.x, 1.0, -grad.y));
+}
+`;
+/**
+ * Shading: the analytic self-shadow, the splat, and the light.
+ *
+ * The self-shadow is a ray march against the height field rather than a shadow
+ * map, and that is the decision that makes terrain shadows work at this scale. A
+ * 2048 map stretched over 25 km is 12 m per texel; a mountain's shadow edge would
+ * be a staircase you could stand in. Marching the field costs a fixed number of
+ * height evaluations and has no resolution to run out of.
+ *
+ * It is called from the VERTEX shader. Per pixel it was the single most expensive
+ * thing in the renderer — twenty height evaluations on every shaded fragment — and
+ * per vertex it is two orders of magnitude cheaper while looking almost identical,
+ * because what it produces is a soft occlusion factor that interpolates cleanly.
+ * The terminator itself stays per-pixel: `terrainLight` takes N·L from the
+ * fragment's own normal, so only the CAST shadow is interpolated.
+ */
+export const terrainShading = /* glsl */ `
+/** 1 lit, 0 shadowed, soft in between. */
+float terrainSunShadow(vec3 p, vec3 n, float lodCell, int steps){
+  if (steps < 1 || u_sunShadow <= 0.0) return 1.0;
+  // Below the horizon there is nothing to shadow; the march would also walk
+  // downhill forever.
+  if (u_sunDir.y <= 0.015) return 1.0;
+  // A surface facing away from the sun is shadowed by definition, and marching
+  // from it only finds the ground it is already part of.
+  if (dot(n, u_sunDir) <= 0.0) return 0.0;
+
+  // Lift off the surface before starting, or every sample on a steep face - a
+  // terrace riser above all - reads its own ground as an occluder and the whole
+  // wall goes black in a grid of triangles. Start ON the offset surface and
+  // compare raw heights; subtracting the bias from the height difference instead
+  // makes the first sample fail on any slope tilted a few degrees from the sun.
+  float bias = max(lodCell, u_elevation * 0.003);
+  vec3 origin = p + n * bias;
+
+  float shadowLod = (1.0 / max(u_baseScale, 1e-9)) * 0.008;
+
+  float res = 1.0;
+  float t = bias * 3.0;
+  float maxT = (u_elevation * 2.5) / max(u_sunDir.y, 0.05);
+
+  for (int i = 0; i < 48; i++){
+    if (i >= steps || t > maxT) break;
+    vec3 sp = origin + u_sunDir * t;
+    // The occluder is sampled at the SHADING lod, coarsening with distance -
+    // never at a fixed coarse lod. Testing a fine surface point against a coarse
+    // height field puts the whole valley floor in shadow, because the coarse
+    // field sits above the fine one wherever the fine one has been cut down.
+    // Sampled MUCH coarser than the surface being shaded. A shadow does not need
+    // nine octaves: what casts a visible shadow is the landform, and marching the
+    // fine field costs the same nine octaves per step for detail that is below a
+    // pixel by the time it lands. Floored against the landform's own size, so the
+    // march runs about five octaves instead of nine wherever it starts.
+    float h = terrainHeightAt(sp.xz, max(max(lodCell * 2.0, t * 0.06), shadowLod));
+    float diff = sp.y - h;
+    res = min(res, u_shadowSoftness * diff / t);
+    if (res <= 0.0) return 0.0;
+    // Geometric growth: near the surface the occluder is metres away, at the end
+    // of the march it is kilometres, and a linear step wastes every sample at one
+    // end or the other. 1.7 rather than 1.42 so twelve steps actually reach maxT -
+    // at 1.42 the march ran out around 700 m and long shadows at low sun simply
+    // did not exist, which is a quality bug that happened to look like a cheap one.
+    t = t * 1.7 + bias;
+  }
+  return saturate(res);
+}
+
+/**
+ * The shadow, faded out with distance and given a step budget that falls with it.
+ *
+ * The march is the most expensive thing left in the renderer, and past a few
+ * kilometres it is buying nothing: aerial perspective has already washed most of
+ * the contrast out of the ground, and a ridge shadow out there is a couple of
+ * pixels wide. Skipping it entirely beyond u_shadowDistance drops the outer
+ * clipmap rings - which are two thirds of the vertices - out of the march
+ * completely, and the rings in between run four steps instead of fourteen.
+ *
+ * Faded rather than cut, or the cut-off would draw a visible circle on the ground.
+ */
+float terrainShadowAt(vec3 p, vec3 n, float lodCell, float dist){
+  float fade = 1.0 - saturate(dist / max(u_shadowDistance, 1.0));
+  if (fade <= 0.002) return 1.0;
+  int steps = int(mix(4.0, float(u_shadowSteps), fade));
+  return mix(1.0, terrainSunShadow(p, n, lodCell, steps), fade);
+}
+
+/**
+ * Albedo.
+ *
+ * Rock is splatted by SLOPE, everything else by height. That ordering is the
+ * whole trick: it means a cliff is bare rock whether it is in a valley or on a
+ * summit, which is how real ground works and why height-only splatting always
+ * reads as a painted contour map.
+ */
+vec3 terrainAlbedo(vec3 wp, float h01, float slope){
+  // Large-scale variation. Without it a splat layer is one flat colour across
+  // kilometres, and the eye reads flat colour as untextured rather than as ground.
+  float macro = tNoise(wp.xz * u_macroScale) * 0.5 + 0.5;
+  float tint = 1.0 + u_macroVariation * (macro - 0.5) * 2.0;
+
+  vec3 col = mix(u_lowColor, u_midColor, smoothstep(0.05, 0.55, h01));
+
+  // Peak layer, held back on steep ground: snow does not sit on a vertical face,
+  // and without this the summit looks dipped in paint.
+  float peak = smoothstep(u_peakLevel, u_peakLevel + u_peakBlend, h01 - slope * u_peakSlopeFalloff * 0.6);
+  col = mix(col, u_peakColor, saturate(peak));
+
+  float rock = smoothstep(u_slopeRockStart, u_slopeRockEnd, slope);
+  col = mix(col, u_rockColor, rock);
+
+  return col * tint;
+}
+
+/** High-frequency bump, well below the mesh resolution, faded out with distance
+ *  so it never becomes a field of crawling pixels on the horizon. One evaluation:
+ *  the noise carries its own derivative, so the three taps a finite difference
+ *  would need are not. */
+vec3 terrainDetailNormal(vec3 n, vec3 wp, float dist){
+  float fade = 1.0 - saturate(dist * u_detailFade);
+  float amt = u_detailStrength * fade * fade;
+  if (amt <= 0.001) return n;
+  vec3 d = tNoised(wp.xz * u_detailScale);
+  return normalize(n + vec3(-d.y, 0.0, -d.z) * amt * 0.9);
+}
+
+/**
+ * Direct sun, sky fill and ground bounce.
+ *
+ * Sun irradiance is in the units skyRadiance returns, calibrated against it rather
+ * than guessed: a 0.3-albedo surface in full sun lands a little below the sky at
+ * the horizon, which is the relationship the eye reads as daylight. Set it to the
+ * clouds' SUN_RADIANCE and every ground surface clips to white.
+ */
+const float TERRAIN_SUN = 2.2;
+
+vec3 terrainLight(vec3 albedo, vec3 n, vec3 viewDir, float shadow, float sceneShadow){
+  float ndl = max(dot(n, u_sunDir), 0.0);
+  // Wrap the terminator slightly: bare ground is not a Lambertian sphere, and a
+  // hard terminator across a whole hillside reads as CG.
+  float wrap = max((dot(n, u_sunDir) + 0.2) / 1.2, 0.0);
+  float diff = mix(ndl, wrap, 0.4);
+
+  vec3 sun = u_sunColor * u_sunIntensity * TERRAIN_SUN * diff * shadow * sceneShadow;
+
+  // Sky fill from the same atmosphere the sky is drawn with, so it darkens and
+  // warms with the sun instead of freezing at a constant blue - but supplied as a
+  // uniform rather than evaluated here, since it is the same for every pixel.
+  // Whitened a little: a single-scattering zenith colour is very saturated, and
+  // at full saturation every shadowed slope - snow above all - comes out cyan.
+  vec3 fill = mix(u_skyAmbient, vec3(dot(u_skyAmbient, vec3(0.3333))), 0.4);
+  vec3 ambient = fill * (0.5 + 0.5 * n.y) * u_ambient * 1.05;
+
+  // Ground bounce, tinted by whatever the ground is. Keeps overhangs and shaded
+  // faces off pure black without flattening them the way raising ambient does.
+  vec3 bounce = u_lowColor * u_groundAmbient * (0.5 - 0.5 * n.y) * u_bounce * 1.3;
+
+  vec3 col = albedo * (sun + ambient + bounce);
+
+  // A single specular lobe. Rock barely needs it; wet sand and snow at low sun
+  // are almost entirely this.
+  if (u_specular > 0.0){
+    vec3 hv = normalize(u_sunDir - viewDir);
+    float a = max(u_roughness * u_roughness, 0.002);
+    float nh = max(dot(n, hv), 0.0);
+    float dd = nh * nh * (a - 1.0) + 1.0;
+    float d = a / max(3.14159265 * dd * dd, 1e-4);
+    col += u_sunColor * u_sunIntensity * TERRAIN_SUN * d * u_specular * shadow * sceneShadow * ndl;
+  }
+
+  return col;
+}
+
+/**
+ * Aerial perspective.
+ *
+ * The single most important line in this shader for the horizon. Ground fades
+ * into the exact sky colour it is seen through, at a rate that thins with
+ * altitude because the atmosphere does — so a distant ridge sits behind the haze
+ * and a peak above it stands clear of it, which is what tells you the scene is
+ * kilometres across rather than metres.
+ *
+ * The one remaining per-pixel skyRadiance call, and it has to be: the colour is
+ * the sky in the view direction, which is different for every fragment.
+ */
+vec3 terrainAerial(vec3 col, vec3 rd, float dist, float height){
+  float scaleHeight = exp(-max(height - u_seaLevel, 0.0) / 1400.0);
+  float f = 1.0 - exp(-dist * u_fogDensity * scaleHeight);
+  if (f < 0.002) return col;
+  return mix(col, skyRadiance(rd), saturate(f));
+}
+`;
+/** Everything a surface material needs, in include order. Requires three's
+ *  `<common>` and `skyLib` from cloudCore before it. */
+export const terrainField = [terrainUniforms, terrainNoise, terrainHeight].join('\n');
+export const terrainFull = [terrainField, terrainShading].join('\n');