@driftengine/core 4.8.3 → 4.8.5

package/src/render/shaders/generated/skinBlur.wgsl.ts

@@ -0,0 +1,56 @@
+/*
+ * Generated from ../skinBlur.ts by `npm run wgsl`. Do not edit.
+ *
+ * The GLSL beside this file is the source of truth. A hand edit here is discarded by
+ * the next generation, and `npm run wgsl:check` fails the build when this is stale.
+ */
+
+export const SKIN_BLUR_FRAG_WGSL = "struct Uniforms {\n    uStep: vec2<f32>,\n    uDepthToViewZ: vec4<f32>,\n    uFocal: f32,\n    uProfiles: array<vec4<f32>, 8>,\n}\n\n@group(0) @binding(1) \nvar<uniform> unnamed: Uniforms;\n@group(0) @binding(32) \nvar uSkin_t: texture_2d<f32>;\n@group(0) @binding(33) \nvar uSkin_s: sampler;\nvar<private> vUv_1: vec2<f32>;\nvar<private> fragColor: vec4<f32>;\n@group(0) @binding(34) \nvar uDepth_t: texture_2d<f32>;\n@group(0) @binding(35) \nvar uDepth_s: sampler;\n\nfn burleyMass_u0028_f1_u003b_vf3_u003b(x: ptr<function, f32>, d: ptr<function, vec3<f32>>) -> vec3<f32> {\n    let _e51 = (*x);\n    let _e53 = (*d);\n    let _e57 = (*x);\n    let _e59 = (*d);\n    return (vec3(0.5f) - ((exp((vec3(-(_e51)) / _e53)) + (exp((vec3(-(_e57)) / (_e59 * 3f))) * 3f)) * 0.125f));\n}\n\nfn viewZ_u0028_f1_u003b(depth: ptr<function, f32>) -> f32 {\n    var ndc: f32;\n\n    let _e51 = (*depth);\n    ndc = (1f - (_e51 * 2f));\n    let _e56 = unnamed.uDepthToViewZ[0u];\n    let _e57 = ndc;\n    let _e61 = unnamed.uDepthToViewZ[1u];\n    let _e65 = unnamed.uDepthToViewZ[2u];\n    let _e66 = ndc;\n    let _e70 = unnamed.uDepthToViewZ[3u];\n    return (((_e56 * _e57) + _e61) / ((_e65 * _e66) + _e70));\n}\n\nfn main_1() {\n    var own: vec4<f32>;\n    var depth_1: f32;\n    var profile: i32;\n    var d_1: vec3<f32>;\n    var widest: f32;\n    var z: f32;\n    var param: f32;\n    var pixels: f32;\n    var centre: vec3<f32>;\n    var param_1: f32;\n    var param_2: vec3<f32>;\n    var sum: vec3<f32>;\n    var weight: vec3<f32>;\n    var i: i32;\n    var outer: vec3<f32>;\n    var local: vec3<f32>;\n    var indexable: array<f32, 6>;\n    var param_3: f32;\n    var param_4: vec3<f32>;\n    var w: vec3<f32>;\n    var indexable_1: array<f32, 6>;\n    var param_5: f32;\n    var param_6: vec3<f32>;\n    var side: i32;\n    var uv: vec2<f32>;\n    var indexable_2: array<f32, 7>;\n    var tap: vec4<f32>;\n    var tapZ: f32;\n    var param_7: f32;\n    var keep: f32;\n    var cover: f32;\n\n    let _e80 = vUv_1;\n    let _e81 = textureSampleLevel(uSkin_t, uSkin_s, _e80, 0f);\n    own = _e81;\n    let _e83 = own[3u];\n    if (_e83 < 0.0001f) {\n        fragColor = vec4<f32>(0f, 0f, 0f, 0f);\n        return;\n    }\n    let _e85 = vUv_1;\n    let _e86 = textureSampleLevel(uDepth_t, uDepth_s, _e85, 0f);\n    depth_1 = _e86.x;\n    let _e88 = depth_1;\n    if (_e88 <= 0f) {\n        let _e90 = own;\n        fragColor = _e90;\n        return;\n    }\n    let _e92 = own[3u];\n    profile = clamp((i32(((_e92 * 8f) + 0.5f)) - 1i), 0i, 7i);\n    let _e98 = profile;\n    let _e101 = unnamed.uProfiles[_e98];\n    d_1 = max(_e101.xyz, vec3<f32>(0.000001f, 0.000001f, 0.000001f));\n    let _e105 = d_1[0u];\n    let _e107 = d_1[1u];\n    let _e109 = d_1[2u];\n    widest = max(_e105, max(_e107, _e109));\n    let _e112 = depth_1;\n    param = _e112;\n    let _e113 = viewZ_u0028_f1_u003b((&param));\n    z = abs(_e113);\n    let _e115 = widest;\n    let _e117 = unnamed.uFocal;\n    let _e119 = z;\n    pixels = ((_e115 * _e117) / max(_e119, 0.0001f));\n    let _e122 = pixels;\n    if (_e122 < 0.5f) {\n        let _e124 = own;\n        fragColor = _e124;\n        return;\n    }\n    let _e125 = widest;\n    param_1 = (0.2f * _e125);\n    let _e127 = d_1;\n    param_2 = _e127;\n    let _e128 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_1), (&param_2));\n    centre = (_e128 * 2f);\n    let _e130 = own;\n    let _e132 = centre;\n    sum = (_e130.xyz * _e132);\n    let _e134 = centre;\n    weight = _e134;\n    i = 1i;\n    loop {\n        let _e135 = i;\n        if (_e135 < 7i) {\n            let _e137 = i;\n            if (_e137 < 6i) {\n                let _e139 = i;\n                indexable = array<f32, 6>(0.2f, 0.75f, 1.6f, 2.8f, 4.55f, 7.3f);\n                let _e142 = indexable[min(_e139, 5i)];\n                let _e143 = widest;\n                param_3 = (_e142 * _e143);\n                let _e145 = d_1;\n                param_4 = _e145;\n                let _e146 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_3), (&param_4));\n                local = _e146;\n            } else {\n                local = vec3<f32>(0.5f, 0.5f, 0.5f);\n            }\n            let _e147 = local;\n            outer = _e147;\n            let _e148 = outer;\n            let _e149 = i;\n            indexable_1 = array<f32, 6>(0.2f, 0.75f, 1.6f, 2.8f, 4.55f, 7.3f);\n            let _e152 = indexable_1[(_e149 - 1i)];\n            let _e153 = widest;\n            param_5 = (_e152 * _e153);\n            let _e155 = d_1;\n            param_6 = _e155;\n            let _e156 = burleyMass_u0028_f1_u003b_vf3_u003b((&param_5), (&param_6));\n            w = (_e148 - _e156);\n            side = -1i;\n            loop {\n                let _e158 = side;\n                if (_e158 <= 1i) {\n                    let _e160 = vUv_1;\n                    let _e162 = unnamed.uStep;\n                    let _e163 = side;\n                    let _e165 = i;\n                    indexable_2 = array<f32, 7>(0f, 0.4f, 1.1f, 2.1f, 3.5f, 5.6f, 9f);\n                    let _e167 = indexable_2[_e165];\n                    let _e169 = pixels;\n                    uv = (_e160 + (_e162 * ((f32(_e163) * _e167) * _e169)));\n                    let _e173 = uv;\n                    let _e174 = textureSampleLevel(uSkin_t, uSkin_s, _e173, 0f);\n                    tap = _e174;\n                    let _e175 = uv;\n                    let _e176 = textureSampleLevel(uDepth_t, uDepth_s, _e175, 0f);\n                    param_7 = _e176.x;\n                    let _e178 = viewZ_u0028_f1_u003b((&param_7));\n                    tapZ = abs(_e178);\n                    let _e180 = tapZ;\n                    let _e181 = z;\n                    let _e184 = widest;\n                    keep = clamp((1f - (abs((_e180 - _e181)) / (4f * _e184))), 0f, 1f);\n                    let _e190 = tap[3u];\n                    let _e192 = own[3u];\n                    cover = clamp((_e190 / _e192), 0f, 1f);\n                    let _e195 = tap;\n                    let _e197 = w;\n                    let _e199 = keep;\n                    let _e201 = sum;\n                    sum = (_e201 + ((_e195.xyz * _e197) * _e199));\n                    let _e203 = w;\n                    let _e204 = cover;\n                    let _e205 = keep;\n                    let _e208 = weight;\n                    weight = (_e208 + (_e203 * (_e204 * _e205)));\n                    continue;\n                } else {\n                    break;\n                }\n                continuing {\n                    let _e210 = side;\n                    side = (_e210 + 2i);\n                }\n            }\n            continue;\n        } else {\n            break;\n        }\n        continuing {\n            let _e212 = i;\n            i = (_e212 + 1i);\n        }\n    }\n    let _e214 = sum;\n    let _e215 = weight;\n    let _e216 = (_e214 / _e215);\n    let _e218 = own[3u];\n    fragColor = vec4<f32>(_e216.x, _e216.y, _e216.z, _e218);\n    return;\n}\n\n@fragment \nfn main(@location(0) vUv: vec2<f32>) -> @location(0) vec4<f32> {\n    vUv_1 = vUv;\n    main_1();\n    let _e3 = fragColor;\n    return _e3;\n}\n";
+
+/**
+ * What the transform assigned, so the renderer binds the same numbers.
+ *
+ * A permuted shader has one entry per variant, keyed as `FLAT_FRAG_WGSL` is.
+ */
+export const SKINBLUR_BINDINGS = {
+  "SKIN_BLUR_FRAG": {
+    "uniforms": 1,
+    "uniformSize": 176,
+    "fields": {
+      "uStep": {
+        "offset": 0,
+        "size": 8,
+        "type": "vec2"
+      },
+      "uDepthToViewZ": {
+        "offset": 16,
+        "size": 16,
+        "type": "vec4"
+      },
+      "uFocal": {
+        "offset": 32,
+        "size": 4,
+        "type": "float"
+      },
+      "uProfiles": {
+        "offset": 48,
+        "size": 128,
+        "type": "vec4",
+        "length": 8,
+        "stride": 16
+      }
+    },
+    "textures": {
+      "uSkin": {
+        "texture": 32,
+        "sampler": 33,
+        "type": "sampler2D"
+      },
+      "uDepth": {
+        "texture": 34,
+        "sampler": 35,
+        "type": "sampler2D"
+      }
+    }
+  }
+} as const;

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/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/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);
+}

