@driftengine/core 4.8.2 → 4.8.4

package/dist/render/globalMediumPass.js

@@ -4,6 +4,7 @@ import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
 import { MEDIUM_FRAG, MEDIUM_UPSAMPLE_FRAG } from './shaders/globalMedium.js';
+import { blendCovering, blendTransmitting } from './sceneCoverage.js';
 /**
  * The global participating medium on WebGL2: a half-res march, then a depth-aware composite.
  *
@@ -200,7 +201,7 @@ export class GlobalMediumPass {
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.enable(gl.BLEND);
-        gl.blendFuncSeparate(gl.ONE, gl.SRC_ALPHA, gl.ZERO, gl.ONE);
+        blendTransmitting(gl, gl.ONE, gl.SRC_ALPHA);
         gl.useProgram(this.upsample);
         gl.bindVertexArray(this.vao);
         gl.activeTexture(gl.TEXTURE0);
@@ -220,7 +221,7 @@ export class GlobalMediumPass {
         gl.activeTexture(gl.TEXTURE0);
         gl.bindTexture(gl.TEXTURE_2D, null);
         /* Back to the blend every other pass in this renderer assumes it inherits. */
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.disable(gl.BLEND);
         gl.depthMask(true);
         gl.enable(gl.DEPTH_TEST);

package/dist/render/hairLobes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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 declare const HAIR_F0: number;
+/**
+ * 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 declare 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 declare const HAIR_SCATTER_SPHERE = 1.33;
+/** A longitudinal lobe: a normalised Gaussian of width `beta` at `x` from its centre. */
+export declare function hairLongitudinal(beta: number, x: number): number;
+/** Schlick's Fresnel for the strand at a cosine, clamped to the unit interval. */
+export declare function hairFresnel(cosine: number): number;
+/** Where `hairLight` leaves its answer: R, then TT, TRT and the scatter, each a colour. */
+export declare const HAIR_OUT: {
+    readonly r: 0;
+    readonly tt: 1;
+    readonly trt: 4;
+    readonly scatter: 7;
+    readonly length: 10;
+};
+/**
+ * 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 declare 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;

package/dist/render/hairLobes.js

@@ -0,0 +1,120 @@
+/** 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, x) {
+    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) {
+    const c = 1 - Math.min(Math.max(cosine, 0), 1);
+    return HAIR_F0 + (1 - HAIR_F0) * c * c * c * c * c;
+}
+function dot(a, b) {
+    return (a[0] * b[0] +
+        a[1] * b[1] +
+        a[2] * b[2]);
+}
+const clamp = (x, low, high) => 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 };
+/**
+ * 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, toLight, toEye, fibre, roughness, shift, scatter, backlit, sourceRadius, dist, out) {
+    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] - sinI * tangent[c];
+        const vp = toEye[c] - sinO * tangent[c];
+        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] - tangent[0] * sinO;
+    let across1 = toEye[1] - tangent[1] * sinO;
+    let across2 = toEye[2] - tangent[2] * sinO;
+    const acrossLength = Math.hypot(across0, across1, across2);
+    if (acrossLength > 1e-4) {
+        across0 /= acrossLength;
+        across1 /= acrossLength;
+        across2 /= acrossLength;
+    }
+    const wrapped = clamp((across0 * toLight[0] +
+        across1 * toLight[1] +
+        across2 * toLight[2] +
+        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;
+    }
+}

package/dist/render/lightBudget.d.ts

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

package/dist/render/lightBudget.js

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

package/dist/render/lineBatch.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { LINE_FRAG, LINE_VERT } from './shaders/line.js';
 import { buildSegmentQuads, expandLineSegments } from './segmentQuads.js';
+import { blendCovering, blendKeeping } from './sceneCoverage.js';
 /**
  * One draw call for a polyline with a real width — an audio waveform, a trail, a plotted
  * curve, anything that is a stroke rather than a surface.
@@ -96,7 +97,10 @@ export class LineBatch {
         if (segmentCount === 0)
             return;
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, additive ? gl.ONE : gl.ONE_MINUS_SRC_ALPHA);
+        if (additive)
+            blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
+        else
+            blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.depthMask(false);
         // The quad billboards toward the view direction the same way a bolt's does — see
         // `line.ts`'s own `cross(dir, view)` — so its winding can flip with the camera exactly

package/dist/render/mesh.d.ts

@@ -56,8 +56,15 @@ export declare class Mesh {
     readonly bounds: Bounds;
     /** Whether this mesh carries a rig, which decides which flat program draws it. */
     readonly isSkinned: boolean;
+    /**
+     * Whether its rig moves a vertex by eight influences rather than four, which decides whether the
+     * skinned program it takes is built with `SKIN_EIGHT` on. See `skinning.ts`.
+     */
+    readonly isSkinnedEight: boolean;
     /** Whether it has texture coordinates, without which a material's maps read one texel. */
     readonly hasUvs: boolean;
