@driftengine/core 4.8.3 → 4.8.5

package/src/render/lightBudget.ts

@@ -238,6 +238,31 @@ export const POINT_GLASS_TINT_TEXTURE_UNIT = SUN_GLASS_TINT_TEXTURE_UNIT + 1;
  */
 export const SURFACE_EFFECTS_TEXTURE_UNIT = POINT_GLASS_TINT_TEXTURE_UNIT + 1;
 
+/**
+ * A cloth binding's three vertex-stage textures — the binding, the particles now, the particles at
+ * rest (`clothBinding.ts`). Vertex samplers, so they count against the vertex stage's own sixteen
+ * beside the palette and the morph deltas, not the lit stage's; numbered past every fragment unit,
+ * inside the combined pool of thirty-two.
+ */
+export const CLOTH_BINDING_TEXTURE_UNIT = SURFACE_EFFECTS_TEXTURE_UNIT + 1;
+export const CLOTH_PARTICLES_TEXTURE_UNIT = CLOTH_BINDING_TEXTURE_UNIT + 1;
+export const CLOTH_REST_TEXTURE_UNIT = CLOTH_PARTICLES_TEXTURE_UNIT + 1;
+
+/**
+ * A shading model's own channels (`shaders/flat/models.ts`), the lit stage's **sixteenth** fragment
+ * sampler — exactly what WebGL2 guarantees a stage, which `textureUnitBudget.test.ts` counts from
+ * the source. Numbered past the cloth's vertex units, inside the combined pool of thirty-two.
+ */
+export const MODEL_MAP_TEXTURE_UNIT = CLOTH_REST_TEXTURE_UNIT + 1;
+
+/**
+ * The two units skin's screen-space blur reads on WebGL2 — its target and the frame's depth — past
+ * every unit a lit program binds, so spreading skin in the middle of a frame unbinds nothing the
+ * draws after it sample. WebGL2 guarantees thirty-two.
+ */
+export const SKIN_BLUR_TEXTURE_UNIT = MODEL_MAP_TEXTURE_UNIT + 1;
+export const SKIN_BLUR_DEPTH_UNIT = SKIN_BLUR_TEXTURE_UNIT + 1;
+
 /**
  * A cookie's tile, in texels a side.
  *

package/src/render/mesh.ts

@@ -57,6 +57,12 @@ const ATTR_JOINTS = 11;
 const ATTR_CHANNEL = 13;
 
 const ATTR_WEIGHTS = 12;
+/*
+ * The second four influences, at the last two locations: a skinned draw spends 11, 12 and 13 and an
+ * instanced one cannot skin, so 14 and 15 are free exactly where they are read. See skinning.ts.
+ */
+const ATTR_JOINTS2 = 14;
+const ATTR_WEIGHTS2 = 15;
 
 /**
  * One absent attribute's constant, at the width the table gave it.
@@ -136,8 +142,15 @@ export class Mesh {
   readonly bounds: Bounds = createBounds();
   /** Whether this mesh carries a rig, which decides which flat program draws it. */
   readonly isSkinned: boolean;
+  /**
+   * Whether its rig moves a vertex by eight influences rather than four, which decides whether the
+   * skinned program it takes is built with `SKIN_EIGHT` on. See `skinning.ts`.
+   */
+  readonly isSkinnedEight: boolean;
   /** Whether it has texture coordinates, without which a material's maps read one texel. */
   readonly hasUvs: boolean;
+  /** How many vertices it has, which a cloth binding is checked against. */
+  readonly vertexCount: number;
 
   /**
    * This mesh's morph deltas, or null for geometry that does not deform.
@@ -276,6 +289,7 @@ export class Mesh {
      * takes; see `WebGL2Renderer.drawMesh`.
      */
     this.isSkinned = data.joints !== undefined;
+    this.vertexCount = data.positions.length / 3;
     this.morph =
       data.morphTargets === undefined || data.morphTargetCount === undefined
         ? null
@@ -287,6 +301,15 @@ export class Mesh {
       this.attachAttribute(gl, ATTR_JOINTS, data.joints, 4);
       this.attachAttribute(gl, ATTR_WEIGHTS, data.weights, 4);
     }