package/src/render/skinnedClothRun.ts

@@ -0,0 +1,128 @@
+/**
+ * A skinned cloth for a renderer: `@driftengine/physics`' solver, run as compute on WebGPU — the
+ * particles never leave the device — and as `SkinnedCloth` on the CPU under WebGL2, which has no
+ * compute. One schedule, `ClothControl`, and the same kernels either way; what a frame draws is
+ * `particles`, through `setCloth(binding, cloth.particles)`.
+ *
+ * **A function rather than renderer methods, so a game pays for it only by importing it.** See
+ * `backend/webgpu/computeHost.ts` for the door it reaches the device through, and why.
+ *
+ * **The CPU fallback's cost**, measured on a desktop part: a few hundred particles are a
+ * millisecond a frame on the main thread, and 4,500 are twenty — a garment that size wants the
+ * device. The device solver ran 4,500 particles in 0.65 ms a frame, most of it the dispatches
+ * rather than the particles (`demo/dev/skinnedCloth.html?bench=1`).
+ */
+import { SkinnedCloth } from '@driftengine/physics';
+import type { SkinnedClothSetup } from '@driftengine/physics';
+
+import type { ClothParticlesHandle, RendererApi } from './backend/api.ts';
+import { computeHostOf } from './backend/webgpu/computeHost.ts';
+import type { ComputeHost } from './backend/webgpu/computeHost.ts';
+import { GpuSkinnedCloth } from './backend/webgpu/gpuSkinnedCloth.ts';
+
+/** A garment a renderer solves, from `createSkinnedCloth`. */
+export interface SkinnedClothSolver {
+  /** What `setCloth(binding, particles)` draws the garment's bound meshes by. */
+  readonly particles: ClothParticlesHandle;
+  /** Where the solver runs: on the device, or on the CPU beneath a backend without compute. */
+  readonly runsOn: 'device' | 'cpu';
+  /**
+   * One frame: the rig's pose — each joint's global matrix, model space, sixteen floats a joint,
+   * and the model matrix — and `dt` seconds, run as whole fixed steps; the particles at the frame's
+   * `alpha` are then what the frame draws. **Once a frame, before the draws**, as
+   * `updateClothParticles` is: a second in one frame would reach every draw of it on WebGPU.
+   */
+  step(globals: Float32Array, model: Float32Array, dt: number): void;
+  /**
+   * The air the cloth drags toward from the next step, world space, metres a second: the frame's
+   * sample of the scene's one `WindField`, so a garment moves with everything else in the air.
+   */
+  setWind(x: number, y: number, z: number): void;
+  /** Back to the skinned pose, settled, as a teleport resets it. */
+  reset(): void;
+  dispose(): void;
+}
+
+/** A garment for `renderer`, from a set-up checked by name. */
+export function createSkinnedCloth(
+  renderer: RendererApi,
+  setup: SkinnedClothSetup,
+): SkinnedClothSolver {
+  const host = computeHostOf(renderer);
+  return host === null ? new CpuCloth(renderer, setup) : new DeviceCloth(host, setup);
+}
+
+class DeviceCloth implements SkinnedClothSolver {
+  readonly runsOn = 'device';
+  readonly particles: ClothParticlesHandle;
+  private readonly cloth: GpuSkinnedCloth;
+
+  constructor(
+    private readonly host: ComputeHost,
+    setup: SkinnedClothSetup,
+  ) {
+    this.cloth = new GpuSkinnedCloth(host.device(), setup);
+    this.particles = this.cloth.particles;
+  }
+
+  step(globals: Float32Array, model: Float32Array, dt: number): void {
+    if (this.host.lost()) return;
+    this.cloth.advance(globals, model, dt, this.host.changeFrame());
+  }
+
+  setWind(x: number, y: number, z: number): void {
+    this.cloth.setWind(x, y, z);
+  }
+
+  reset(): void {
+    if (this.host.lost()) return;
+    this.cloth.reset();
+  }
+
+  /** Its buffers at once — its work is submitted — and its textures with the frame's. */
+  dispose(): void {
+    this.cloth.dispose();
+    this.host.retire(this.cloth.particles.textures);
+  }
+
+  /** The particles where the last step left them: the parity check's door, waits on the device. */
+  read(): Promise<Float32Array> {
+    return this.cloth.read();
+  }
+}
+
+class CpuCloth implements SkinnedClothSolver {
+  readonly runsOn = 'cpu';
+  readonly particles: ClothParticlesHandle;
+  private readonly cloth: SkinnedCloth;
+  /** The frame's particles at `alpha`, before they go up. */
+  private readonly staging: Float32Array;
+
+  constructor(
+    private readonly renderer: RendererApi,
+    setup: SkinnedClothSetup,
+  ) {
+    this.cloth = new SkinnedCloth(setup);
+    this.particles = renderer.createClothParticles(this.cloth.count);
+    this.staging = new Float32Array(this.cloth.count * 3);
+  }
+
+  step(globals: Float32Array, model: Float32Array, dt: number): void {
+    this.cloth.setPose(globals, model);
+    this.cloth.advance(dt);
+    this.cloth.interpolate(this.cloth.alpha, this.staging);
+    this.renderer.updateClothParticles(this.particles, this.staging);
+  }
+
+  setWind(x: number, y: number, z: number): void {
+    this.cloth.setWind(x, y, z);
+  }
+
+  reset(): void {
+    this.cloth.reset();
+  }
+
+  dispose(): void {
+    this.renderer.disposeClothParticles(this.particles);
+  }
+}