@driftengine/core 4.8.2 → 4.8.4

package/src/render/shaders/outputTransform.ts

@@ -27,6 +27,27 @@
  * gates on the same `gradeHere` the mesh pass uses.
  */
 
+/**
+ * A highlight shoulder that keeps a colour's hue: past 0.8 the brightest channel eases toward 1 —
+ * `0.8 + 0.2·e / (e + 0.2)` of an excess `e` — and the other two are scaled by the same factor, so
+ * an overbright red stays red rather than clipping channel by channel toward white.
+ *
+ * **Per channel is what sRGB alone does, and it is a hue shift**: `(1.6, 0.4, 0.2)` clips to
+ * `(1, 0.4, 0.2)`, a pinker colour and a wider core, where this gives `(0.96, 0.24, 0.12)`. The
+ * curve is the one a ported game's own resolve applies, read out of its build, so a port matching
+ * it reads the same. **What it gives up** is ACES's filmic toe and saturation roll-off: it touches
+ * nothing below 0.8 and never desaturates, so a scene that wants a film's look still wants ACES.
+ * Shared by the forward passes and the resolve, so the two cannot disagree about it.
+ */
+export const HIGHLIGHT_SHOULDER_GLSL = `
+vec3 highlightShoulder(vec3 c) {
+  float m = max(c.r, max(c.g, c.b));
+  if (m <= 0.8) return c;
+  float e = m - 0.8;
+  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);
+}
+`;
+
 /**
  * `uOutputTransform` and `uOutputExposure`, the fit, and `applyOutputTransform`.
  *
@@ -36,7 +57,7 @@
  * a branch that costs one compare.
  */
 export const OUTPUT_TRANSFORM_GLSL = `
-/** 0 none, 1 sRGB, 2 ACES then sRGB. See renderQuality.ts. */
+/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */
 uniform int uOutputTransform;
 /** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */
 uniform float uOutputExposure;
@@ -99,9 +120,11 @@ vec3 linearToSrgb(vec3 c) {
   return mix(high, low, step(c, vec3(0.0031308)));
 }
 
+${HIGHLIGHT_SHOULDER_GLSL}
 vec3 applyOutputTransform(vec3 c) {
   if (uOutputTransform == 0) return c;
   if (uOutputTransform == 2) c = acesFilmic(c);
+  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);
   return linearToSrgb(c);
 }
 `;

package/src/render/shaders/recon/motion.wgsl.ts

@@ -128,6 +128,108 @@ fn motionSkinnedVert(
   return out;
 }
 
