@volter/blender-engine 0.1.148 → 0.1.149

package/browser/three/blender-runtime-weights.ts

@@ -1,30 +1,7 @@
-/**
- * THE WEIGHT OVERLAY — the active vertex group's weights, coloured with
- * Blender's own ramp (ARCHITECTURE-CORE §Blender north star, "Inspection
- * parity, not editing parity" and "The reference is Blender's SOURCE as well
- * as its frames"; WORK.md §Blender in the tab is Blender, "Inspection parity",
- * I4).
- *
- * IT IS INSPECTION, NOT PAINT MODE. Blender shows these colours by entering
- * Weight Paint; here it is a viewport overlay toggle beside Bones, because the
- * Model document has no brushes to enter a paint mode for and looking at the
- * weights is the whole point.
- *
- * WHICH RAMP, and the correction it cost. The brief for this unit named
- * `BKE_defvert_weight_to_rgb` / `weight_to_rgb`
- * (`blenkernel/intern/deform.cc:1559-1590`) — the blue → cyan → green →
- * yellow → red piecewise ramp. MEASURED at the engine's pin, that function is
- * NOT what paints a vertex group: its only callers in the whole tree are
- * `blenkernel/intern/particle.cc:3602,3624-3625`, the HAIR KEY weight colour.
- * The weight-paint viewport samples a 256-texel 1D table built in
- * `draw/engines/overlay/overlay_instance.cc:186-221`, and that table is an HSV
- * sweep with a gamma correction — a different curve with the same endpoints,
- * which is why the two look alike until you compare mid-tones. This file is
- * the table Blender actually samples; the piecewise ramp is named here so the
- * next reader does not "fix" it back.
- */
+
 import * as THREE from 'three';
 import { z } from 'zod';
+import { bytesFromBase64 } from './blender-base64';
 
 /** What `session.py`'s `_weights` answers. `weightsBase64` / `alertBase64` are
  *  absent on a REFERENCE (`unchanged`), which is the same contract the meshes
@@ -36,10 +13,8 @@ export const weightsSchema = z
     group: z.string(),
     groupIndex: z.number().int().nonnegative(),
     count: z.number().int().nonnegative(),
-    /** sha1 of the packed weight + alert bytes. The reference key, and the
-     *  presenter's staleness signal — never the mesh's revision, which does
-     *  NOT move when only deform weights change (`session.py::_weights` states
-     *  the measurement). */
+    /** sha1 of the packed weight and alert bytes: the reference key and
+     *  staleness signal, independent of mesh geometry revisions. */
     digest: z.string(),
     /** `scene.tool_settings.vertex_group_user` (`rna_scene.cc:3428-3434`). */
     alertMode: z.enum(['NONE', 'ACTIVE', 'ALL']),
@@ -126,27 +101,9 @@ function hueToRgb(hue: number): [number, number, number] {
   }
 }
 
-/**
- * `TH_VERTEX_UNREFERENCED`, the colour a zero-weight vertex is painted
- * (`overlay_paint_weight_frag.glsl:98-100`, `mix(weight_color,
- * color_unreferenced, alert * alert)` at alert 1).
- *
- * MEASURED: `vertex_unreferenced` appears NOWHERE in
- * `release/datafiles/userdef/userdef_default_theme.c` — the only mention of
- * the member in the whole checkout is its RNA declaration
- * (`rna_userdef.cc:3104`). The default theme therefore leaves the struct's
- * zero standing, which is BLACK, and black is what Blender draws for an
- * unweighted vertex. Stated rather than eyedropped.
- */
+/** TH_VERTEX_UNREFERENCED is black: Blender’s default theme leaves that member zero. */
 export const VERTEX_UNREFERENCED = 0x000000;
 
