@driftengine/core 4.8.3 → 4.8.4

package/src/render/compressedSource.ts

@@ -0,0 +1,198 @@
+/**
+ * A block-compressed image a caller hands to `createSurfaceTexture`, and the one decision about it
+ * both backends share: whether this device takes it as blocks.
+ *
+ * **Uploaded as it is, or not at all.** A BC texture costs a byte a texel on the GPU (BC7) or half
+ * of one (BC1) against four for RGBA, and keeps the mip chain its author built rather than one a box
+ * filter makes. A device that cannot sample the format — most phones, which have ASTC and ETC2 —
+ * gets nothing from the blocks, and the engine does not decode them here: core ships no decoder.
+ * The loader in `@driftengine/assets` asks `uploadsCompressed` first and decodes at load where the
+ * answer is no; a caller handing a source this device cannot take is refused by name.
+ *
+ * Backend-neutral, because both backends must agree on what they accept before either touches a
+ * device. `BlockFormat` is the same union `@driftengine/drft` names `BcFormat`; core imports nothing
+ * from that package, and a format added there without a twin here fails where the loader passes one
+ * to the other, at compile time.
+ */
+
+/** BC1 to BC5 and BC7. BC6H and the signed forms are not among them. */
+export type BlockFormat = 'bc1' | 'bc2' | 'bc3' | 'bc4' | 'bc5' | 'bc7';
+
+/** A format as a device offers it: the colour space is part of the name, as WebGPU's are. */
+export type CompressedTextureFormat =
+  'bc1' | 'bc1-srgb' | 'bc2' | 'bc2-srgb' | 'bc3' | 'bc3-srgb' | 'bc4' | 'bc5' | 'bc7' | 'bc7-srgb';
+
+/** Block-compressed texels with their stored mip chain, level 0 first. */
+export interface CompressedTextureSource {
+  readonly format: BlockFormat;
+  readonly width: number;
+  readonly height: number;
+  readonly levels: readonly Uint8Array[];
+}
+
+/** What `createSurfaceTexture` takes: an image, or blocks. */
+export type SurfaceSource = TexImageSource | CompressedTextureSource;
+
+/**
+ * The layers as blocks, or null where every one is an image. An array mixing the two is refused:
+ * one GPU texture has one format.
+ */
+export function compressedLayers(
+  sources: readonly SurfaceSource[],
+): readonly CompressedTextureSource[] | null {
+  let count = 0;
+  for (const source of sources) if (isCompressedSource(source)) count++;
+  if (count === 0) return null;
+  if (count !== sources.length) {
+    throw new Error(
+      'createSurfaceTextureArray: some layers are blocks and some are images, and one texture has ' +
+        'one format. Decode the blocks, or build the array from blocks alone.',
+    );
+  }
+  return sources as readonly CompressedTextureSource[];
+}
+
+/** Bytes per 4x4 block. */
+export const BLOCK_BYTES: Readonly<Record<BlockFormat, number>> = {
+  bc1: 8,
+  bc2: 16,
+  bc3: 16,
+  bc4: 8,
+  bc5: 16,
+  bc7: 16,
+};
+
+/** Whether `source` is a compressed source rather than an image. */
+export function isCompressedSource(source: unknown): source is CompressedTextureSource {
+  const candidate = source as { format?: unknown; levels?: unknown } | null;
+  return (
+    typeof candidate === 'object' &&
+    candidate !== null &&
+    typeof candidate.format === 'string' &&
+    Array.isArray(candidate.levels)
+  );
+}
+
+/** The format a device would have to offer, or null for one with no sRGB form. */
+export function compressedFormatName(
+  format: BlockFormat,
+  srgb: boolean,
+): CompressedTextureFormat | null {
+  if (!srgb) return format;
+  return format === 'bc4' || format === 'bc5' ? null : `${format}-srgb`;
+}
+
+/**
+ * Whether a `width` by `height` source in `format` uploads as blocks on a device offering
+ * `available`. Level 0 must be whole blocks each way: WebGPU refuses any other size for a BC
+ * texture, and WebGL2's S3TC extension says the same, so a 6x6 image is decoded rather than
+ * refused. What would make that wrong is a device that pads; none is relied on here.
+ */
+export function uploadsCompressed(
+  format: BlockFormat,
+  srgb: boolean,
+  width: number,
+  height: number,
+  available: readonly CompressedTextureFormat[],
+): boolean {
+  const name = compressedFormatName(format, srgb);
+  return name !== null && width % 4 === 0 && height % 4 === 0 && available.includes(name);
+}
+
+/** The bytes level `level` of a `width` by `height` image takes: whole blocks, one at least. */
+function levelBytes(format: BlockFormat, width: number, height: number, level: number): number {
+  const w = Math.max(1, width >> level);
+  const h = Math.max(1, height >> level);
+  return Math.ceil(w / 4) * Math.ceil(h / 4) * BLOCK_BYTES[format];
+}
+
+/**
+ * How many levels the layers carry, after checking each is the size its place requires and every
+ * layer matches the first. Refuses by name: a short level uploaded anyway is a device error at
+ * submit, which on WebGPU is a frame that draws nothing and says so somewhere else.
+ */
+export function compressedLevels(layers: readonly CompressedTextureSource[]): number {
+  const first = layers[0];
+  if (first === undefined)
+    throw new Error('createSurfaceTexture: an array needs at least one image');
+  const { format, width, height } = first;
+  const count = first.levels.length;
+  const most = Math.floor(Math.log2(Math.max(1, width, height))) + 1;
+  if (count < 1 || count > most) {
+    throw new Error(
+      `createSurfaceTexture: ${count} levels for a ${width}x${height} image, which has at least 1 ` +
+        `and at most ${most}`,
+    );
+  }
+  for (let layer = 0; layer < layers.length; layer++) {
+    const source = layers[layer] as CompressedTextureSource;
+    if (
+      source.format !== format ||
+      source.width !== width ||
+      source.height !== height ||
+      source.levels.length !== count
+    ) {
+      throw new Error(
+        `createSurfaceTexture: layer ${layer} is ${source.width}x${source.height} ` +
+          `${source.format.toUpperCase()} with ${source.levels.length} levels, and layer 0 is ` +
+          `${width}x${height} ${format.toUpperCase()} with ${count}. Every layer of an array is one ` +
+          'format, size and chain on the device.',
+      );
+    }
+    for (let level = 0; level < count; level++) {
+      const want = levelBytes(format, width, height, level);
+      const got = (source.levels[level] as Uint8Array).length;
+      if (got !== want) {
+        throw new Error(
+          `createSurfaceTexture: level ${level} of a ${width}x${height} ${format.toUpperCase()} ` +
+            `image is ${want} bytes, and ${got} were given`,
+        );
+      }
+    }
+  }
+  return count;
+}
+
+/** What a refusal names: the format, its colour space, and what the device offers instead. */
+export function compressedRefusal(
+  format: BlockFormat,
+  srgb: boolean,
+  width: number,
+  height: number,
+  available: readonly CompressedTextureFormat[],
+): string {
+  const asked = `${format.toUpperCase()}${srgb ? ' sRGB' : ''} at ${width}x${height}`;
+  const offered = available.length === 0 ? 'no BC format' : available.join(', ');
+  return (
+    `createSurfaceTexture: this device cannot take ${asked} as blocks — it offers ${offered}, and ` +
+    'a BC texture must be whole 4x4 blocks at level 0. Decode it first (decodeBc in ' +
+    '@driftengine/assets), or ask renderer.compressedFormats before choosing.'
+  );
+}
+
+/** The format name and level count blocks upload as here, or a refusal naming why they cannot. */
+export function planBlocks(
+  blocks: readonly CompressedTextureSource[],
+  srgb: boolean,
+  compressed: readonly CompressedTextureFormat[],
+): { readonly name: CompressedTextureFormat; readonly levels: number } {
+  const { format, width, height } = blocks[0] as CompressedTextureSource;
+  const name = compressedFormatName(format, srgb);
+  if (name === null || !uploadsCompressed(format, srgb, width, height, compressed)) {
+    throw new Error(compressedRefusal(format, srgb, width, height, compressed));
+  }
+  return { name, levels: compressedLevels(blocks) };
+}
+
+/**
+ * `update` replaces pixels with an image, and a texture holding blocks has no pixels to replace:
+ * its format is the blocks', and an image would be a different texture. Refused rather than
+ * quietly reallocated, so the handle a draw holds keeps meaning what it meant.
+ */
+export function refuseBlockUpdate(format: BlockFormat | null): void {
+  if (format === null) return;
+  throw new Error(
+    `updateSurfaceTexture: this texture holds ${format.toUpperCase()} blocks, and update replaces ` +
+      'an image. Build a new texture for new contents.',
+  );
+}