+    /** How many vertices it has, which a cloth binding is checked against. */
+    readonly vertexCount: number;
     /**
      * This mesh's morph deltas, or null for geometry that does not deform.
      *

package/dist/render/mesh.js

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

package/dist/render/oitPass.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
 import { OIT_RESOLVE_FRAG } from './shaders/oitResolve.js';
+import { blendTransmitting } from './sceneCoverage.js';
 /**
  * Order-independent transparency on WebGL2: two targets, two passes over the same geometry, and a
  * resolve.
@@ -163,7 +164,7 @@ export class OitPass {
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.ONE_MINUS_SRC_ALPHA, gl.SRC_ALPHA);
+        blendTransmitting(gl, gl.ONE_MINUS_SRC_ALPHA, gl.SRC_ALPHA);
         gl.useProgram(this.program);
         gl.activeTexture(gl.TEXTURE0);
         gl.bindTexture(gl.TEXTURE_2D, this.accum);

package/dist/render/particleBatch.js

@@ -1,6 +1,7 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { particleShaders } from './particleMaterial.js';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from './shaders/particle.js';
+import { blendCovering, blendKeeping } from './sceneCoverage.js';
 /** Corners of one blade, as a triangle-strip-friendly quad. */
 const CORNERS = [
     [-1, -1],
@@ -138,9 +139,9 @@ export class ParticleBatch {
             return;
         gl.enable(gl.BLEND);
         if (this.blend === 'additive')
-            gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+            blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
         else
-            gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+            blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.bindVertexArray(this.vao);

package/dist/render/particlePool.d.ts

@@ -19,7 +19,11 @@ import type { Vec3 } from '../math/color.ts';
 export interface ParticleInstances {
     /** World position, three floats each. */
     positions: Float32Array;
-    /** Metres across, and radians of roll about the particle's own axis. */
+    /**
+     * Metres from the centre to an edge, a half-width: the quad spans twice this. Then radians of
+     * roll about the particle's own axis. This said metres across until 4.8.3, and a caller who took
+     * it at its word drew every particle twice as wide as meant.
+     */
     sizes: Float32Array;
     spins: Float32Array;
     /** Linear colour, three floats each. */
@@ -54,7 +58,7 @@ export interface ParticlePoolOptions {
     capacity: number;
     /** Seconds a particle lives. */
     lifeSec: number;
-    /** Size at birth and at death, metres. */
+    /** Size at birth and at death: metres from the centre to an edge, so the quad is twice as wide. */
     sizeStart: number;
     sizeEnd: number;
     /** Colour at birth and at death. */

package/dist/render/plumeRenderer.js

@@ -3,6 +3,7 @@ import { compileProgram, uniformLocations } from './shader.js';
 import { bindAtmosphere } from './atmosphere.js';
 import { plumeShaders } from './plumeMaterial.js';
 import { buildPlumeGeometry } from './plumeGeometry.js';
+import { blendCovering, blendKeeping } from './sceneCoverage.js';
 /* The shared count, so both backends step a plume's vertices the same way. */
 const VERTS_PER_PLUME = PLUME_VERTS;
 export class PlumeRenderer {
@@ -123,9 +124,9 @@ export class PlumeRenderer {
         bindAtmosphere(gl, u, atmosphere, atmosphereCameraY, underwaterEnabled);
         gl.enable(gl.BLEND);
         if (this.blend === 'additive')
-            gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+            blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
         else
-            gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+            blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.depthMask(false);
         gl.disable(gl.CULL_FACE);
         gl.bindVertexArray(this.vao);

package/dist/render/recon/motionVectors.d.ts

@@ -42,9 +42,11 @@ export declare function cameraMotion(reprojection: ArrayLike<number>, u: number,
  */
 export declare function objectMotion(currentClip: ArrayLike<number>, previousClip: ArrayLike<number>, out: Float32Array): boolean;
 /**
- * A vertex through a skin palette: the four joints' matrices weighted and summed, then applied —
+ * A vertex through a skin palette: the joints' matrices weighted and summed, then applied —
  * `SKINNING_GLSL`'s `skinMatrix()` times the position, in model space, before the model matrix.
- * `palette` is sixteen floats a joint, column-major. Written into `out`, four values.
+ * `palette` is sixteen floats a joint, column-major. `joints` and `weights` hold four influences, or
+ * eight for a mesh with a second set (the first set then the second, as the shader reads them with
+ * `SKIN_EIGHT` on). Written into `out`, four values.
  */
 export declare function skinVertex(palette: ArrayLike<number>, joints: ArrayLike<number>, weights: ArrayLike<number>, position: ArrayLike<number>, out: Float64Array): void;
 /**

package/dist/render/recon/motionVectors.js

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

package/dist/render/renderQuality.d.ts

@@ -14,8 +14,14 @@
  * `aces` adds filmic tone mapping before that, rolling highlights off instead of
  * clipping them flat. Together they are what three.js does by default, which is why a
  * world ported from it looks wrong until this exists.
+ *
+ * `shoulder` keeps sRGB's midtones exactly and eases only the highlights: past 0.8 the brightest
+ * channel rolls toward 1 and the other two are scaled with it, so an overbright red spark stays
+ * red where `srgb` clips each channel and turns its core pink and wide. It is the curve a ported
+ * game's own resolve applied — for a port that has to match one — and it has none of ACES's toe or
+ * desaturation. See `HIGHLIGHT_SHOULDER_GLSL` for the arithmetic.
  */
-export type OutputTransform = 'none' | 'srgb' | 'aces';
+export type OutputTransform = 'none' | 'srgb' | 'aces' | 'shoulder';
 /**
  * The three settings whose accepted values are a closed set, written as one.
  *
@@ -31,6 +37,8 @@ export type DirectionalShadowDepthLayers = 1 | 2;
 export type WaterReflectionFilterTaps = 1 | 5 | 9;
 /** How light through glass is coloured: see `RenderQuality.glassShadows`. */
 export type GlassShadows = 'full' | 'half' | 'off';
+/** How light scattered beneath skin is drawn: see `RenderQuality.skinScattering`. */
+export type SkinScattering = 'pre-integrated' | 'screen-space';
 export interface RenderQuality {
     /**
      * The transfer curve applied at the end of every shaded pass.
@@ -60,7 +68,8 @@ export interface RenderQuality {
      * chooses is a look rather than a standard — three.js uses 1/0.6 and says so. This
      * engine holds no opinion and takes the number from whoever is authoring the world, so
      * that matching another renderer, or simply preferring a different grade, is a setting
-     * rather than a patch. Ignored when `outputTransform` is not `aces`.
+     * rather than a patch. Scales into `aces` and into `shoulder`, the two curves; ignored by
+     * `none` and `srgb`, which have none.
      */
     readonly outputExposure: number;
     /**
@@ -194,6 +203,24 @@ export interface RenderQuality {
      * lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
      */
     readonly glassShadows: GlassShadows;
+    /**
+     * How light that scatters beneath skin is drawn, for a material whose model is `skinModel`.
+     *
+     * **`'pre-integrated'`, the default**: the lit stage's fit alone — a terminator softened and
+     * reddened by the surface's curvature, light through thin parts, a penumbra each channel crosses
+     * as far as it travels — at no cost beyond the skin pipeline itself. **`'screen-space'`** adds
+     * Burley's blur in the picture as well: a skin draw writes its diffuse to a target of its own (it
+     * is drawn twice to do so), which is spread across the pixels its scatter distance covers and
+     * added back before anything blended is drawn, so light crosses a shadow's edge and a nostril's
+     * rim in the picture rather than in a fit. See `skinBlur.ts`.
+     *
+     * Construction-time: two half-float targets the size of the frame, and a multisampled one under
+     * multisampling, made at the first skin draw. It needs the composite (`screenEffects`), which is
+     * where the frame is still linear light to add to; without one, skin is pre-integrated and the
+     * renderer says so once. What would make the default wrong is a close-up face that reads as wax
+     * at a shadow's edge — that is what the blur is for.
+     */
+    readonly skinScattering: SkinScattering;
     /** Horizontal world-space reach over which a directional shadow dissolves. */
     readonly directionalShadowMaxDistance: number;
     /** Maximum horizontal projection per vertical metre before low-angle shadows vanish. */

package/dist/render/renderQuality.js

@@ -63,6 +63,7 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     lightVolumeSamples: 32,
     directionalShadowDepthLayers: 2,
     glassShadows: 'full',
+    skinScattering: 'pre-integrated',
     directionalShadowMaxDistance: 6,
     directionalShadowMaxSlope: 3,
     pointShadowRebakeDistance: 0.001,
@@ -215,6 +216,7 @@ export function resolveRenderQuality(options = {}) {
         lightVolumeSamples: options.lightVolumeSamples ?? DEFAULT_RENDER_QUALITY.lightVolumeSamples,
         directionalShadowDepthLayers: options.directionalShadowDepthLayers ?? DEFAULT_RENDER_QUALITY.directionalShadowDepthLayers,
         glassShadows: options.glassShadows ?? DEFAULT_RENDER_QUALITY.glassShadows,
+        skinScattering: options.skinScattering ?? DEFAULT_RENDER_QUALITY.skinScattering,
         directionalShadowMaxDistance: options.directionalShadowMaxDistance ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxDistance,
         directionalShadowMaxSlope: options.directionalShadowMaxSlope ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxSlope,
         pointShadowRebakeDistance: options.pointShadowRebakeDistance ?? DEFAULT_RENDER_QUALITY.pointShadowRebakeDistance,
@@ -312,6 +314,9 @@ export function resolveRenderQuality(options = {}) {
         quality.glassShadows !== 'off') {
         throw new Error(`RenderQuality.glassShadows must be 'full', 'half' or 'off', got ${String(quality.glassShadows)}`);
     }
+    if (quality.skinScattering !== 'pre-integrated' && quality.skinScattering !== 'screen-space') {
+        throw new Error(`RenderQuality.skinScattering must be 'pre-integrated' or 'screen-space', got ${String(quality.skinScattering)}`);
+    }
     if (quality.plumeNoiseOctaves > 3) {
         throw new Error(`RenderQuality.plumeNoiseOctaves must be <= 3, got ${quality.plumeNoiseOctaves}`);
     }

package/dist/render/rendererHarness.js

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

package/dist/render/sceneCoverage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * What a blended draw into the scene does to its alpha, which holds how much of each pixel is still
+ * the opaque surface — the share ambient occlusion is allowed to darken.
+ *
+ * **Occlusion is applied in the composite, from the depth the opaque world left**, after every
+ * translucent draw has landed, and a particle or a pane writes no depth: so a puff of smoke in front
+ * of a wall was darkened by the corner behind it. Reported from a game as walls and two figures
+ * standing behind a cloud showing through it as outlines, and nothing at all with occlusion off.
+ *
+ * So the scene's alpha is a running share. The frame clears it to 1 and an opaque draw writes 1,
+ * which is the whole of the surface; then each draw blended in front of it says which of three
+ * things it is, and the composite darkens `share` of the pixel and leaves the rest:
+ *
+ * - **It covers**: glass, smoke, water, a line, text in the world, a panel. The share falls by what
+ *   the draw lets through, `share * (1 - a)`.
+ * - **It transmits**: the medium, the order-independent composite. Its alpha already *is* what gets
+ *   through, `share * a`.
+ * - **It keeps**: light added to the surface or a layer of the surface itself — caustics, a light
+ *   volume, a bolt, a wet film, a decal, a reflection. The share is unchanged.
+ *
+ * **What it gives up** is added light in front of an occluded corner: a glow or a spark adds to the
+ * pixel and keeps the share, so the composite darkens what it added along with the surface — which
+ * is how every blended draw behaved before this, and one multiply cannot tell the two apart. **What
+ * would make it wrong** is an opaque pass writing an alpha below 1: its surface would then take less
+ * occlusion than it should, which is the safe direction, and is the lit shader's own case at a
+ * cutout's edge or under a per-vertex alpha lane.
+ *
+ * **It survives the temporal passes.** A temporal resolve passes the frame's alpha through, since
+ * it is a fact about this frame and takes no history; a reconstruction reads it from the scene it
+ * rebuilt into the picture it shows, and the blended draws that land after it cover that picture.
+ *
+ * **One pipeline does not take part**: the GPU-driven pass blends its own surfaces into a target
+ * whose alpha is the mask its blit reads to tell a drawn pixel from an undrawn one, and that blit
+ * writes the share back to 1. Its panes still take the occlusion of what they cover. What would
+ * close it is a channel for that mask other than alpha.
+ *
+ * A contributed pass drawing something blended into the scene states the same thing for its own
+ * pipeline with `SCENE_ALPHA_COVERS`, `SCENE_ALPHA_TRANSMITS` or `SCENE_ALPHA_KEEPS`.
+ */
+/** A blended draw that covers the surface by its alpha: `share * (1 - a)`. */
+export declare const SCENE_ALPHA_COVERS: GPUBlendComponent;
+/** A draw whose alpha is what gets through it, a transmittance or a revealage: `share * a`. */
+export declare const SCENE_ALPHA_TRANSMITS: GPUBlendComponent;
+/** Light added to the surface, or a layer of it: the share unchanged. */
+export declare const SCENE_ALPHA_KEEPS: GPUBlendComponent;
+/**
+ * The same three on WebGL2, as the alpha half of `blendFuncSeparate` beside the colour half a
+ * caller already had. `src` and `dst` are the colour factors.
+ */
+export declare function blendCovering(gl: WebGL2RenderingContext, src: number, dst: number): void;
+/** `SCENE_ALPHA_TRANSMITS` on WebGL2, beside the colour factors `src` and `dst`. */
+export declare function blendTransmitting(gl: WebGL2RenderingContext, src: number, dst: number): void;
+/** `SCENE_ALPHA_KEEPS` on WebGL2, beside the colour factors `src` and `dst`. */
+export declare function blendKeeping(gl: WebGL2RenderingContext, src: number, dst: number): void;