+    /* The fifth to eighth influences, or zeros, which add nothing. See `isSkinnedEight`. */
+    this.isSkinnedEight = this.isSkinned && data.joints2 !== undefined;
+    if (data.joints2 === undefined || data.weights2 === undefined) {
+      this.constants.push({ location: ATTR_JOINTS2, value: ABSENT_ATTRIBUTE['joints2'] });
+      this.constants.push({ location: ATTR_WEIGHTS2, value: ABSENT_ATTRIBUTE['weights2'] });
+    } else {
+      this.attachAttribute(gl, ATTR_JOINTS2, data.joints2, 4);
+      this.attachAttribute(gl, ATTR_WEIGHTS2, data.weights2, 4);
+    }
 
     this.hasTangents = data.tangents !== undefined;
     if (data.tangents === undefined) {

package/src/render/recon/motionVectors.ts

@@ -85,9 +85,11 @@ export function objectMotion(
 }
 
 /**
- * A vertex through a skin palette: the four joints' matrices weighted and summed, then applied —
+ * A vertex through a skin palette: the joints' matrices weighted and summed, then applied —
  * `SKINNING_GLSL`'s `skinMatrix()` times the position, in model space, before the model matrix.
- * `palette` is sixteen floats a joint, column-major. Written into `out`, four values.
+ * `palette` is sixteen floats a joint, column-major. `joints` and `weights` hold four influences, or
+ * eight for a mesh with a second set (the first set then the second, as the shader reads them with
+ * `SKIN_EIGHT` on). Written into `out`, four values.
  */
 export function skinVertex(
   palette: ArrayLike<number>,
@@ -103,7 +105,8 @@ export function skinVertex(
   out[1] = 0;
   out[2] = 0;
   out[3] = 0;
-  for (let influence = 0; influence < 4; influence += 1) {
+  const influences = Math.min(joints.length, weights.length, 8);
+  for (let influence = 0; influence < influences; influence += 1) {
     const weight = weights[influence] as number;
     if (weight === 0) continue;
     const at = (joints[influence] as number) * 16;

package/src/render/renderQuality.ts

@@ -46,6 +46,9 @@ export type WaterReflectionFilterTaps = 1 | 5 | 9;
 /** How light through glass is coloured: see `RenderQuality.glassShadows`. */
 export type GlassShadows = 'full' | 'half' | 'off';
 
+/** How light scattered beneath skin is drawn: see `RenderQuality.skinScattering`. */
+export type SkinScattering = 'pre-integrated' | 'screen-space';
+
 export interface RenderQuality {
   /**
    * The transfer curve applied at the end of every shaded pass.
@@ -210,6 +213,24 @@ export interface RenderQuality {
    * lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
    */
   readonly glassShadows: GlassShadows;
+  /**
+   * How light that scatters beneath skin is drawn, for a material whose model is `skinModel`.
+   *
+   * **`'pre-integrated'`, the default**: the lit stage's fit alone — a terminator softened and
+   * reddened by the surface's curvature, light through thin parts, a penumbra each channel crosses
+   * as far as it travels — at no cost beyond the skin pipeline itself. **`'screen-space'`** adds
+   * Burley's blur in the picture as well: a skin draw writes its diffuse to a target of its own (it
+   * is drawn twice to do so), which is spread across the pixels its scatter distance covers and
+   * added back before anything blended is drawn, so light crosses a shadow's edge and a nostril's
+   * rim in the picture rather than in a fit. See `skinBlur.ts`.
+   *
+   * Construction-time: two half-float targets the size of the frame, and a multisampled one under
+   * multisampling, made at the first skin draw. It needs the composite (`screenEffects`), which is
+   * where the frame is still linear light to add to; without one, skin is pre-integrated and the
+   * renderer says so once. What would make the default wrong is a close-up face that reads as wax
+   * at a shadow's edge — that is what the blur is for.
+   */
+  readonly skinScattering: SkinScattering;
   /** Horizontal world-space reach over which a directional shadow dissolves. */
   readonly directionalShadowMaxDistance: number;
   /** Maximum horizontal projection per vertical metre before low-angle shadows vanish. */
@@ -920,6 +941,7 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
   lightVolumeSamples: 32,
   directionalShadowDepthLayers: 2,
   glassShadows: 'full',
+  skinScattering: 'pre-integrated',
   directionalShadowMaxDistance: 6,
   directionalShadowMaxSlope: 3,
   pointShadowRebakeDistance: 0.001,
@@ -1084,6 +1106,7 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
     directionalShadowDepthLayers:
       options.directionalShadowDepthLayers ?? DEFAULT_RENDER_QUALITY.directionalShadowDepthLayers,
     glassShadows: options.glassShadows ?? DEFAULT_RENDER_QUALITY.glassShadows,
+    skinScattering: options.skinScattering ?? DEFAULT_RENDER_QUALITY.skinScattering,
     directionalShadowMaxDistance:
       options.directionalShadowMaxDistance ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxDistance,
     directionalShadowMaxSlope:
@@ -1238,6 +1261,11 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
       `RenderQuality.glassShadows must be 'full', 'half' or 'off', got ${String(quality.glassShadows)}`,
     );
   }
+  if (quality.skinScattering !== 'pre-integrated' && quality.skinScattering !== 'screen-space') {
+    throw new Error(
+      `RenderQuality.skinScattering must be 'pre-integrated' or 'screen-space', got ${String(quality.skinScattering)}`,
+    );
+  }
   if (quality.plumeNoiseOctaves > 3) {
     throw new Error(
       `RenderQuality.plumeNoiseOctaves must be <= 3, got ${quality.plumeNoiseOctaves}`,

package/src/render/rendererHarness.ts

@@ -104,6 +104,10 @@ export function recordingGl(
     NONE: 0,
     ALWAYS: 0x0207,
     LESS: 0x0201,
+    EQUAL: 0x0202,
+    GREATER: 0x0204,
+    GEQUAL: 0x0206,
+    LEQUAL: 0x0203,
     TEXTURE_MIN_FILTER: 0x2801,
     TEXTURE_MAG_FILTER: 0x2800,
     TEXTURE_WRAP_S: 0x2802,

package/src/render/sceneTarget.ts

@@ -497,6 +497,27 @@ export class SceneTarget {
    * must reject it in the same place or the accumulation and the revealage cover different
    * fragments.
    */
+  /**
+   * The depth the frame draws against, for a second framebuffer to share: skin's diffuse half,
+   * which tests against it and writes none. The multisampled renderbuffer where the frame is
+   * multisampled, the texture otherwise, with the size and sample count a colour beside it needs.
+   */
+  sharedDepth(): {
+    texture: WebGLTexture | null;
+    renderbuffer: WebGLRenderbuffer | null;
+    samples: number;
+    width: number;
+    height: number;
+  } {
+    return {
+      texture: this.msaaDepth === null ? this.depth : null,
+      renderbuffer: this.msaaDepth,
+      samples: this.samples,
+      width: this.width,
+      height: this.height,
+    };
+  }
+
   depthAttachment(): WebGLTexture | null {
     return this.depth;
   }

package/src/render/shaders/clothBinding.ts

@@ -0,0 +1,81 @@
+/**
+ * The vertex-stage cloth binding: a skinned vertex moved toward the cloth simulation's triangle it
+ * is bound to, by a weight painted per vertex — the GLSL of `clothPlacement.ts`, line for line.
+ *
+ * **Textures read by vertex index, not attributes**, for the reason morph targets are: the skinned
+ * variants already use all sixteen attribute locations once eight influences are in. Three
+ * textures, each wrapped onto rows at its own width (read back with `textureSize`, so no uniform
+ * joins the vertex block and no shared field moves):
+ *
+ * - **the binding**, two texels a render vertex: the three particle indices and the weight, then
+ *   the barycentric (u, v) for the second and third particle and the offset along the normal;
+ * - **the particles now**, one texel a particle, world space — the simulation's output;
+ * - **the particles at rest**, one texel a particle, model space — the rest frames are built from
+ *   these, so a vertex's own bind-pose normal turns as its triangle has turned.
+ *
+ * **A pipeline constant, not a permutation**, as `SKIN_EIGHT` is: declared in the skinned variants
+ * and folded away where a draw binds no cloth. The textures are bound either way, to stand-ins
+ * where there is no cloth.
+ */
+export const CLOTH_BINDING_GLSL = `
+/** Whether this pipeline places vertices by a cloth binding. */
+const bool CLOTH_BOUND = false; // wgsl:override
+uniform highp sampler2D uClothBinding;
+uniform highp sampler2D uClothParticles;
+uniform highp sampler2D uClothRest;
+
+/** Texel i of a texture wrapped onto rows of the given width. */
+ivec2 clothTexel(int i, int width) {
+  return ivec2(i % width, i / width);
+}
+
+/** A triangle's frame: its first edge, the normal crossed with it, and its normal. */
+mat3 clothFrame(vec3 a, vec3 b, vec3 c) {
+  vec3 edge = b - a;
+  vec3 n = normalize(cross(edge, c - a));
+  vec3 t = normalize(edge);
+  return mat3(t, cross(n, t), n);
+}
+
+/**
+ * Where this vertex's triangle puts it, the turn its normal takes, and how far it follows (the
+ * painted weight: 0 skinned, 1 cloth). One particle named three times is a vertex bound to that
+ * particle alone: on it, with no turn.
+ */
+float clothPlace(out vec3 position, out mat3 turn) {
+  int bindingWidth = textureSize(uClothBinding, 0).x;
+  int particleWidth = textureSize(uClothParticles, 0).x;
+  int restWidth = textureSize(uClothRest, 0).x;
+  vec4 indices = texelFetch(uClothBinding, clothTexel(gl_VertexID * 2, bindingWidth), 0);
+  vec4 at = texelFetch(uClothBinding, clothTexel(gl_VertexID * 2 + 1, bindingWidth), 0);
+  int a = int(indices.x);
+  int b = int(indices.y);
+  int c = int(indices.z);
+  vec3 pa = texelFetch(uClothParticles, clothTexel(a, particleWidth), 0).xyz;
+  if (a == b && b == c) {
+    position = pa;
+    turn = mat3(1.0);
+    return indices.w;
+  }
+  vec3 pb = texelFetch(uClothParticles, clothTexel(b, particleWidth), 0).xyz;
+  vec3 pc = texelFetch(uClothParticles, clothTexel(c, particleWidth), 0).xyz;
+  mat3 now = clothFrame(pa, pb, pc);
+  mat3 rest = clothFrame(
+    texelFetch(uClothRest, clothTexel(a, restWidth), 0).xyz,
+    texelFetch(uClothRest, clothTexel(b, restWidth), 0).xyz,
+    texelFetch(uClothRest, clothTexel(c, restWidth), 0).xyz
+  );
+  position = pa * (1.0 - at.x - at.y) + pb * at.x + pc * at.y + now[2] * at.z;
+  turn = now * transpose(rest);
+  return indices.w;
+}
+`;
+
+/** A skinned vertex stage with the cloth binding on: the same source, the constant flipped. */
+export function clothBound(source: string): string {
+  const off = 'const bool CLOTH_BOUND = false;';
+  if (!source.includes(off)) {
+    throw new Error('clothBound: this vertex stage declares no CLOTH_BOUND constant');
+  }
+  return source.replace(off, 'const bool CLOTH_BOUND = true;');
+}

package/src/render/shaders/depth.ts

@@ -1,7 +1,9 @@
 import { resolveConditionals } from './conditionals.ts';
 import { SUN_STATIC_LAYER } from '../shadowMap.ts';
 import { CUTOUT_COVERAGE_GLSL } from './cutoutCoverage.ts';
+import { CUTOUT_DITHER_GLSL } from '../cutoutDither.ts';
 import { SKINNING_GLSL } from './skinning.ts';
+import { CLOTH_BINDING_GLSL } from './clothBinding.ts';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.ts';
 
 /**
@@ -21,6 +23,11 @@ const DEPTH_VERT_SOURCE = `#version 300 es
 layout(location = 0) in vec3 aPosition;
 #if SKINNED
 ${SKINNING_GLSL}
+/* Not in the glass-tint caster: a garment is not glass, and its layout keeps its bindings. */
+#if GLASS
+#else
+${CLOTH_BINDING_GLSL}
+#endif
 #endif
 
 uniform mat4 uLightViewProj;
@@ -67,14 +74,15 @@ ${CHANNEL_BEND}
 layout(location = 5) in vec3 aUv;
 uniform vec2 uUvScale;
 uniform vec2 uUvOffset;
-uniform float uAlphaCutout;
+/* x the cutoff, y 1 for a dithered edge: see the cutout fragment stages below. */
+uniform vec2 uAlphaCutout;
 #endif
 
 out vec4 vLightPosition;
 #if CUTOUT
 /* The texture coordinate and, in z, the texture-array layer the face wears. */
 out vec3 vUv;
-flat out float vAlphaCutout;
+flat out vec2 vAlphaCutout;
 #endif
 #if GLASS
 /* Where on the pane this is, for the tint's own normal and its angle to the light. Last, so the
@@ -101,6 +109,18 @@ void main() {
   vec3 bent = world.xyz;
 #else
   vec3 bent = channelBend(world.xyz, aChannel.x);
+#endif
+#if SKINNED
+#if GLASS
+#else
+  /* Toward the cloth exactly as the colour pass moves it, or the shadow parts from the garment. */
+  if (CLOTH_BOUND) {
+    vec3 clothPosition;
+    mat3 turn;
+    float follow = clothPlace(clothPosition, turn);
+    bent = mix(bent, clothPosition, follow);
+  }
+#endif
 #endif
   vLightPosition = uLightViewProj * vec4(bent, world.w);
   gl_Position = vLightPosition;
@@ -199,12 +219,13 @@ export const DEPTH_CUTOUT_FRAG = `#version 300 es
 precision highp float;
 in vec4 vLightPosition;
 in vec3 vUv;
-flat in float vAlphaCutout;
+flat in vec2 vAlphaCutout;
 
 uniform highp sampler2DArray uPreviousShadowMap;
 uniform int uPeelShadowLayer;
 uniform highp sampler2DArray uCutoutMap;
 ${CUTOUT_COVERAGE_GLSL}
+${CUTOUT_DITHER_GLSL}
 void main() {
   /* Credited for its mip level as the surface's own test is, so a leaf casts the shape it draws. */
   vec3 at = vec3(vUv.xy, floor(vUv.z + 0.5));
@@ -215,7 +236,16 @@ void main() {
     float previousDepth = textureLod(uPreviousShadowMap, vec3(uv, ${SUN_STATIC_LAYER}.0), 0.0).r;
     if (gl_FragCoord.z <= previousDepth + 0.00001) discard;
   }
-  if (alpha < vAlphaCutout) discard;
+  /*
+   * A dithered edge casts the share it covers, with a pattern that does not move: a shadow map has
+   * no temporal resolve of its own and a static layer keeps whatever it was drawn with, so a moving
+   * pattern would shimmer there. The map's filter averages it into a soft edge.
+   */
+  if (vAlphaCutout.y > 0.5) {
+    if (!cutoutKeeps(cutoutShare(alpha, vAlphaCutout.x), gl_FragCoord.xy, 0.0)) discard;
+  } else if (alpha < vAlphaCutout.x) {
+    discard;
+  }
 }
 `;
 
@@ -293,13 +323,14 @@ export const GLASS_TINT_CUTOUT_FRAG = `#version 300 es
 precision highp float;
 in vec4 vLightPosition;
 in vec3 vUv;
-flat in float vAlphaCutout;
+flat in vec2 vAlphaCutout;
 in vec3 vGlassWorld;
 
 uniform vec4 uGlassPane;
 uniform vec4 uGlassLight;
 uniform highp sampler2DArray uCutoutMap;
 ${CUTOUT_COVERAGE_GLSL}
+${CUTOUT_DITHER_GLSL}
 out vec4 outTint;
 
 void main() {
@@ -307,6 +338,11 @@ void main() {
   vec3 at = vec3(vUv.xy, floor(vUv.z + 0.5));
   float alpha = cutoutAlpha(texture(uCutoutMap, at).a, vUv.xy * vec2(textureSize(uCutoutMap, 0).xy));
 ${GLASS_TINT_BODY}
-  if (alpha < vAlphaCutout) discard;
+  /* The depth cutout's own test, so the colour lands exactly where the depth does. */
+  if (vAlphaCutout.y > 0.5) {
+    if (!cutoutKeeps(cutoutShare(alpha, vAlphaCutout.x), gl_FragCoord.xy, 0.0)) discard;
+  } else if (alpha < vAlphaCutout.x) {
+    discard;
+  }
 }
 `;

package/src/render/shaders/flat/anisotropic.ts

@@ -0,0 +1,68 @@
+/**
+ * The anisotropic model in GLSL: GGX stretched along a direction in the surface, after glTF's
+ * `KHR_materials_anisotropy` — `anisotropicLobe.ts` is the same arithmetic, and its tests hold it to
+ * the standard lobe at strength 0 and to the widths' ratio at its half maximum.
+ *
+ * **The direction** is the tangent frame's, turned by the material's rotation, and by the model
+ * map's red and green where one is bound (a direction encoded −1 to 1, glTF's packing), its blue
+ * scaling the strength. **The environment** is reflected about a normal bent toward the stretch, as
+ * Filament and three.js do: a streak of sky across a brushed disc rather than a round spot, at the
+ * cost of a reflection that is not the exact anisotropic integral.
+ *
+ * Lamps widen both of the lobe's widths by the source's angle, as `sphereLobe` widens the standard
+ * lobe, with the energy kept; at strength 0 that is `sphereLobe` exactly.
+ */
+export const ANISOTROPIC_GLSL = /* glsl */ `
+/* The stretch's frame and strength, gathered once with the surface. */
+vec3 aAlong;
+vec3 aAcross;
+float aStrength;
+
+void anisotropicSurface() {
+  vec2 direction = vec2(1.0, 0.0);
+  float strength = uModelParams[0].x;
+  if (uModelParams[1].w > 0.0) {
+    vec2 mapped = mMap.rg * 2.0 - 1.0;
+    direction = dot(mapped, mapped) > 1e-8 ? normalize(mapped) : direction;
+    strength *= mMap.b;
+  }
+  vec2 turned = vec2(
+    direction.x * uModelParams[0].y - direction.y * uModelParams[0].z,
+    direction.x * uModelParams[0].z + direction.y * uModelParams[0].y
+  );
+  aAlong = normalize(mTangent * turned.x + mBitangent * turned.y);
+  aAcross = cross(mNormal, aAlong);
+  aStrength = strength;
+}
+
+/** The stretched lobe at a half vector, 1 at the mirror direction: anisotropicLobe.ts. */
+float anisotropicLobe(vec3 h, float sourceRadius, float dist) {
+  float alpha = max(mRoughness * mRoughness, MIN_LOBE_ALPHA);
+  float alongWidth = alpha + (1.0 - alpha) * aStrength * aStrength;
+  float grow = sourceRadius / max(2.0 * dist, 1e-3);
+  float alongWide = clamp(alongWidth + grow, alongWidth, 1.0);
+  float acrossWide = clamp(alpha + grow, alpha, 1.0);
+  float energy = (alongWidth / alongWide) * (alpha / acrossWide);
+  float x = dot(aAlong, h) / alongWide;
+  float y = dot(aAcross, h) / acrossWide;
+  float z = dot(mNormal, h);
+  float d = x * x + y * y + z * z;
+  return energy / max(d * d, 1e-8);
+}
+
+void anisotropicLight(vec3 l, float sourceRadius, float dist) {
+  float ndl = max(dot(mNormal, l), 0.0);
+  vec3 h = normalize(l + mToEye);
+  vec3 tint = mix(mSpecColor, vec3(1.0), pow(1.0 - max(dot(mToEye, h), 0.0), 5.0) * mMetal);
+  mDiffuse = mAlbedo * ndl * (1.0 - mMetal);
+  mSpecular = ndl > 0.0 ? tint * anisotropicLobe(h, sourceRadius, dist) : vec3(0.0);
+}
+
+/* The environment's normal, bent toward the stretch by its strength and the surface's roughness. */
+vec3 anisotropicReflectNormal(vec3 n) {
+  vec3 across = cross(aAcross, mToEye);
+  vec3 bent = cross(across, aAcross);
+  float bend = aStrength * clamp(5.0 * mRoughness, 0.0, 1.0);
+  return normalize(mix(n, bent, bend));
+}
+`;

package/src/render/shaders/flat/eye.ts

@@ -0,0 +1,82 @@
+/**
+ * The eye model in GLSL: `eyeRefraction.ts` is the refraction's arithmetic, and its tests hold it
+ * to no shift head-on, the refracted crossing at 30°, a bounded shift edge-on and the map-less iris.
+ *
+ * **The iris is moved before any map is read** (`modelSurfaceAt`), by how far the eye's ray crosses
+ * the iris plane after the cornea bends it, so the whole iris — colour, relief, the model's own
+ * channels — moves as one. The crossing is turned into texture coordinates by the tangent frame and
+ * by how many of them a metre spans here, which the screen's derivatives say: so it is in uniform
+ * control flow, as `modelSurfaceAt` is. **What it gives up** is an anisotropic mapping — a texture
+ * stretched one way more than the other moves by the average of the two.
+ *
+ * **The model map**: red is the iris (1 inside), green the cornea's height above the iris plane as a
+ * share of `irisDepth`. Without one, the iris is a disc of `irisRadius` about the texture's centre
+ * and the height is `irisDepth` throughout.
+ *
+ * **Lit as an eye is**: the iris by a normal mirrored about the axis — concave where the cornea is
+ * convex, so light pools on the side away from it — and the sclera by the surface's own; and over
+ * both, the cornea's highlight, normalised GGX at `corneaRoughness` with the Fresnel of index 1.336,
+ * in lamp units like skin's. The environment is reflected at the cornea's split-sum share.
+ */
+import { CORNEA_F0, EYE_MIN_DESCENT } from '../../eyeRefraction.ts';
+
+export const EYE_GLSL = /* glsl */ `
+const float CORNEA_F0 = ${CORNEA_F0.toFixed(9)};
+const float EYE_MIN_DESCENT = ${EYE_MIN_DESCENT.toFixed(4)};
+
+/* How much of this texel is iris, gathered with the surface. */
+float eIris;
+
+/** Where the iris is without a map: a disc of the model's radius about the centre, a soft limbus. */
+float eyeIrisDisc(vec2 uv) {
+  float r = length(uv - 0.5);
+  return 1.0 - smoothstep(uModelParams[0].x - 0.01, uModelParams[0].x + 0.01, r);
+}
+
+/** The iris's texture coordinate, moved by the cornea: \`eyeRefraction.ts\`. Before any map is read. */
+vec3 eyeRefract(vec3 at) {
+  vec3 n = normalize(vNormal);
+  vec3 axis = uModelParams[1].xyz;
+  vec4 map = texture(uModelMap, at);
+  bool mapped = uModelParams[1].w > 0.0;
+  float iris = mapped ? map.r : eyeIrisDisc(at.xy);
+  float height = uModelParams[0].y * (mapped ? map.g : 1.0);
+  vec3 ray = refract(-normalize(uCameraPos - vWorldPos), n, 1.0 / uModelParams[0].z);
+  float descent = max(-dot(ray, axis), EYE_MIN_DESCENT);
+  vec3 travel = ray * (height / descent);
+  vec3 across = travel - axis * dot(travel, axis);
+  mat3 frame = tangentFrame(n, vWorldPos, vUv.xy, vTangent, vHasTangents);
+  /* How many texture coordinates a metre spans here, from the screen's two derivatives. */
+  float perMetre = length(fwidth(vUv.xy)) / max(length(fwidth(vWorldPos)), 1e-9);
+  vec2 shift = vec2(dot(across, frame[0]), dot(across, frame[1])) * (perMetre * iris);
+  return vec3(at.xy + shift, at.z);
+}
+
+void eyeSurface(vec3 at) {
+  eIris = uModelParams[1].w > 0.0 ? mMap.r : eyeIrisDisc(at.xy);
+  mRoughness = uModelParams[0].w;
+}
+
+void eyeLight(vec3 l, float sourceRadius, float dist) {
+  vec3 axis = uModelParams[1].xyz;
+  /* The iris is concave where the cornea over it is convex: the surface's normal mirrored about the axis. */
+  vec3 irisNormal = normalize(2.0 * dot(mNormal, axis) * axis - mNormal);
+  vec3 lit = normalize(mix(mNormal, irisNormal, eIris));
+  mDiffuse = mAlbedo * max(dot(lit, l), 0.0) * (1.0 - mMetal);
+
+  float ndl = max(dot(mNormal, l), 0.0);
+  vec3 h = normalize(l + mToEye);
+  float ndh = max(dot(mNormal, h), 0.0);
+  float ndv = max(dot(mNormal, mToEye), 1e-4);
+  float grow = sourceRadius / max(2.0 * dist, 1e-3);
+  float alpha = min(max(mRoughness * mRoughness, MIN_LOBE_ALPHA) + grow, 1.0);
+  float f = CORNEA_F0 + (1.0 - CORNEA_F0) * pow(1.0 - max(dot(mToEye, h), 0.0), 5.0);
+  mSpecular = vec3(3.14159265 * f * smithMasking(ndl, ndv, alpha) * ggxLobe(ndh, alpha) * ndl);
+}
+
+/** The environment at the cornea's Fresnel, by the split sum's share at its own roughness. */
+float eyeReflectance() {
+  vec2 dfg = envBrdfApprox(max(dot(mNormal, mToEye), 0.0), uModelParams[0].w);
+  return CORNEA_F0 * dfg.x + dfg.y;
+}
+`;

package/src/render/shaders/flat/hair.ts

@@ -0,0 +1,102 @@
+/**
+ * The hair model in GLSL: `hairLobes.ts` is the same arithmetic, and its tests hold the lobes to
+ * their tilted peaks, the transmitted lobe to the backlight, the sum to what a white strand
+ * receives, and every term to a finite answer where the geometry degenerates.
+ *
+ * **The strand is the tangent, root to tip.** The model map's green turns each strand's tilt by up
+ * to half of it either way (0.5 is none) and its blue is occlusion, which the sky, DriftLight and
+ * the environment's reflection take and the lamps do not — their shadows are theirs to cast. The
+ * red is not read: a colour from root to tip is the albedo map's to carry.
+ *
+ * **The environment** is the reflected lobe's: mirrored about a normal turned toward the eye across
+ * the strand, which is the cone R lies on, at the strand's own Fresnel — the lobe integrates to it
+ * over every direction of arrival. **What it gives up** is the two transmitted lobes against the
+ * sky, which a head of hair lit from behind by an open sky would show as a rim; the lamps carry
+ * them.
+ */
+import { HAIR_F0, HAIR_MIN_BETA, HAIR_SCATTER_SPHERE } from '../../hairLobes.ts';
+
+export const HAIR_GLSL = /* glsl */ `
+const float HAIR_F0 = ${HAIR_F0.toFixed(9)};
+const float HAIR_MIN_BETA = ${HAIR_MIN_BETA.toFixed(3)};
+const float HAIR_SCATTER_SPHERE = ${HAIR_SCATTER_SPHERE.toFixed(3)};
+
+/* This texel's tilt, gathered once with the surface. */
+float hShift;
+
+void hairSurface() {
+  hShift = uModelParams[0].x * (0.5 + mMap.g);
+}
+
+/** A longitudinal lobe: a normalised Gaussian of width \`beta\` at \`x\` from its centre. */
+float hairLongitudinal(float beta, float x) {
+  return exp(-0.5 * x * x / (beta * beta)) / (2.5066283 * beta);
+}
+
+float hairFresnel(float cosine) {
+  float c = 1.0 - clamp(cosine, 0.0, 1.0);
+  return HAIR_F0 + (1.0 - HAIR_F0) * c * c * c * c * c;
+}
+
+/** The normal turned toward the eye across the strand: the scatter's and the environment's. */
+vec3 hairAcross() {
+  vec3 across = mToEye - mTangent * dot(mTangent, mToEye);
+  float length2 = dot(across, across);
+  return length2 > 1e-8 ? across * inversesqrt(length2) : mNormal;
+}
+
+void hairLight(vec3 l, float sourceRadius, float dist) {
+  vec3 t = mTangent;
+  float sinI = clamp(dot(t, l), -1.0, 1.0);
+  float sinO = clamp(dot(t, mToEye), -1.0, 1.0);
+  /* Floored for the half angle's limit, whose single-precision cosine is negative: hairLobes.ts. */
+  float cosD = max(cos(0.5 * abs(asin(sinO) - asin(sinI))), 1e-3);
+  vec3 lp = l - sinI * t;
+  vec3 vp = mToEye - sinO * t;
+  float cosPhi = dot(lp, vp) * inversesqrt(dot(lp, lp) * dot(vp, vp) + 1e-4);
+  float cosHalfPhi = sqrt(clamp(0.5 + 0.5 * cosPhi, 0.0, 1.0));
+  float beta = max(mRoughness * mRoughness, HAIR_MIN_BETA);
+  float grow = sourceRadius / max(2.0 * dist, 1e-3);
+  float x = sinI + sinO;
+
+  float r = hairLongitudinal(beta + grow, x + 2.0 * hShift) * 0.25 * cosHalfPhi
+    * hairFresnel(sqrt(clamp(0.5 + 0.5 * dot(l, mToEye), 0.0, 1.0)));
+
+  float a = 1.0 / (1.19 / cosD + 0.36 * cosD);
+  float h = cosHalfPhi * (1.0 + a * (0.6 - 0.8 * cosPhi));
+  float fTT = hairFresnel(cosD * sqrt(clamp(1.0 - h * h, 0.0, 1.0)));
+  float tt = hairLongitudinal(0.5 * beta + grow, x - hShift) * exp(-3.65 * cosPhi - 3.98)
+    * (1.0 - fTT) * (1.0 - fTT) * uModelParams[0].z;
+  float ttPower = 0.5 * sqrt(clamp(1.0 - h * h * a * a, 0.0, 1.0)) / cosD;
+
+  float fTRT = hairFresnel(0.5 * cosD);
+  float trt = hairLongitudinal(2.0 * beta + grow, x - 3.0 * hShift) * exp(17.0 * cosPhi - 16.78)
+    * (1.0 - fTRT) * (1.0 - fTRT) * fTRT;
+
+  /* Above zero, so pow never takes the logarithm of nothing: hairLobes.ts. */
+  vec3 fibre = max(mAlbedo, vec3(1e-4));
+  /* π: the published lobes are per unit irradiance, and a lamp here is π of that. */
+  mSpecular = 3.14159265 * (vec3(r) + tt * pow(fibre, vec3(ttPower)) + trt * pow(fibre, vec3(0.8 / cosD)));
+  float wrapped = clamp((dot(hairAcross(), l) + 1.0) * 0.25, 0.0, 1.0);
+  mDiffuse = sqrt(mAlbedo) * uModelParams[0].y * mix(wrapped, 1.0 - abs(sinI), 0.33);
+}
+
+/**
+ * A shadow on the scatter: light that reaches a strand in another's shadow has passed through
+ * hair to get there, so a penumbra deepens toward the fibre's own hue.
+ */
+vec3 hairShade(float shadow) {
+  vec3 hue = mAlbedo / max(dot(mAlbedo, vec3(0.2126, 0.7152, 0.0722)), 1e-4);
+  return shadow * pow(max(hue, vec3(1e-4)), vec3(1.0 - shadow));
+}
+
+/** Light from every side, through the scatter term: \`HAIR_SCATTER_SPHERE\` says why that number. */
+vec3 hairAround(vec3 light) {
+  return sqrt(mAlbedo) * (uModelParams[0].y * HAIR_SCATTER_SPHERE * mMap.b) * light;
+}
+
+/** The reflected lobe's share of the environment: its Fresnel, which is what it integrates to. */
+float hairReflectance() {
+  return hairFresnel(dot(hairAcross(), mToEye)) * mMap.b;
+}
+`;