+/*
+ * The same for a rig with eight influences a vertex, the second four at the scene's own locations
+ * 14 and 15 and summed after the first, as \`skinMatrix()\` sums them with \`SKIN_EIGHT\` on — or the
+ * motion of a face or a shoulder would be the four heaviest joints' alone.
+ */
+@vertex
+fn motionSkinnedEightVert(
+  @location(0) position: vec3<f32>,
+  @location(11) joints: vec4<f32>,
+  @location(12) weights: vec4<f32>,
+  @location(14) joints2: vec4<f32>,
+  @location(15) weights2: vec4<f32>,
+) -> Varyings {
+  let skin = skinOf(palette, joints, weights) + skinOf(palette, joints2, weights2);
+  let wasSkin =
+    skinOf(previousPalette, joints, weights) + skinOf(previousPalette, joints2, weights2);
+  let world = draw.model * (skin * vec4<f32>(position, 1.0));
+  let wasWorld = draw.previousModel * (wasSkin * vec4<f32>(position, 1.0));
+  var out: Varyings;
+  out.clip = frame.raster * world;
+  out.now = frame.viewProj * world;
+  out.was = frame.previousViewProj * wasWorld;
+  return out;
+}
+
+/*
+ * The cloth-bound stage: a skinned vertex moved toward its simulation triangle by its painted
+ * weight, as shaders/clothBinding.ts moves it in the scene, once with this frame's particles and
+ * once with last frame's. **The same arithmetic in the same order**, or the depth this stage writes
+ * is not the scene's and the equal test admits none of the garment. The binding's turn is not
+ * needed: a motion is where a point went, not which way it faces.
+ */
+@group(2) @binding(0) var clothBinding: texture_2d<f32>;
+@group(2) @binding(1) var clothParticles: texture_2d<f32>;
+@group(2) @binding(2) var previousClothParticles: texture_2d<f32>;
+
+fn clothTexel(i: i32, width: i32) -> vec2<i32> {
+  return vec2<i32>(i % width, i / width);
+}
+
+fn clothPoint(particles: texture_2d<f32>, indices: vec4<f32>, at: vec4<f32>) -> vec3<f32> {
+  let width = i32(textureDimensions(particles, 0).x);
+  let a = i32(indices.x);
+  let b = i32(indices.y);
+  let c = i32(indices.z);
+  let pa = textureLoad(particles, clothTexel(a, width), 0).xyz;
+  if (a == b && b == c) {
+    return pa;
+  }
+  let pb = textureLoad(particles, clothTexel(b, width), 0).xyz;
+  let pc = textureLoad(particles, clothTexel(c, width), 0).xyz;
+  let n = normalize(cross(pb - pa, pc - pa));
+  return pa * (1.0 - at.x - at.y) + pb * at.x + pc * at.y + n * at.z;
+}
+
+/* A skinned point now and last frame, carried to the cloth by the vertex's own weight. */
+fn clothVaryings(vertex: u32, world: vec4<f32>, wasWorld: vec4<f32>) -> Varyings {
+  let width = i32(textureDimensions(clothBinding, 0).x);
+  let indices = textureLoad(clothBinding, clothTexel(i32(vertex) * 2, width), 0);
+  let at = textureLoad(clothBinding, clothTexel(i32(vertex) * 2 + 1, width), 0);
+  let follow = indices.w;
+  let placed = vec4<f32>(mix(world.xyz, clothPoint(clothParticles, indices, at), follow), world.w);
+  let wasPlaced = vec4<f32>(
+    mix(wasWorld.xyz, clothPoint(previousClothParticles, indices, at), follow),
+    wasWorld.w);
+  var out: Varyings;
+  out.clip = frame.raster * placed;
+  out.now = frame.viewProj * placed;
+  out.was = frame.previousViewProj * wasPlaced;
+  return out;
+}
+
+@vertex
+fn motionClothVert(
+  @builtin(vertex_index) vertex: u32,
+  @location(0) position: vec3<f32>,
+  @location(11) joints: vec4<f32>,
+  @location(12) weights: vec4<f32>,
+) -> Varyings {
+  let world = draw.model * (skinOf(palette, joints, weights) * vec4<f32>(position, 1.0));
+  let wasWorld =
+    draw.previousModel * (skinOf(previousPalette, joints, weights) * vec4<f32>(position, 1.0));
+  return clothVaryings(vertex, world, wasWorld);
+}
+
+@vertex
+fn motionClothEightVert(
+  @builtin(vertex_index) vertex: u32,
+  @location(0) position: vec3<f32>,
+  @location(11) joints: vec4<f32>,
+  @location(12) weights: vec4<f32>,
+  @location(14) joints2: vec4<f32>,
+  @location(15) weights2: vec4<f32>,
+) -> Varyings {
+  let skin = skinOf(palette, joints, weights) + skinOf(palette, joints2, weights2);
+  let wasSkin =
+    skinOf(previousPalette, joints, weights) + skinOf(previousPalette, joints2, weights2);
+  let world = draw.model * (skin * vec4<f32>(position, 1.0));
+  let wasWorld = draw.previousModel * (wasSkin * vec4<f32>(position, 1.0));
+  return clothVaryings(vertex, world, wasWorld);
+}
+
 /*
  * The rewritten stage: a mesh whose vertices were rewritten this frame reads last frame's rows from
  * a second buffer of the same stride, so each vertex carries both of its positions.

package/src/render/shaders/recon/resolve.wgsl.ts

@@ -951,6 +951,19 @@ fn reconSceneBilinear(p: vec2<f32>) -> vec3<f32> {
   return textureSampleLevel(sceneTexture, linearSampler, uv, 0.0).xyz;
 }
 
+/*
+ * The surface's share of an output pixel, read from the jittered scene it was rebuilt from
+ * (sceneCoverage.ts): what the blended draws that landed before the reconstruction left of it.
+ * The late ones then cover the picture this is stored in, so the composite's occlusion reads both.
+ * Bilinear and at the unjittered position, which is where the colour beside it stands.
+ */
+fn reconSceneShare(ox: i32, oy: i32) -> f32 {
+  let output = vec2<f32>(f32(recon.outputSize.x), f32(recon.outputSize.y));
+  let render = vec2<f32>(f32(recon.renderSize.x), f32(recon.renderSize.y));
+  let at = (vec2<f32>(f32(ox), f32(oy)) + 0.5) / output + recon.jitter / render;
+  return textureSampleLevel(sceneTexture, linearSampler, vec2<f32>(at.x, 1.0 - at.y), 0.0).w;
+}
+
 fn reconHistoryBilinear(p: vec2<f32>) -> vec4<f32> {
   let size = vec2<f32>(f32(recon.outputSize.x), f32(recon.outputSize.y));
   let uv = vec2<f32>(p.x + 0.5, size.y - 0.5 - p.y) / size;
@@ -973,7 +986,8 @@ fn sharpenMain(@builtin(global_invocation_id) id: vec3<u32>) {
   if (id.x >= recon.outputSize.x || id.y >= recon.outputSize.y) { return; }
   let y = i32(recon.outputSize.y) - 1 - i32(id.y);
   let value = reconSharpenAt(i32(id.x), y);
-  textureStore(resolved, vec2<i32>(i32(id.x), i32(id.y)), vec4<f32>(value, 1.0));
+  let share = reconSceneShare(i32(id.x), y);
+  textureStore(resolved, vec2<i32>(i32(id.x), i32(id.y)), vec4<f32>(value, share));
 }
 `;
 }

package/src/render/shaders/rush.ts

@@ -25,6 +25,7 @@ import { DEPTH_OF_FIELD_GLSL } from './depthOfField.ts';
 import { AUTO_EXPOSURE_GLSL } from './exposure.ts';
 import { LOCAL_EXPOSURE_GLSL } from './localExposure.ts';
 import { FILM_LOOK_GLSL } from './filmLook.ts';
+import { HIGHLIGHT_SHOULDER_GLSL } from './outputTransform.ts';
 
 export const RUSH_FRAG = `#version 300 es
 precision highp float;
@@ -242,9 +243,11 @@ vec3 acesFilmic(vec3 x) {
   return clamp(ACES_OUTPUT * (a / b), 0.0, 1.0);
 }
 
+${HIGHLIGHT_SHOULDER_GLSL}
 vec3 grade(vec3 c) {
   if (uOutputTransform == 0) return c;
   if (uOutputTransform == 2) c = acesFilmic(c);
+  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);
   return linearToSrgb(c);
 }
 