package/src/render/cutoutCaster.ts

@@ -17,6 +17,8 @@ import type { SurfaceMaterial } from './surfaceTexture.ts';
 export interface CutoutCaster<Texture> {
   readonly albedo: Texture;
   readonly cutoff: number;
+  /** 1 for a dithered edge, which a caster draws with a pattern that does not move. */
+  readonly dithered: number;
   readonly u: number;
   readonly v: number;
   readonly uOffset: number;
@@ -26,6 +28,7 @@ export interface CutoutCaster<Texture> {
 const answer: {
   albedo: unknown;
   cutoff: number;
+  dithered: number;
   u: number;
   v: number;
   uOffset: number;
@@ -33,6 +36,7 @@ const answer: {
 } = {
   albedo: null,
   cutoff: 0,
+  dithered: 0,
   u: 1,
   v: 1,
   uOffset: 0,
@@ -49,6 +53,7 @@ export function cutoutOf<Texture>(
   if (albedo === null || !(cutoff > 0)) return null;
   answer.albedo = albedo;
   answer.cutoff = cutoff;
+  answer.dithered = material.cutoutMode === 'dithered' ? 1 : 0;
   answer.u = material.uScale ?? 1;
   answer.v = material.vScale ?? 1;
   answer.uOffset = material.uOffset ?? 0;

package/src/render/cutoutDither.ts

@@ -0,0 +1,99 @@
+/**
+ * A cutout whose edge is a share of the pixel rather than a line through it.
+ *
+ * **Why.** A hard alpha test draws a strand of hair, an eyelash or a fringe of leaves as a stair of
+ * whole pixels: a card's alpha falls off over a few texels and the test turns that into on and off.
+ * A dithered cutout keeps each pixel with a probability, the share of it the texture covers, and
+ * something downstream then averages the pattern back into coverage. What can average it depends on
+ * the frame, so the material asks for the smooth edge and the renderer decides, per frame, how:
+ *
+ * - **A temporal resolve (TAA or DriftTR)**: the pixel is kept against a threshold that moves every
+ *   frame, and the resolve integrates the pattern over its history into coverage.
+ * - **A multisampled frame**: the share goes to the GPU as alpha-to-coverage, which turns it into
+ *   that many of the pixel's samples.
+ * - **Neither**: the hard test, because a dither nothing resolves is grain on the screen.
+ *
+ * **What it gives up**: a dithered edge under a temporal resolve is soft by one history's worth of
+ * blur and ghosts slightly behind a fast card, which is the resolve's own trade; and under
+ * multisampling the share is quantised to the sample count, five levels at four samples. **What
+ * would make it wrong** is a pass that tests depth for equality against the main pass and discards
+ * differently from it; the caster and the lit pass take their keep from the same two functions here.
+ */
+
+/** What a material asks for. `'hard'` is every cutout that shipped before this. */
+export type CutoutMode = 'hard' | 'dithered';
+
+/** What the frame does with it: 0, 1 and 2 in the shader's `uCutout.y`. */
+export type CutoutResolve = 'hard' | 'dither' | 'coverage';
+
+/** The shader's number for a resolve. */
+export const CUTOUT_RESOLVE_CODE: Readonly<Record<CutoutResolve, number>> = Object.freeze({
+  hard: 0,
+  dither: 1,
+  coverage: 2,
+});
+
+/**
+ * How a cutout is drawn this frame. A temporal resolve is preferred over multisampling when a frame
+ * has both, because it resolves every share and multisampling only the sample count's.
+ */
+export function resolveCutout(mode: CutoutMode, temporal: boolean, samples: number): CutoutResolve {
+  if (mode !== 'dithered') return 'hard';
+  if (temporal) return 'dither';
+  if (samples > 1) return 'coverage';
+  return 'hard';
+}
+
+/**
+ * The share of a pixel a cutout keeps, from its alpha: half at the cutoff, ramping over a band
+ * twice the distance to the nearer end. At a cutoff of a half that is alpha itself.
+ */
+export function cutoutShare(alpha: number, cutoff: number): number {
+  const band = Math.max(2 * Math.min(cutoff, 1 - cutoff), 1e-4);
+  return Math.min(Math.max((alpha - cutoff) / band + 0.5, 0), 1);
+}
+
+/**
+ * The temporal step of the noise below, per frame: Jimenez's constant (2014), which moves the
+ * pattern across the tile rather than stepping each pixel's threshold.
+ *
+ * **A golden-ratio step per pixel was tried and measured, and it is not better.** It spreads a still
+ * pixel's thresholds evenly over time, which reads like the cure for grain; on a card of strands
+ * under TAA it left 12.9 levels of grain against this one's 11.7. The floor is the resolve's own: it
+ * keeps nine tenths of its history, so the newest frame's kept-or-not pattern is a tenth of the
+ * picture, about ten levels of grain at a half share whatever sequence chose it.
+ */
+const NOISE_FRAME_STEP = 5.588238;
+
+/**
+ * The threshold a pixel's share is compared against: interleaved gradient noise (Jimenez,
+ * "Next Generation Post Processing in Call of Duty: Advanced Warfare", 2014), offset by the frame so
+ * the pattern moves. `x` and `y` are pixel centres, as `gl_FragCoord.xy` is.
+ */
+export function ditherThreshold(x: number, y: number, frame: number): number {
+  const px = x + NOISE_FRAME_STEP * frame;
+  const py = y + NOISE_FRAME_STEP * frame;
+  const inner = 0.06711056 * px + 0.00583715 * py;
+  const f = 52.9829189 * (inner - Math.floor(inner));
+  return f - Math.floor(f);
+}
+
+/**
+ * The two functions in GLSL, for the lit pass and every caster that keeps the same pixels.
+ *
+ * `cutoutKeeps(share, pixel, frame)` is the dithered test; `cutoutShare(alpha, cutoff)` is also what
+ * a coverage frame writes as alpha. Frame is a float the renderer counts and wraps, so the noise's
+ * argument stays small enough for a half-precision device.
+ */
+export const CUTOUT_DITHER_GLSL = `
+float cutoutShare(float alpha, float cutoff) {
+  float band = max(2.0 * min(cutoff, 1.0 - cutoff), 1e-4);
+  return clamp((alpha - cutoff) / band + 0.5, 0.0, 1.0);
+}
+
+bool cutoutKeeps(float share, vec2 pixel, float frame) {
+  vec2 p = pixel + vec2(${NOISE_FRAME_STEP.toFixed(6)} * frame);
+  float noise = fract(52.9829189 * fract(dot(p, vec2(0.06711056, 0.00583715))));
+  return share > noise;
+}
+`;

package/src/render/eyeRefraction.ts

@@ -0,0 +1,72 @@
+/**
+ * The eye model's refraction, as `shaders/flat/eye.ts` computes it: the reference its tests hold the
+ * arithmetic to, and nothing at run time calls it.
+ *
+ * **An iris is seen through a cornea**, a few millimetres of clear fluid above it with an index near
+ * water's, so it is not where it is painted: the eye's ray bends at the cornea toward the axis and
+ * meets the iris plane somewhere else, and the iris seems to lie deeper and to shift as the eye
+ * turns away. The lit stage moves the iris's texture coordinate by that shift before any map of
+ * the material is read, so the whole iris — colour, relief, its own channels — moves as one.
+ *
+ * **The shift**: refract the view at the cornea's surface, follow the refracted ray down until it
+ * has descended the cornea's height above the iris plane along the eye's axis, and take what it
+ * travelled across the plane. Head-on it is nothing; at an angle θ to a flat cornea it is
+ * `height · tan(asin(sin θ / ior))`. The plane is perpendicular to the axis, so a cornea seen
+ * almost edge-on sends the ray along it: the descent is floored, which bounds the shift at about a
+ * thousand times the height rather than letting it run to infinity at the limb.
+ */
+import type { Vec3 } from '../math/color.ts';
+
+/** Schlick's base for the cornea's highlight, at the model's default index 1.336. */
+export const CORNEA_F0 = ((1 - 1.336) / (1 + 1.336)) ** 2;
+
+/** How slowly a refracted ray may descend toward the iris plane before it is held there. */
+export const EYE_MIN_DESCENT = 1e-3;
+
+/** GLSL's `refract`, into `out`: the transmitted direction, or zeros past total internal reflection. */
+export function refract(incident: Vec3, normal: Vec3, eta: number, out: Float64Array): void {
+  const d = normal[0] * incident[0] + normal[1] * incident[1] + normal[2] * incident[2];
+  const k = 1 - eta * eta * (1 - d * d);
+  if (k < 0) {
+    out.fill(0);
+    return;
+  }
+  const s = eta * d + Math.sqrt(k);
+  for (let c = 0; c < 3; c++) out[c] = eta * (incident[c] as number) - s * (normal[c] as number);
+}
+
+/**
+ * How far across the iris plane the eye's ray lands from where it entered the cornea, in metres,
+ * into `out`: `toEye` and `normal` at the cornea, `axis` the eye's, all unit vectors; `height` the
+ * cornea's height above the iris plane there.
+ */
+export function eyeRefractionShift(
+  toEye: Vec3,
+  normal: Vec3,
+  axis: Vec3,
+  ior: number,
+  height: number,
+  out: Float64Array,
+): void {
+  const ray = new Float64Array(3);
+  refract([-toEye[0], -toEye[1], -toEye[2]], normal, 1 / ior, ray);
+  const descent = Math.max(
+    -((ray[0] as number) * axis[0] + (ray[1] as number) * axis[1] + (ray[2] as number) * axis[2]),
+    EYE_MIN_DESCENT,
+  );
+  const reach = height / descent;
+  const along =
+    ((ray[0] as number) * axis[0] + (ray[1] as number) * axis[1] + (ray[2] as number) * axis[2]) *
+    reach;
+  for (let c = 0; c < 3; c++) out[c] = (ray[c] as number) * reach - axis[c] * along;
+}
+
+/**
+ * Where the iris is, without a map: 1 inside `irisRadius` of the texture's centre, 0 outside, across
+ * an edge `edge` wide — a limbus, not a cut.
+ */
+export function irisMask(u: number, v: number, irisRadius: number, edge: number): number {
+  const r = Math.hypot(u - 0.5, v - 0.5);
+  const t = Math.min(Math.max((r - (irisRadius - edge)) / (2 * edge), 0), 1);
+  return 1 - t * t * (3 - 2 * t);
+}

package/src/render/glCompressed.ts

@@ -0,0 +1,86 @@
+/**
+ * BC on WebGL2: which formats this context samples, and the upload of a stored chain.
+ *
+ * **Four extensions, each a different subset**, and the names a device offers are read off them:
+ * `WEBGL_compressed_texture_s3tc` is BC1 to BC3, its `_srgb` twin their sRGB forms,
+ * `EXT_texture_compression_rgtc` BC4 and BC5, and `EXT_texture_compression_bptc` BC7 in both. A
+ * desktop GPU usually has all four and a phone none, which is why the loader decodes there.
+ *
+ * BC1 is uploaded as `COMPRESSED_RGBA_S3TC_DXT1_EXT` rather than the RGB one, so a three-colour
+ * block's fourth index is transparent here as it is on WebGPU, whose only BC1 is `bc1-rgba-unorm`.
+ *
+ * The stored levels are uploaded as they are and no chain is generated: `generateMipmap` cannot
+ * write a compressed format, and the chain its author stored is the better one anyway. A chain that
+ * stops before 1x1 sets `TEXTURE_MAX_LEVEL` to its last level, or the texture is incomplete and
+ * samples black.
+ */
+import type { CompressedTextureFormat, CompressedTextureSource } from './compressedSource.ts';
+
+/** The constants each extension defines, written out so a missing extension cannot be read for one. */
+const INTERNAL: Readonly<Record<CompressedTextureFormat, number>> = {
+  bc1: 0x83f1, // COMPRESSED_RGBA_S3TC_DXT1_EXT
+  bc2: 0x83f2, // COMPRESSED_RGBA_S3TC_DXT3_EXT
+  bc3: 0x83f3, // COMPRESSED_RGBA_S3TC_DXT5_EXT
+  'bc1-srgb': 0x8c4d, // COMPRESSED_SRGB_ALPHA_S3TC_DXT1_EXT
+  'bc2-srgb': 0x8c4e, // COMPRESSED_SRGB_ALPHA_S3TC_DXT3_EXT
+  'bc3-srgb': 0x8c4f, // COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT
+  bc4: 0x8dbb, // COMPRESSED_RED_RGTC1_EXT
+  bc5: 0x8dbd, // COMPRESSED_RED_GREEN_RGTC2_EXT
+  bc7: 0x8e8c, // COMPRESSED_RGBA_BPTC_UNORM_EXT
+  'bc7-srgb': 0x8e8d, // COMPRESSED_SRGB_ALPHA_BPTC_UNORM_EXT
+};
+
+const BY_EXTENSION: readonly (readonly [string, readonly CompressedTextureFormat[]])[] = [
+  ['WEBGL_compressed_texture_s3tc', ['bc1', 'bc2', 'bc3']],
+  ['WEBGL_compressed_texture_s3tc_srgb', ['bc1-srgb', 'bc2-srgb', 'bc3-srgb']],
+  ['EXT_texture_compression_rgtc', ['bc4', 'bc5']],
+  ['EXT_texture_compression_bptc', ['bc7', 'bc7-srgb']],
+];
+
+/**
+ * The BC formats this context samples, enabling each extension that offers some. Enabling is what
+ * `getExtension` does, and a format is only legal in an upload once it has been called.
+ */
+export function glCompressedFormats(gl: WebGL2RenderingContext): CompressedTextureFormat[] {
+  const out: CompressedTextureFormat[] = [];
+  for (const [name, formats] of BY_EXTENSION) {
+    if (gl.getExtension(name) !== null) out.push(...formats);
+  }
+  return out;
+}
+
+/**
+ * Upload `layers`, every one of `levels` levels, to the bound `TEXTURE_2D_ARRAY` as `name`, and cap
+ * the chain at what was stored. The caller has checked the sources and the device.
+ */
+export function uploadCompressedArray(
+  gl: WebGL2RenderingContext,
+  name: CompressedTextureFormat,
+  layers: readonly CompressedTextureSource[],
+  levels: number,
+): void {
+  const first = layers[0] as CompressedTextureSource;
+  for (let level = 0; level < levels; level++) {
+    let size = 0;
+    for (const layer of layers) size += (layer.levels[level] as Uint8Array).length;
+    const data = new Uint8Array(size);
+    let at = 0;
+    for (const layer of layers) {
+      const bytes = layer.levels[level] as Uint8Array;
+      data.set(bytes, at);
+      at += bytes.length;
+    }
+    gl.compressedTexImage3D(
+      gl.TEXTURE_2D_ARRAY,
+      level,
+      INTERNAL[name],
+      Math.max(1, first.width >> level),
+      Math.max(1, first.height >> level),
+      layers.length,
+      0,
+      data,
+    );
+  }
+  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_BASE_LEVEL, 0);
+  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAX_LEVEL, levels - 1);
+}

package/src/render/hairLobes.ts

@@ -0,0 +1,188 @@
+/**
+ * The hair model's lobes, as `shaders/flat/hair.ts` computes them: the reference its tests hold the
+ * arithmetic to, and nothing at run time calls it.
+ *
+ * **A strand is a rough dielectric cylinder, index 1.55, after Marschner et al. 2003 in the
+ * real-time form Karis gave in 2016.** Light leaves it three ways, each a longitudinal Gaussian in
+ * `sinθi + sinθo` — the angles of light and eye out of the plane normal to the strand — times an
+ * azimuthal term in φ, the turn between them around it:
+ *
+ * - **R**, reflected off the surface: white, and shifted toward the root by twice the tilt of the
+ *   cuticle's scales, which point toward the tip;
+ * - **TT**, through the strand and out: the glow of a backlit head, shifted toward the tip by the
+ *   tilt, half as wide, and tinted by the fibre for the path it took;
+ * - **TRT**, reflected once inside: the coloured second highlight, three tilts toward the tip and
+ *   twice as wide;
+ *
+ * and a fourth, the light scattered through many strands, as a wrapped diffuse against a normal
+ * turned toward the eye across the strand, tinted by a root of the fibre's colour.
+ *
+ * **The tangent runs from root to tip**, and the tilt is positive for a strand authored that way. A
+ * card authored the other way round swaps its two highlights' ends, and takes a negative shift.
+ *
+ * **In this engine's light units.** A lamp's diffuse here is `albedo · cosθ` with no 1/π, so the
+ * published lobes, which are per unit irradiance, are multiplied by π; the scatter term's 1/π cancels.
+ * **What it gives up** is the fit's own: these are Karis's approximations to the azimuthal
+ * integrals, not the integrals, and they do not conserve energy exactly — the tests hold the sum
+ * under what a strand receives.
+ */
+import type { Vec3 } from '../math/color.ts';
+
+/** Schlick's base for a strand at index 1.55: `((1 − n) / (1 + n))²`. */
+export const HAIR_F0 = ((1 - 1.55) / (1 + 1.55)) ** 2;
+
+/**
+ * The narrowest longitudinal width a strand is drawn at, in radians.
+ *
+ * **Below every measured fibre**: Marschner gives the reflected lobe 5° to 10°, and this is about
+ * 3°, so no real hair is clamped. What it stops is a roughness of 0 making a Gaussian narrower than
+ * a pixel can sample — the speckle `MIN_LOBE_ALPHA` argues against for the standard lobe.
+ */
+export const HAIR_MIN_BETA = 0.05;
+
+/**
+ * The scatter term's answer to light arriving evenly from every side, per unit of it: the term's
+ * shape integrated over the sphere and divided by π, which is how this engine's lamp units add up.
+ *
+ * Derived: the wrapped half `(N·L + 1) / 4` averages 1/4 over the sphere, `1 − |T·L|` averages 1/2,
+ * and the shape is `mix(wrapped, 1 − |T·L|, 0.33)`, so its mean is 0.67 · 0.25 + 0.33 · 0.5 = 0.3325
+ * and its integral 4π times that. Over π: **1.33**.
+ */
+export const HAIR_SCATTER_SPHERE = 1.33;
+
+/** How much the scatter term leans toward the strand's own direction rather than the pseudo-normal. */
+const KAJIYA_SHARE = 0.33;
+
+/** A longitudinal lobe: a normalised Gaussian of width `beta` at `x` from its centre. */
+export function hairLongitudinal(beta: number, x: number): number {
+  return Math.exp((-0.5 * x * x) / (beta * beta)) / (Math.sqrt(2 * Math.PI) * beta);
+}
+
+/** Schlick's Fresnel for the strand at a cosine, clamped to the unit interval. */
+export function hairFresnel(cosine: number): number {
+  const c = 1 - Math.min(Math.max(cosine, 0), 1);
+  return HAIR_F0 + (1 - HAIR_F0) * c * c * c * c * c;
+}
+
+function dot(a: ArrayLike<number>, b: ArrayLike<number>): number {
+  return (
+    (a[0] as number) * (b[0] as number) +
+    (a[1] as number) * (b[1] as number) +
+    (a[2] as number) * (b[2] as number)
+  );
+}
+
+const clamp = (x: number, low: number, high: number): number => Math.min(Math.max(x, low), high);
+
+/** Where `hairLight` leaves its answer: R, then TT, TRT and the scatter, each a colour. */
+export const HAIR_OUT = { r: 0, tt: 1, trt: 4, scatter: 7, length: 10 } as const;
+
+/**
+ * One light on a strand, in lamp units and unshadowed, into `out` (`HAIR_OUT`'s layout: R is grey,
+ * the rest colours). `tangent`, `toLight` and `toEye` are unit vectors but for a tangent that could
+ * not be made one, which comes in as zeros; `fibre` is the base colour.
+ *
+ * **A lamp with a size widens every lobe by the angle it subtends**, `sourceRadius / 2·dist` as
+ * `sphereLobe` takes it, and the lobes are normalised Gaussians, so a wider one carries the same
+ * light rather than more. The sun passes zeros.
+ */
+export function hairLight(
+  tangent: ArrayLike<number>,
+  toLight: ArrayLike<number>,
+  toEye: ArrayLike<number>,
+  fibre: Vec3,
+  roughness: number,
+  shift: number,
+  scatter: number,
+  backlit: number,
+  sourceRadius: number,
+  dist: number,
+  out: Float64Array,
+): void {
+  const sinI = clamp(dot(tangent, toLight), -1, 1);
+  const sinO = clamp(dot(tangent, toEye), -1, 1);
+  /*
+   * The half difference angle, rounded to single precision as the device holds it: at its limit,
+   * light and eye at opposite ends of the strand, that is π/2 rounded up, whose cosine is −4.4e-8
+   * rather than double precision's +6e-17 — and the transmitted powers divide by it. The floor is
+   * for the device's number, and the rounding is what lets a test here see it.
+   */
+  const cosD = Math.max(
+    Math.cos(Math.fround(0.5 * Math.abs(Math.asin(sinO) - Math.asin(sinI)))),
+    1e-3,
+  );
+  let lp2 = 0;
+  let vp2 = 0;
+  let lpvp = 0;
+  for (let c = 0; c < 3; c++) {
+    const lp = (toLight[c] as number) - sinI * (tangent[c] as number);
+    const vp = (toEye[c] as number) - sinO * (tangent[c] as number);
+    lp2 += lp * lp;
+    vp2 += vp * vp;
+    lpvp += lp * vp;
+  }
+  const cosPhi = lpvp / Math.sqrt(lp2 * vp2 + 1e-4);
+  const cosHalfPhi = Math.sqrt(clamp(0.5 + 0.5 * cosPhi, 0, 1));
+  const beta = Math.max(roughness * roughness, HAIR_MIN_BETA);
+  const grow = sourceRadius / Math.max(2 * dist, 1e-3);
+  const x = sinI + sinO;
+
+  const r =
+    hairLongitudinal(beta + grow, x + 2 * shift) *
+    0.25 *
+    cosHalfPhi *
+    hairFresnel(Math.sqrt(clamp(0.5 + 0.5 * dot(toLight, toEye), 0, 1)));
+
+  const a = 1 / (1.19 / cosD + 0.36 * cosD);
+  const h = cosHalfPhi * (1 + a * (0.6 - 0.8 * cosPhi));
+  const fTT = hairFresnel(cosD * Math.sqrt(clamp(1 - h * h, 0, 1)));
+  const tt =
+    hairLongitudinal(0.5 * beta + grow, x - shift) *
+    Math.exp(-3.65 * cosPhi - 3.98) *
+    (1 - fTT) *
+    (1 - fTT) *
+    backlit;
+  const ttPower = (0.5 * Math.sqrt(clamp(1 - h * h * a * a, 0, 1))) / cosD;
+
+  const fTRT = hairFresnel(0.5 * cosD);
+  const trt =
+    hairLongitudinal(2 * beta + grow, x - 3 * shift) *
+    Math.exp(17 * cosPhi - 16.78) *
+    (1 - fTRT) *
+    (1 - fTRT) *
+    fTRT;
+  const trtPower = 0.8 / cosD;
+
+  let across0 = (toEye[0] as number) - (tangent[0] as number) * sinO;
+  let across1 = (toEye[1] as number) - (tangent[1] as number) * sinO;
+  let across2 = (toEye[2] as number) - (tangent[2] as number) * sinO;
+  const acrossLength = Math.hypot(across0, across1, across2);
+  if (acrossLength > 1e-4) {
+    across0 /= acrossLength;
+    across1 /= acrossLength;
+    across2 /= acrossLength;
+  }
+  const wrapped = clamp(
+    (across0 * (toLight[0] as number) +
+      across1 * (toLight[1] as number) +
+      across2 * (toLight[2] as number) +
+      1) /
+      4,
+    0,
+    1,
+  );
+  const shape = wrapped + (1 - Math.abs(sinI) - wrapped) * KAJIYA_SHARE;
+
+  out[HAIR_OUT.r] = Math.PI * r;
+  for (let c = 0; c < 3; c++) {
+    /*
+     * Above zero, so the device's `pow` never forms the logarithm of zero: an infinity in the
+     * middle of an expression is something a shader compiler may assume never happens. Nothing in
+     * double precision can show the difference, so no test here does.
+     */
+    const colour = Math.max(fibre[c], 1e-4);
+    out[HAIR_OUT.tt + c] = Math.PI * tt * colour ** ttPower;
+    out[HAIR_OUT.trt + c] = Math.PI * trt * colour ** trtPower;
+    out[HAIR_OUT.scatter + c] = Math.sqrt(fibre[c]) * scatter * shape;
+  }
+}