-function bytesFrom(base64: string): Uint8Array {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes;
-}
-
 /**
  * THE OVERLAY: the painted object's own geometry, drawn again in the weight
  * colours.
@@ -173,34 +130,14 @@ export class WeightOverlay {
     this.group.name = 'BlenderWeightOverlay';
   }
 
-  /**
-   * Draw the weights over `source`, the presented mesh of the painted object.
-   * `null` weights (no active vertex group, no active mesh) clears it.
-   *
-   * `objectMatrix` is the object's matrix in BLENDER's frame — the frame's own
-   * `objects[].matrix`, exactly as the armature overlay takes it, and NOT the
-   * presented mesh's `matrixWorld`. Measured live 2026-09-19: `matrixWorld`
-   * already carries the model root's Z-up permutation, and this group carries
-   * it too, so the drawing landed with the permutation applied TWICE — the
-   * Body's colours lay flat on the floor beside the standing cylinder.
-   *
-   * Returns the warning this drawing could not honour, or null.
-   */
+  /** Draw active-group weights over source, or clear the drawing for null weights. objectMatrix is objects[].matrix in Blender coordinates, before the model root’s Z-up conversion. Return an unsupported-drawing warning or null. */
   apply(
     weights: BlenderWeights | null,
     source: THREE.Mesh | null,
     objectMatrix: THREE.Matrix4 | null,
   ): string | null {
     if (weights === null || source === null || !source.isMesh || objectMatrix === null) {
-      // THE DRAWING GOES, THE ARRAY STAYS. Dropping `held` here is what the
-      // walk caught (2026-09-19): `_weights` answers null whenever the active
-      // object is not a mesh — entering POSE MODE on the rig is enough — while
-      // the session's `_known` still records the array as sent, so the next
-      // frame that names the Body again ships a REFERENCE to bytes this side
-      // had just thrown away, and the colours never came back. The array is
-      // still the truth about that object's group; only the drawing is stale.
-      // It is the same rule the meshes follow: a presenter holds its geometry
-      // until the SESSION replaces it, never until a frame stops mentioning it.
+      // Clear the drawing while retaining received weight arrays. The session may refer to those bytes again until it replaces them.
       this.clear();
       this.signature = '';
       return null;
@@ -222,11 +159,11 @@ export class WeightOverlay {
         this.clear();
         return `weights: ${key} carried neither an array nor a reference`;
       }
-      const raw = bytesFrom(weights.weightsBase64);
+      const raw = bytesFromBase64(weights.weightsBase64);
       this.held = {
         key,
         weights: new Float32Array(raw.buffer, raw.byteOffset, weights.count),
-        alerts: bytesFrom(weights.alertBase64),
+        alerts: bytesFromBase64(weights.alertBase64),
       };
     }
     const held = this.held;

package/browser/three/blender-sky.ts

@@ -1,19 +1,4 @@
-/**
- * Blender's scattering skies, transcribed from the pinned source.
- *
- * `intern/sky/source/sky_multiple_scattering.cpp` precomputes a 512x256 XYZ
- * texture and `gpu_shader_material_tex_sky.glsl`'s `node_tex_sky_nishita` reads
- * it back per direction; both halves are here because both are what a script
- * sees through `ShaderNodeTexSky`. The single-scattering atmosphere is in
- * `blender-single-scattering-sky.ts`; model selection, caching and the shared
- * GPU lookup convention live here. Each model keeps its own native elevation
- * and azimuth conventions.
- *
- * The constants and the arithmetic are the source's. The XYZ-to-scene-linear
- * matrix is not in the source -- it comes from the colour configuration -- and
- * was measured off the oracle by round-tripping an EXR through
- * `Linear CIE-XYZ D65`.
- */
+/** Blender scattering skies from the pinned source. Multiple scattering uses a precomputed XYZ texture; single scattering lives in blender-single-scattering-sky.ts. This module selects models, caches results and converts XYZ into scene-linear colour. */
 import * as THREE from 'three';
 import {precomputeSingleScatteringSky, precomputeSingleScatteringSun} from './blender-single-scattering-sky';
 
@@ -53,8 +38,7 @@ const SPECTRAL_XYZ = [
   [20.762668673810577145, 2.3614213523314368527, 110.48009643252140334],
 ];
 
-/** `IMB_colormanagement_get_xyz_to_scene_linear()`, measured on the oracle by
- *  loading an EXR of the three basis vectors as `Linear CIE-XYZ D65`. */
+/** XYZ-to-scene-linear matrix from EXR basis-vector conversion through Linear CIE-XYZ D65. */
 const XYZ_TO_RGB = [
   [3.2409698963165283, -1.5373831987380981, -0.49861079454421997],
   [-0.969243586063385, 1.8759675025939941, 0.041555099189281464],
@@ -102,11 +86,11 @@ const aerosolDensity = (h: number): number =>
   (Math.exp(-h / AEROSOL_HEIGHT_SCALE) + AEROSOL_BACKGROUND_DENSITY / AEROSOL_BASE_DENSITY);
 
 export interface SkyParameters {
-  /** Omitted in older frames, whose only supported model was multiple scattering. */
-  model?: 'SINGLE_SCATTERING' | 'MULTIPLE_SCATTERING';
-  sunDisc?: boolean | undefined;
-  sunSize?: number | undefined;
-  sunIntensity?: number | undefined;
+  /** Sky model selected by the frame. */
+  model: 'SINGLE_SCATTERING' | 'MULTIPLE_SCATTERING';
+  sunDisc: boolean;
+  sunSize: number;
+  sunIntensity: number;
   sunElevation: number;
   sunRotation: number;
   altitude: number;
@@ -357,13 +341,9 @@ function precomputeTexture(p: SkyParameters, sunElevation: number): Float32Array
 }
 
 /**
- * THE 15-SECOND HALF, as a pure function of the parameters.
- *
- * `precomputeTexture` walks 512x256 texels with 64 in-scattering steps each and
- * that is where a sky's cost lives; reading it back (below) is 32,768 bilinear
- * lookups and costs milliseconds. Split out because the expensive half takes
- * numbers and returns numbers -- no THREE, no DOM -- so a WORKER can run it and
- * post the Float32Array back. See `contributions/sky-precompute-worker.ts`.
+ * Precompute sky radiance from numeric parameters without Three or DOM access.
+ * `sky-precompute-worker.ts` runs this work off the main thread
+ * and returns the Float32Array for synchronous field sampling.
  */
 export function precomputeSkyTexture(p: SkyParameters): Float32Array {
   if (p.model === 'SINGLE_SCATTERING') return precomputeSingleScatteringSky(p);
@@ -376,7 +356,7 @@ export function precomputeSkyTexture(p: SkyParameters): Float32Array {
  * single scattering keeps it as supplied to Blender's precompute. */
 export function skyTextureKey(p: SkyParameters): string {
   const elevation = p.model === 'SINGLE_SCATTERING' ? p.sunElevation : simplify(p.sunElevation, p.sunRotation)[0];
-  return JSON.stringify([p.model ?? 'MULTIPLE_SCATTERING', elevation, p.altitude, p.airDensity, p.aerosolDensity, p.ozoneDensity]);
+  return JSON.stringify([p.model, elevation, p.altitude, p.airDensity, p.aerosolDensity, p.ozoneDensity]);
 }
 
 /** Precomputed sky textures, however they were derived. `skyField` is
@@ -433,7 +413,7 @@ export function skyField(p: SkyParameters): (direction: THREE.Vector3) => THREE.
     primeSkyTexture(p, pixels);
   }
   const colour = new THREE.Vector3();
-  const diameter = p.sunSize ?? 0;
+  const diameter = p.sunSize;
   const solar = p.model === 'SINGLE_SCATTERING' && p.sunDisc && diameter > 0
     ? precomputeSingleScatteringSun(p, diameter) : null;
   const sun = skySunDirection(p);
@@ -478,7 +458,7 @@ export function skyField(p: SkyParameters): (direction: THREE.Vector3) => THREE.
       if (angle < diameter / 2) {
         const limb = 1 - .6 * (1 - Math.sqrt(Math.max(0, 1 - (angle / (diameter / 2)) ** 2)));
         const t = (dirElevation - p.sunElevation) / diameter + .5;
-        for (let i = 0; i < 3; i++) xyz[i]! += mix(solar[0][i]!, solar[1][i]!, t) * (p.sunIntensity ?? 1) * limb;
+        for (let i = 0; i < 3; i++) xyz[i]! += mix(solar[0][i]!, solar[1][i]!, t) * p.sunIntensity * limb;
       }
     }
     return colour.set(

package/browser/three/blender-triangulate.ts

@@ -1,33 +1,7 @@
 /**
- * `triangulate` — how a BMesh FACE becomes triangles, and the one place that
- * decision is made.
- *
- * A `BMesh` face is an n-gon; a `BufferGeometry` is triangles. The conversion
- * used to be a naive fan (`0,1,2`, `0,2,3`, `0,3,4`, …), which is correct for
- * a CONVEX polygon and silently wrong for a concave one: the fan's later
- * triangles fold back over the polygon's own reflex corner, so they overlap
- * each other and face BACKWARDS. That renders as a hole. It shipped as one —
- * the treasure chest's crescent lid end-cap (docs/BLENDER-PARITY.md §Driver
- * ladder, "Chest-measured gaps") — and, worse, `validate()` had nothing to say
- * about it, because every count and every winding on the BMesh side was
- * perfectly sound. The defect only existed in the export.
- *
- * So the export's triangulation is now a real one, and it is the SAME
- * function `validate` checks, which is what closes the gap: there is no way
- * for the exporter to fan something the validator did not look at.
- *
- * THE RUNG. Ear clipping is not hand-rolled here: `THREE.ShapeUtils
- * .triangulateShape` is three's own Earcut and ships in the dependency the
- * kit already has. This module supplies only the two things Earcut cannot do
- * for a 3D face — pick the plane to flatten onto, and decide whether the
- * result is trustworthy.
- *
- * THE FAN IS STILL THE FAST PATH, and deliberately so. Every face is fanned
- * FIRST and the fan is kept whenever it is sound, so every convex face — which
- * is nearly all of them, quads included — exports with byte-identical indices
- * to before this module existed. Earcut runs only where the fan actually
- * fails. That is not an optimization: it is what lets an existing model be
- * rebuilt through the fixed kit and change ONLY where it was broken.
+ * Triangulate BMesh n-gons for export and validation. Keep a fan when it covers the polygon without
+ * overlap or reversed triangles; otherwise flatten onto a suitable plane and use three’s Earcut.
+ * Both paths validate the resulting triangles against the face.
  */
 
 import * as THREE from 'three';
@@ -52,8 +26,8 @@ export interface PolygonTriangulation {
    *  no flattening of it is simple, and neither the fan nor Earcut can fix
    *  that. `validate` reports it as `overlappingTriangulation`. */
   readonly sound: boolean;
-  /** Which path produced `triangles` — `'fan'` is the untouched legacy
-   *  layout, `'earcut'` is `THREE.ShapeUtils.triangulateShape`. */
+  /** Which path produced `triangles` — `'fan'` is the fan from the first
+   *  corner, `'earcut'` is `THREE.ShapeUtils.triangulateShape`. */
   readonly method: 'fan' | 'earcut';
 }
 
@@ -64,8 +38,7 @@ export interface PolygonTriangulation {
 const AREA_TOLERANCE = 1e-6;
 
 /** The polygon's Newell area-weighted normal — the standard best-fit plane
- *  for a possibly non-planar face, and the one whose length is twice the
- *  projected area. */
+ *  for a possibly non-planar face, scaled so its length is the projected area. */
 function newellNormal(points: readonly THREE.Vector3[]): THREE.Vector3 {
   const n = new THREE.Vector3();
   for (let i = 0; i < points.length; i++) {
@@ -82,8 +55,7 @@ function newellNormal(points: readonly THREE.Vector3[]): THREE.Vector3 {
 const cross2 = (a: THREE.Vector2, b: THREE.Vector2, c: THREE.Vector2): number =>
   (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
 
-/** The consecutive fan from corner 0 — the layout every export used before
- *  this module, reproduced exactly so a sound fan stays byte-identical. */
+/** Consecutive triangle fan from corner 0. */
 const fanOf = (n: number): TriangleIndices[] =>
   Array.from({ length: n - 2 }, (_, i) => [0, i + 1, i + 2] as const);
 

package/browser/three/blender-viewport-sampling.ts

@@ -0,0 +1,235 @@
+/** Viewport anti-aliasing from Blender 5.2: Workbench uses its jitter table and Blackman-Harris resolve; EEVEE uses Halton jitter and Gaussian film accumulation. The luma weight is constant at exposureScale 0. Photographs cap samples at PHOTOGRAPH_SAMPLE_MAX. */
+
+/** The most samples a photograph draws. Workbench's own maximum is 32; EEVEE's viewport can be
+ *  set past it, and 0 means it never stops. */
+export const PHOTOGRAPH_SAMPLE_MAX = 64;
+
+/** What the stage's `PhotographSampling` reads (`@volter/editor-threejs/capture/photograph-sampling`). */
+export interface BlenderPhotographSampling {
+  readonly offsets: readonly (readonly [number, number])[];
+  readonly projectionScale: number;
+  readonly reach: number;
+  readonly filter: 'blackman-harris' | 'gaussian';
+  readonly radius: number;
+  readonly accumulation: 'log2' | 'luma';
+  readonly exposureScale: number;
+  readonly backdropMerge: boolean;
+  /** Show Workbench accumulation from sample 1 and EEVEE accumulation from sample 2, where their measured edges improve on the ordinary MSAA frame. */
+  readonly liveFrom: number;
+}
+
+const f32 = Math.fround;
+
+/** `blender::RandomNumberGenerator` (drand48's constants), as `BLI_rng_new(seed)` seeds it. */
+class BlenderRng {
+  private x: bigint;
+  constructor(seed: number) {
+    this.x = (BigInt(seed >>> 0) << 16n) | 0x330en;
+  }
+  private step(): void {
+    this.x = (0x5deece66dn * this.x + 0xbn) & 0xffffffffffffn;
+  }
+  getDouble(): number {
+    this.step();
+    return Number(BigInt.asIntN(32, this.x >> 17n)) / 0x80000000;
+  }
+}
+
+function jitterate1(jit1: [number, number][], jit2: [number, number][], radius1: number): void {
+  const num = jit1.length;
+  for (let i = num - 1; i >= 0; i--) {
+    let dvecx = 0;
+    let dvecy = 0;
+    const x0 = jit1[i]![0];
+    const y0 = jit1[i]![1];
+    for (let j = num - 1; j >= 0; j--) {
+      if (i === j) continue;
+      // Single-precision, rounded after each operation as C's float arithmetic is.
+      let vecx = f32(f32(jit1[j]![0] - x0) - 1);
+      let vecy = f32(f32(jit1[j]![1] - y0) - 1);
+      for (let k = 3; k > 0; k--) {
+        for (const step of [1, 1, -2]) {
+          if (Math.abs(vecx) < radius1 && Math.abs(vecy) < radius1) {
+            let len = f32(Math.sqrt(f32(f32(vecx * vecx) + f32(vecy * vecy))));
+            if (len > 0 && len < radius1) {
+              len = f32(len / radius1);
+              dvecx = f32(dvecx + f32(vecx / len));
+              dvecy = f32(dvecy + f32(vecy / len));
+            }
+          }
+          vecx = f32(vecx + step);
+        }
+        vecy = f32(vecy + 1);
+      }
+    }
+    let x = f32(x0 - f32(dvecx / 18));
+    let y = f32(y0 - f32(dvecy / 18));
+    x = f32(x - Math.floor(x));
+    y = f32(y - Math.floor(y));
+    jit2[i] = [x, y];
+  }
+  for (let i = 0; i < num; i++) jit1[i] = [jit2[i]![0], jit2[i]![1]];
+}
+
+function jitterate2(jit1: [number, number][], jit2: [number, number][], radius2: number): void {
+  const num = jit1.length;
+  for (let i = num - 1; i >= 0; i--) {
+    let dvecx = 0;
+    let dvecy = 0;
+    const x0 = jit1[i]![0];
+    const y0 = jit1[i]![1];
+    for (let j = num - 1; j >= 0; j--) {
+      if (i === j) continue;
+      // Single-precision, rounded after each operation as C's float arithmetic is.
+      let vecx = f32(f32(jit1[j]![0] - x0) - 1);
+      let vecy = f32(f32(jit1[j]![1] - y0) - 1);
+      for (let k = 0; k < 3; k++) {
+        if (Math.abs(vecx) < radius2) dvecx = f32(dvecx + f32(vecx * radius2));
+        vecx = f32(vecx + 1);
+      }
+      for (let k = 0; k < 3; k++) {
+        if (Math.abs(vecy) < radius2) dvecy = f32(dvecy + f32(vecy * radius2));
+        vecy = f32(vecy + 1);
+      }
+    }
+    let x = f32(x0 - f32(dvecx / 2));
+    let y = f32(y0 - f32(dvecy / 2));
+    x = f32(x - Math.floor(x));
+    y = f32(y - Math.floor(y));
+    jit2[i] = [x, y];
+  }
+  for (let i = 0; i < num; i++) jit1[i] = [jit2[i]![0], jit2[i]![1]];
+}
+
+/** `BLI_jitter_init`: `num` points in the unit square, centred on (0, 0). */
+function bliJitterInit(num: number): [number, number][] {
+  const numFl = f32(num);
+  const numFlSqrt = f32(Math.sqrt(numFl));
+  const rad1 = f32(1 / numFlSqrt);
+  const rad2 = f32(1 / numFl);
+  const rad3 = f32(numFlSqrt / numFl);
+  const rng = new BlenderRng(31415926 + num);
+  const jit: [number, number][] = [];
+  let x = 0;
+  for (let i = 0; i < num; i++) {
+    const a = f32(x + f32(rad1 * f32(0.5 - rng.getDouble())));
+    const b = f32(f32(f32(i) / numFl) + f32(rad1 * f32(0.5 - rng.getDouble())));
+    jit.push([a, b]);
+    x = f32(x + rad3);
+    x = f32(x - Math.floor(x));
+  }
+  const jit2: [number, number][] = jit.map(() => [0, 0]);
+  for (let i = 0; i < 24; i++) {
+    jitterate1(jit, jit2, rad1);
+    jitterate1(jit, jit2, rad1);
+    jitterate2(jit, jit2, rad2);
+  }
+  return jit.map(([a, b]) => [f32(a - 0.5), f32(b - 0.5)]);
+}
+
+/** C's `fmodf`: the remainder carries the dividend's sign. */
+const fmod = (a: number, b: number) => a - b * Math.trunc(a / b);
+
+/** `TaaSamples::init_samples`: one of Workbench's tables, in [-1, 1) pixels-as-weighed. */
+function workbenchTable(num: number): (readonly [number, number])[] {
+  const samples = bliJitterInit(num);
+  let closest = 0;
+  let closestDistance = 1;
+  samples.forEach(([x, y], i) => {
+    const d = f32(f32(x * x) + f32(y * y));
+    if (d < closestDistance) {
+      closestDistance = d;
+      closest = i;
+    }
+  });
+  const [cx, cy] = samples[closest]!;
+  const moved = samples.map(([x, y]): [number, number] => {
+    const sx = f32(x - cx);
+    const sy = f32(y - cy);
+    return [f32(f32(fmod(f32(sx + 0.5), 1) * 2) - 1), f32(f32(fmod(f32(sy + 0.5), 1) * 2) - 1)];
+  });
+  if (closest !== 0) [moved[0], moved[closest]] = [moved[closest]!, moved[0]!];
+  for (let i = 0; i < moved.length - 2; i++) {
+    let farthest = 0;
+    let index = i;
+    for (let j = i + 1; j < moved.length; j++) {
+      const dx = moved[i]![0] - moved[j]![0];
+      const dy = moved[i]![1] - moved[j]![1];
+      const d = dx * dx + dy * dy;
+      if (d > farthest) {
+        farthest = d;
+        index = j;
+      }
+    }
+    [moved[i + 1], moved[index]] = [moved[index]!, moved[i + 1]!];
+  }
+  return moved;
+}
+
+const workbenchTables = new Map<number, (readonly [number, number])[]>();
+
+/** Workbench's sampling for a sample count (`viewport_aa` / `render_aa` as a number: 0 off,
+ *  1 the single sample its SMAA resolves alone, else 5, 8, 11, 16 or 32). Off is one centred
+ *  sample kept as it is: no accumulation, no filter (`workbench_state.cc`, `draw_aa` false). */
+export function workbenchSampling(count: number, backdropMerge: boolean): BlenderPhotographSampling {
+  if (count <= 0) {
+    return {
+      offsets: [[0, 0]], projectionScale: 0.5, reach: 0, filter: 'blackman-harris', radius: 0,
+      accumulation: 'log2', exposureScale: 1, backdropMerge, liveFrom: 1,
+    };
+  }
+  // One sample is the centre (`TaaSamples` always starts there); Workbench then SMAAs it.
+  const size = count <= 1 ? 1 : count <= 5 ? 5 : count <= 8 ? 8 : count <= 11 ? 11 : count <= 16 ? 16 : 32;
+  let offsets = workbenchTables.get(size);
+  if (!offsets) {
+    offsets = size === 1 ? [[0, 0]] : workbenchTable(size);
+    workbenchTables.set(size, offsets);
+  }
+  return {
+    offsets, projectionScale: 0.5, reach: 1, filter: 'blackman-harris', radius: 1,
+    accumulation: 'log2', exposureScale: 1, backdropMerge, liveFrom: 1,
+  };
+}
+
+/** `Sampling::sample_disk`. */
+function sampleDisk(u: number, v: number): [number, number] {
+  const omega = v * 2 * Math.PI;
+  const r = Math.sqrt(u);
+  return [r * Math.cos(omega), r * Math.sin(omega)];
+}
+
+/** Radical inverse in `base` (`BLI_halton_2d` iterates to the same value for index `n`). */
+function halton(n: number, base: number): number {
+  let result = 0;
+  let fraction = 1 / base;
+  for (let i = n; i > 0; i = Math.floor(i / base)) {
+    result += (i % base) * fraction;
+    fraction /= base;
+  }
+  return result;
+}
+
+/** EEVEE's film sampling over its viewport `taa_samples` (0: never stops) and `filter_size`. */
+export function eeveeSampling(taaSamples: number, filterSize: number): BlenderPhotographSampling {
+  const count = Math.min(PHOTOGRAPH_SAMPLE_MAX, taaSamples > 0 ? taaSamples : PHOTOGRAPH_SAMPLE_MAX);
+  // A single sample is not filtered (`Film::init`), nor is a filter under 0.01, whose one texel
+  // is taken whole (`update_sample_table`).
+  const clamped = Math.min(100, Math.max(0, filterSize));
+  const radius = count === 1 || clamped < 0.01 ? 0 : clamped;
+  const fract = (x: number) => x - Math.floor(x);
+  const offsets: (readonly [number, number])[] = [];
+  for (let s = 0; s < count; s++) {
+    const u = fract(f32(halton(s + 1, 2) + f32(1 / 2)));
+    const v = fract(f32(halton(s + 1, 3) + f32(2 / 3)));
+    // A filter under 1/sqrt(2) (0 included) jitters over a disk of half its radius (`pixel_jitter_get`).
+    if (radius < Math.SQRT1_2) {
+      const [x, y] = sampleDisk(u, v);
+      offsets.push([x * 0.5 * radius, y * 0.5 * radius]);
+    } else offsets.push([u - 0.5, v - 0.5]);
+  }
+  return {
+    offsets, projectionScale: 1, reach: Math.min(3, Math.ceil(radius)), filter: 'gaussian', radius,
+    // Exposure scale zero gives a constant luma weight.
+    accumulation: 'luma', exposureScale: 0, backdropMerge: false, liveFrom: Math.min(2, count),
+  };
+}

package/browser/three/blender-workbench-material.ts

@@ -1,26 +1,4 @@
-/**
- * BLENDER'S SOLID SHADING, as Blender computes it: `get_world_lighting` from
- * `draw/engines/workbench/shaders/workbench_world_light_lib.glsl`, transcribed line for line,
- * over the four studio lights of the factory `Default` (`SOLID_LIGHTS`, read back from Blender
- * 5.2's preferences with their specular colours) and no ambient (`light_ambient` is zero).
- *
- * Per light: a wrapped diffuse term, `(N·L + wrap) / (1 + wrap)²`; a normalized Blinn specular
- * whose gloss the wrap softens, blended toward a wrapped "environment" term by `wrap²`; a
- * Fresnel lift of the specular colour (`brdf_approx`); and energy conservation that takes the
- * specular's grey level off the diffuse. The surface is the material's VIEWPORT DISPLAY
- * (`Material.diffuse_color`, `roughness`, `metallic`), which is what Solid's MATERIAL colour type
- * reads — never its node graph.
- *
- * WHY A FUNCTION AND NOT A LIGHT RIG: three's lambert and BRDF cannot express the wrap, the
- * coupled specular or the per-light specular colour, so the four lights plus one fitted gain
- * could match the default view's three faces only by absorbing the difference, and missed a
- * face square to the view by 18 levels (143 against Blender's 161). This function, evaluated
- * offline for that face, gives 161.
- *
- * Built on `MeshLambertMaterial` so skinning, morphs and the view-space normal come with it;
- * only the final colour is replaced. Blender uses a fast reciprocal (`fast_rcp`); this uses the
- * exact one.
- */
+/** Blender Solid shading from workbench_world_light_lib.glsl with the factory studio lights and viewport display colours. Pack roughness as sqrt(Material.roughness), use Blender’s fast_rcp and respect the Specular Lighting toggle. MeshLambertMaterial supplies skinning, morphs and view-space normals. */
 import * as THREE from 'three';
 import { SOLID_LIGHTS } from './blender-runtime-lighting';
 
@@ -31,8 +9,12 @@ export interface ViewportDisplay {
   readonly metallic: number;
 }
 
-/** For a surface with no material: the factory cube's material's display, read back from Blender
- *  5.2 (grey 0.8, roughness 0.5, metallic 0). Blender's own default surface was not measured. */
+/** `Material::pack_data`'s remap of the display roughness to Disney roughness. */
+export function workbenchRoughness(display: ViewportDisplay): number {
+  return Math.sqrt(Math.min(1, Math.max(0, display.roughness)));
+}
+
+/** Default material display values: grey 0.8, roughness 0.5, metallic 0. */
 export const DEFAULT_VIEWPORT_DISPLAY: ViewportDisplay = { color: [0.8, 0.8, 0.8, 1], roughness: 0.5, metallic: 0 };
 
 const WORKBENCH_GLSL = /* glsl */ `
@@ -42,13 +24,25 @@ uniform vec3 wbSpecular[4];
 uniform vec4 wbWrap;
 uniform float wbRoughness;
 uniform float wbMetallic;
+uniform bool wbSpecularOn;
+
+// [Drobot2014a] as Blender has it (\`workbench_world_light_lib.glsl\`): an approximate reciprocal.
+vec4 wbFastRcp(vec4 v) {
+  return intBitsToFloat(0x7eef370b - floatBitsToInt(v));
+}
 
 vec4 wbWrapped(vec4 NL, vec4 w) {
   vec4 w1 = w + 1.0;
-  return clamp((NL + w) / (w1 * w1), 0.0, 1.0);
+  return clamp((NL + w) * wbFastRcp(w1 * w1), 0.0, 1.0);
 }
 
 vec3 volterWorkbenchLighting(vec3 baseColor, vec3 N, vec3 I) {
+  if (!wbSpecularOn) {
+    vec4 plainNL = vec4(dot(wbDir[0], N), dot(wbDir[1], N), dot(wbDir[2], N), dot(wbDir[3], N));
+    vec4 plainLight = wbWrapped(plainNL, wbWrap);
+    return (plainLight.x * wbDiffuse[0] + plainLight.y * wbDiffuse[1] +
+      plainLight.z * wbDiffuse[2] + plainLight.w * wbDiffuse[3]) * baseColor;
+  }
   vec3 diffuseColor = mix(baseColor, vec3(0.0), wbMetallic);
   vec3 specularColor = mix(vec3(0.05), baseColor, wbMetallic);
   vec3 R = -reflect(I, N);
@@ -89,8 +83,9 @@ const LIGHT_DIFFUSE = vec3s((light) => light.diffuse);
 const LIGHT_SPECULAR = vec3s((light) => light.specular);
 const LIGHT_WRAP = new THREE.Vector4(...SOLID_LIGHTS.map((light) => light.smooth));
 
-/** One Solid-shaded surface: Blender's function over this viewport display. */
-export function workbenchMaterial(display: ViewportDisplay, side: THREE.Side): THREE.MeshLambertMaterial {
+/** One Solid-shaded surface: Blender's function over this viewport display, with or without the
+ *  specular term (`View3DShading.show_specular_highlight`). */
+export function workbenchMaterial(display: ViewportDisplay, side: THREE.Side, specular = true): THREE.MeshLambertMaterial {
   const [r, g, b] = display.color;
   const material = new THREE.MeshLambertMaterial({ side });
   material.color.setRGB(r, g, b, THREE.LinearSRGBColorSpace);
@@ -100,8 +95,9 @@ export function workbenchMaterial(display: ViewportDisplay, side: THREE.Side): T
     shader.uniforms['wbDiffuse'] = { value: LIGHT_DIFFUSE };
     shader.uniforms['wbSpecular'] = { value: LIGHT_SPECULAR };
     shader.uniforms['wbWrap'] = { value: LIGHT_WRAP };
-    shader.uniforms['wbRoughness'] = { value: display.roughness };
+    shader.uniforms['wbRoughness'] = { value: workbenchRoughness(display) };
     shader.uniforms['wbMetallic'] = { value: display.metallic };
+    shader.uniforms['wbSpecularOn'] = { value: specular };
     shader.fragmentShader = shader.fragmentShader
       .replace('void main() {', `${WORKBENCH_GLSL}\nvoid main() {`)
       .replace(