@@ -335,7 +338,8 @@ vec3 finish(vec3 light) {
 }
 
 void main() {
-  vec3 scene = textureLod(uScene, vUv, 0.0).rgb;
+  vec4 sampled = textureLod(uScene, vUv, 0.0);
+  vec3 scene = sampled.rgb;
   if (uMotionStrength > 0.0) scene = cameraBlur(scene);
   /*
    * Defocus after the camera smear and before everything else, because a lens is the last thing
@@ -350,8 +354,15 @@ void main() {
    * not then darkened again along its own trail. mix from 1 rather than a multiply by the
    * strength, so the parameter reads as "how much of this occlusion", and 0 is exactly the
    * frame that existed before the effect did.
+   *
+   * **Scaled by the surface's share of the pixel**, which the scene carries in its alpha
+   * (sceneCoverage.ts): the occlusion was measured from the depth the opaque world left, and a
+   * pane, a puff of smoke or a caption in front of a corner wrote no depth, so darkening all of the
+   * pixel darkened them by a corner they hide. Where nothing blended landed the share is 1 and
+   * this is the frame it was.
    */
-  float ao = mix(1.0, textureLod(uAo, vUv + uAoOffset, 0.0).r, uAoStrength);
+  float share = clamp(sampled.a, 0.0, 1.0);
+  float ao = mix(1.0, textureLod(uAo, vUv + uAoOffset, 0.0).r, uAoStrength * share);
 
   /*
    * Distance from the centre, corrected so the falloff is a circle on screen rather than

package/src/render/shaders/skinBlur.ts

@@ -0,0 +1,105 @@
+/**
+ * Skin's screen-space scattering: one axis of the blur that spreads the diffuse pass by Burley's
+ * profile, and on the second axis the sum the frame takes back. `skinBlur.ts` beside the render
+ * directory is the kernel's reference and says what it gives up.
+ *
+ * **One pass, run twice**: along x into a target of its own, keeping the profile in the alpha, then
+ * along y blended additively into the frame — its colour added, the frame's alpha kept.
+ *
+ * **Refuses what is not the same skin**: a neighbour that wrote no skin, or one further in depth
+ * than four of the profile's widest distances, takes no weight, and what is kept is divided by
+ * what was kept, so a cheek's light does not pull toward the black beside its silhouette. A tap
+ * part skin is counted for the part it is: the target is read as coverage-weighted, which is what
+ * a filtered tap across an edge already is.
+ */
+import { glslIsFarDepth, glslSceneDepthToNdc } from '../depthConvention.ts';
+import { SKIN_BLUR_EDGES, SKIN_BLUR_TAPS, SKIN_PROFILES } from '../skinBlur.ts';
+
+const list = (values: readonly number[]): string => values.map((v) => v.toFixed(2)).join(', ');
+
+export const SKIN_BLUR_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/** The diffuse pass, or the first axis' result: diffuse in rgb, the profile as (index + 1) / 8. */
+uniform sampler2D uSkin;
+/** highp, for the reason the ambient occlusion blur gives: eight bits of depth find false edges. */
+uniform highp sampler2D uDepth;
+/** One texel along the axis being blurred, in UV. The other component is zero. */
+uniform vec2 uStep;
+/** A depth sample to view-space metres, as the ambient occlusion blur takes it. */
+uniform vec4 uDepthToViewZ;
+/** How many pixels a metre spans at a metre's distance. */
+uniform float uFocal;
+/** Each profile's scatter distance per channel, in metres. */
+uniform vec4 uProfiles[${SKIN_PROFILES}];
+
+out vec4 fragColor;
+
+const float TAPS[${SKIN_BLUR_TAPS.length}] = float[${SKIN_BLUR_TAPS.length}](${list(SKIN_BLUR_TAPS)});
+const float EDGES[${SKIN_BLUR_EDGES.length}] = float[${SKIN_BLUR_EDGES.length}](${list(SKIN_BLUR_EDGES)});
+
+float viewZ(float depth) {
+  float ndc = ${glslSceneDepthToNdc('depth')};
+  return (uDepthToViewZ.x * ndc + uDepthToViewZ.y) / (uDepthToViewZ.z * ndc + uDepthToViewZ.w);
+}
+
+/** Burley's profile across a line, integrated from 0 to x: one half at infinity. */
+vec3 burleyMass(float x, vec3 d) {
+  return 0.5 - (exp(-x / d) + 3.0 * exp(-x / (3.0 * d))) * 0.125;
+}
+
+void main() {
+  vec4 own = textureLod(uSkin, vUv, 0.0);
+  /*
+   * Not skin: nothing here to spread, and nothing to add. Any alpha is skin, because a pixel a
+   * silhouette crosses under multisampling resolves to its covered share of the profile's code, and
+   * its colour to that share of the diffuse, which is exactly what it owes the frame.
+   */
+  if (own.a < 1e-4) {
+    fragColor = vec4(0.0);
+    return;
+  }
+  float depth = textureLod(uDepth, vUv, 0.0).r;
+  if (${glslIsFarDepth('depth')}) {
+    fragColor = own;
+    return;
+  }
+  /* A part-covered pixel's code is its share of the whole: read it as the nearest, which is the
+     right profile at half coverage and up, and a neighbouring one only on a silhouette below it. */
+  int profile = clamp(int(own.a * 8.0 + 0.5) - 1, 0, ${SKIN_PROFILES - 1});
+  vec3 d = max(uProfiles[profile].xyz, vec3(1e-6));
+  float widest = max(d.r, max(d.g, d.b));
+  float z = abs(viewZ(depth));
+  /* The widest distance in pixels here: under half of one, there is nothing to spread across. */
+  float pixels = widest * uFocal / max(z, 1e-4);
+  if (pixels < 0.5) {
+    fragColor = own;
+    return;
+  }
+  vec3 centre = 2.0 * burleyMass(EDGES[0] * widest, d);
+  vec3 sum = own.rgb * centre;
+  vec3 weight = centre;
+  for (int i = 1; i < ${SKIN_BLUR_TAPS.length}; i++) {
+    vec3 outer = i < ${SKIN_BLUR_EDGES.length} ? burleyMass(EDGES[min(i, ${SKIN_BLUR_EDGES.length - 1})] * widest, d) : vec3(0.5);
+    vec3 w = outer - burleyMass(EDGES[i - 1] * widest, d);
+    for (int side = -1; side <= 1; side += 2) {
+      vec2 uv = vUv + uStep * (float(side) * TAPS[i] * pixels);
+      vec4 tap = textureLod(uSkin, uv, 0.0);
+      float tapZ = abs(viewZ(textureLod(uDepth, uv, 0.0).r));
+      float keep = clamp(1.0 - abs(tapZ - z) / (4.0 * widest), 0.0, 1.0);
+      /*
+       * How much of the tap is skin: a filtered tap astride a silhouette is part skin and part
+       * the black beside it, in colour and in alpha alike, so its alpha over this pixel's says the
+       * share, and the colour is already that share of the skin's — counted as such, it neither
+       * darkens the edge nor drops out.
+       */
+      float cover = clamp(tap.a / own.a, 0.0, 1.0);
+      sum += tap.rgb * w * keep;
+      weight += w * (cover * keep);
+    }
+  }
+  fragColor = vec4(sum / weight, own.a);
+}
+`;

package/src/render/shaders/skinning.ts

@@ -31,6 +31,18 @@ uniform highp sampler2D uJointPalette;
 
 layout(location = 11) in vec4 aJoints;
 layout(location = 12) in vec4 aWeights;
+/*
+ * **The fifth to eighth influences, read only by a pipeline built for a mesh that has them.**
+ *
+ * Declared in every skinned variant at the last two locations WebGL2 guarantees — 13 is the channel,
+ * and an instanced draw, which takes 11 to 15, cannot skin — and fed zeros by the absent-attribute
+ * constants for a mesh with four. \`SKIN_EIGHT\` is a pipeline constant rather than a permutation,
+ * so the generated vertex stages do not double: off, the device compiles the second sum away and a
+ * four-influence mesh pays nothing; on, it is four more palette reads a vertex.
+ */
+const bool SKIN_EIGHT = false;  // wgsl:override
+layout(location = 14) in vec4 aJoints2;
+layout(location = 15) in vec4 aWeights2;
 
 /** One joint's matrix, read as four consecutive texels of row 0. */
 mat4 jointMatrix(int index) {
@@ -51,9 +63,24 @@ mat4 jointMatrix(int index) {
  * by hand with unnormalised weights, which shades slightly dark or bright rather than breaking.
  */
 mat4 skinMatrix() {
-  return jointMatrix(int(aJoints.x)) * aWeights.x
-       + jointMatrix(int(aJoints.y)) * aWeights.y
-       + jointMatrix(int(aJoints.z)) * aWeights.z
-       + jointMatrix(int(aJoints.w)) * aWeights.w;
+  mat4 m = jointMatrix(int(aJoints.x)) * aWeights.x
+         + jointMatrix(int(aJoints.y)) * aWeights.y
+         + jointMatrix(int(aJoints.z)) * aWeights.z
+         + jointMatrix(int(aJoints.w)) * aWeights.w;
+  if (SKIN_EIGHT) {
+    m += jointMatrix(int(aJoints2.x)) * aWeights2.x
+       + jointMatrix(int(aJoints2.y)) * aWeights2.y
+       + jointMatrix(int(aJoints2.z)) * aWeights2.z
+       + jointMatrix(int(aJoints2.w)) * aWeights2.w;
+  }
+  return m;
 }
+
 `;
+
+/** The source above with the eight-influence switch on, for a WebGL2 program built for such a mesh. */
+export function skinEight(source: string): string {
+  const off = 'const bool SKIN_EIGHT = false;';
+  if (!source.includes(off)) throw new Error('skinEight: the source carries no SKIN_EIGHT switch');
+  return source.replace(off, 'const bool SKIN_EIGHT = true;');
+}

package/src/render/shaders/temporalResolve.ts

@@ -211,11 +211,18 @@ vec3 historyCatmullRom(vec2 uv) {
 }
 
 void main() {
-  vec3 current = textureLod(uScene, vUv, 0.0).rgb;
+  /*
+   * **The alpha is this frame's and takes no history.** It is how much of the pixel is still the
+   * opaque surface (sceneCoverage.ts), which the composite's occlusion reads after this has
+   * replaced the scene, so it passes through untouched. The history is read for its colour alone.
+   */
+  vec4 sampled = textureLod(uScene, vUv, 0.0);
+  vec3 current = sampled.rgb;
+  float share = sampled.a;
 
   /* Nothing to blend towards: the first frame, a resize, a cut, or the effect switched off. */
   if (uHistoryBlend <= 0.0) {
-    fragColor = vec4(current, 1.0);
+    fragColor = vec4(current, share);
     flickerOut = freshRecord(current);
     flickerMotionOut = vec4(0.0);
     return;
@@ -248,7 +255,7 @@ void main() {
   vec4 previous = uReprojection * clip;
   /* Behind the previous eye: there is no last-frame position to sample. */
   if (previous.w <= 0.0) {
-    fragColor = vec4(current, 1.0);
+    fragColor = vec4(current, share);
     flickerOut = freshRecord(current);
     flickerMotionOut = vec4(metres, 0.0, 0.0, 0.0);
     return;
@@ -261,7 +268,7 @@ void main() {
    * as a smear for as long as the camera kept turning.
    */
   if (wasUv.x < 0.0 || wasUv.x > 1.0 || wasUv.y < 0.0 || wasUv.y > 1.0) {
-    fragColor = vec4(current, 1.0);
+    fragColor = vec4(current, share);
     flickerOut = freshRecord(current);
     flickerMotionOut = vec4(metres, 0.0, 0.0, 0.0);
     return;
@@ -320,6 +327,6 @@ void main() {
     repeated * still
   );
   flickerMotionOut = vec4(metres, swingOut, 0.0, 0.0);
-  fragColor = vec4(mix(current, bounded, blend), 1.0);
+  fragColor = vec4(mix(current, bounded, blend), share);
 }
 `;

package/src/render/shadowCasters.ts

@@ -2,6 +2,7 @@ import { resolveGlass, type GlassOptions, type ResolvedGlass } from './glass.ts'
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { InstanceData } from './instancedMesh.ts';
 import type { InstancedHandle, MeshHandle, ScatterHandle } from './backend/api.ts';
+import type { ClothBindingHandle, ClothParticlesHandle } from './backend/api.ts';
 import type { MeshInstances } from './instances.ts';
 import type { SurfaceMaterial } from './surfaceTexture.ts';
 import type { SurfaceTextureHandle } from './backend/api.ts';
@@ -70,6 +71,12 @@ export function glassOf(material: SceneCasterMaterial | undefined, out: Resolved
   return resolveGlass(material?.glass, out);
 }
 
+/** A skinned caster's cloth: the mesh's binding and the character's particles. See `setCloth`. */
+export interface ShadowCasterCloth {
+  readonly binding: ClothBindingHandle;
+  readonly particles: ClothParticlesHandle;
+}
+
 export interface ShadowCasterSink {
   /** A rigid mesh at a model transform: the world, a prop, a static piece of scenery. */
   mesh(mesh: MeshHandle, model: ReadonlyMat4, material?: SceneCasterMaterial): void;
@@ -88,6 +95,12 @@ export interface ShadowCasterSink {
     model: ReadonlyMat4,
     palette: Float32Array,
     material?: SceneCasterMaterial,
+    /**
+     * The cloth the visible draw places this mesh by, if any — for the reason the palette is not
+     * optional in spirit: a garment cast from its skinning alone throws a shadow that does not
+     * move as the cloth does.
+     */
+    cloth?: ShadowCasterCloth,
   ): void;
   /**
    * An instanced batch of rigid meshes, placed by the same matrices the visible draw uses.

package/src/render/skinBlur.ts

@@ -0,0 +1,53 @@
+/**
+ * Skin's screen-space scattering, as `shaders/skinBlur.ts` spreads it: the reference its tests hold
+ * the kernel to, and nothing at run time calls it.
+ *
+ * **What it spreads.** With `skinScattering: 'screen-space'`, a skin draw writes its specular to the
+ * frame and its diffuse — the light that went beneath the surface — to a target of its own, with the
+ * profile it scatters by in the alpha. Before anything blended is drawn, that target is blurred
+ * along the screen's two axes by Burley's normalised diffusion, one width per channel, and added
+ * back: light that entered a cheek leaves it a centimetre away, reddest furthest, across the
+ * pixels that centimetre covers at the cheek's distance. The pre-integrated fit stays in the lit
+ * stage for what this cannot see — a terminator's curvature — and this carries what that cannot:
+ * light crossing a shadow's edge, or a nostril's rim, in the picture rather than in a fit.
+ *
+ * **Separable, which the profile is not**: two 1D passes with Burley's profile integrated across a
+ * line, as Jimenez's separable subsurface scattering does. What it gives up is the radial shape, a
+ * blur a little squarer than the profile; what it buys is thirteen taps an axis rather than a disc.
+ *
+ * **Each tap is the profile's mass over its cell, in closed form**, so a channel's weights sum to
+ * one before any are refused, and a channel that travels a quarter as far as the widest keeps most
+ * of its light at the centre. The taps are placed in units of the widest channel's distance and
+ * closer together near the centre, where the profile's sharp peak is.
+ */
+
+/** The taps' distances from the centre, one side, in units of the widest channel's distance. */
+export const SKIN_BLUR_TAPS = [0, 0.4, 1.1, 2.1, 3.5, 5.6, 9] as const;
+
+/**
+ * Where each tap's cell ends, in the same units: halfway to the next tap, and the last cell runs
+ * to infinity, so the profile's whole mass is somewhere.
+ */
+export const SKIN_BLUR_EDGES = [0.2, 0.75, 1.6, 2.8, 4.55, 7.3] as const;
+
+/** How many profiles a frame's skin can name: `SkinModel.profile`. */
+export const SKIN_PROFILES = 8;
+
+/**
+ * Burley's profile across a line, `(e^(−x/d) + e^(−x/3d)) / 8d`, integrated from 0 to `x`: half of
+ * it lies on each side, so this reaches ½ at infinity.
+ */
+export function burleyMass(x: number, d: number): number {
+  return 0.5 - (Math.exp(-x / d) + 3 * Math.exp(-x / (3 * d))) / 8;
+}
+
+/**
+ * Tap `tap`'s weight for one channel scattering `d`, the taps spaced by `widest`: the centre's cell
+ * is both sides of it, every other cell one side, and a tap on each side takes this weight.
+ */
+export function skinBlurWeight(tap: number, d: number, widest: number): number {
+  if (tap === 0) return 2 * burleyMass((SKIN_BLUR_EDGES[0] as number) * widest, d);
+  const inner = (SKIN_BLUR_EDGES[tap - 1] as number) * widest;
+  const outer = tap < SKIN_BLUR_EDGES.length ? (SKIN_BLUR_EDGES[tap] as number) * widest : Infinity;
+  return (outer === Infinity ? 0.5 : burleyMass(outer, d)) - burleyMass(inner, d);
+}

package/src/render/skinScatter.ts

@@ -0,0 +1,92 @@
+/**
+ * The skin model's arithmetic, as `shaders/flat/skin.ts` computes it: the reference its tests hold
+ * the fit to, and nothing at run time calls it.
+ *
+ * **Pre-integrated, after Penner 2011, with the profile integrated rather than looked up.** Light
+ * entering skin leaves it a little way off, so on a curved surface a point is lit by its
+ * neighbours' `N·L` as well as its own: the clamped cosine averaged around a ring of the surface's
+ * curvature, weighted by the diffusion profile at each neighbour's distance. The profile is Burley's
+ * normalised diffusion, one per channel, at a scatter distance `d` — the model's `radius` times its
+ * scatter colour — projected onto the ring's plane, as a cylinder's cross-section sees it. The
+ * result depends on `N·L` and on one number per channel, `k = d × curvature`, and at `k = 0` it is
+ * Lambert's.
+ *
+ * **Fitted rather than tabulated**, so no seventeenth sampler and no image: the ring average is the
+ * clamped cosine convolved with an angular kernel, so it splits into the cosine's first harmonic —
+ * scaled by one number, `κ₁(k)` — and a smoothed `|cos θ|` carrying every even harmonic:
+ *
+ *     D(c, k) = ½ (κ₁ c + A √(c² + ε²) + B)
+ *
+ * with `κ₁`, `A`, `ε` and `B` closed forms in `k` that are exactly `1, 1, 0, 0` at `k = 0`. The
+ * test measures it against the integral done numerically: **worst 0.0105 over `k` to 10**, beyond
+ * which the shader holds `k` — a scatter ten times the surface's own radius, where the answer is
+ * nearly flat already.
+ */
+
+/** Schlick's base for skin, at index 1.4: `((1 − n) / (1 + n))²`. */
+export const SKIN_F0 = ((1 - 1.4) / (1 + 1.4)) ** 2;
+
+/** The largest `k` the fit is held to, and where the shader clamps it. */
+export const SKIN_MAX_K = 10;
+
+/**
+ * The fit's eight numbers, found by minimising its worst error against the numeric integral over
+ * `c` in [−1, 1] and `k` in (0, 10]:
+ *
+ * - `kappa`: `κ₁ = (1 + a k² + b k³)^(−1/6)` — the first harmonic's share, quadratic at zero and
+ *   falling as `1/√k`, as the integral's does;
+ * - `spread`: `A = (1 + a k³)^(−1/6)`;
+ * - `soften`: `ε = a k / (1 + b k)`, how far `|c|` is rounded at the terminator;
+ * - `floor`: `B = (1 − A)(a + b (1 − A))`, the even part's floor as `A` gives up `|c|`.
+ */
+export const SKIN_FIT = {
+  kappa: [22.6772, 101.349],
+  spread: 838.87,
+  soften: [1.3081, 3.65743],
+  floor: [0.508537, 0.129496],
+} as const;
+
+/** The ring-averaged `N·L` for one channel: `c` is `N·L`, `k` that channel's scatter × curvature. */
+export function skinRing(c: number, k: number): number {
+  const q = Math.min(Math.max(k, 0), SKIN_MAX_K);
+  const k2 = q * q;
+  const kappa = (1 + SKIN_FIT.kappa[0] * k2 + SKIN_FIT.kappa[1] * k2 * q) ** (-1 / 6);
+  const spread = (1 + SKIN_FIT.spread * k2 * q) ** (-1 / 6);
+  const soften = (SKIN_FIT.soften[0] * q) / (1 + SKIN_FIT.soften[1] * q);
+  const given = 1 - spread;
+  const floor = given * (SKIN_FIT.floor[0] + SKIN_FIT.floor[1] * given);
+  return 0.5 * (kappa * c + spread * Math.sqrt(c * c + soften * soften) + floor);
+}
+
+/**
+ * How far into a penumbra skin's light reaches, as a width the shadow is assumed to have: the
+ * lamp loop reads a shadow where its derivative cannot be taken, so its width in the world is not
+ * known there. Two centimetres is a soft edge across a face.
+ */
+export const SKIN_PENUMBRA_WIDTH = 0.02;
+
+/**
+ * A shadow on skin, one channel at scatter distance `d`: the shadow's own value raised to
+ * `1 / (1 + d / width)`, so light reaches further into the penumbra the further that channel
+ * travels beneath the surface — red furthest, which is the red edge a shadow on skin has — and a
+ * shadow stays whole at 0 and absent at 1. **What it gives up** is the profile itself: Penner
+ * convolves a sharpened shadow with it, which needs the penumbra's width in the world and hardens
+ * the narrow channels' edge where nothing widened the map to make room.
+ */
+export function skinPenumbra(shadow: number, d: number): number {
+  return Math.max(shadow, 0) ** (1 / (1 + d / SKIN_PENUMBRA_WIDTH));
+}
+
+/**
+ * Light through a thin part, one channel: `transmission × exp(−thickness / d)` of the light behind,
+ * by how squarely it is behind. A part as thick as its curvature's diameter — an ear's rim at a few
+ * millimetres, a cheek at ten centimetres — passes red through the one and nothing through the other.
+ */
+export function skinTransmission(
+  backNdl: number,
+  thickness: number,
+  d: number,
+  transmission: number,
+): number {
+  return transmission * Math.exp(-thickness / Math.max(d, 1e-6)) * Math.max(backNdl, 0);
+}