@driftengine/core 4.8.6 → 4.8.7

package/src/render/particlePool.ts

@@ -53,6 +53,29 @@ export interface ParticleInstances {
   capacity: number;
 }
 
+/**
+ * Floats one particle takes in a buffer a caller's own compute writes (`DeviceParticles`), in this
+ * order: position 3, half-width 1, roll 1, colour 3, opacity 1, age 1, seed 1, velocity 3, a
+ * sprite's frame 1 and its half-height 1 — `ParticleInstances`' streams, interleaved as the pool's
+ * own upload interleaves them. 64 bytes a particle.
+ */
+export const DEVICE_PARTICLE_FLOATS = 16;
+
+/**
+ * Particles a caller's own compute shader wrote into a buffer of its own (`registerCompute`), drawn
+ * where they lie by `drawDeviceParticles` rather than read back and uploaded again. WebGPU only.
+ *
+ * **Not sorted**, as a pool's are where its batch asks: the device holds them, so an alpha-blended
+ * set that must be drawn far to near sorts itself. A slot with a half-width of 0 draws nothing, which
+ * is how a fixed-size buffer holds fewer live particles than it has room for.
+ */
+export interface DeviceParticles {
+  /** A buffer with `VERTEX` usage, `DEVICE_PARTICLE_FLOATS` floats a particle. */
+  readonly buffer: GPUBuffer;
+  /** How many particles from its start to draw; no more than the buffer holds. */
+  readonly count: number;
+}
+
 function createParticleInstances(capacity: number): ParticleInstances {
   return {
     positions: new Float32Array(capacity * 3),

package/src/render/pointLightSelection.ts

@@ -1,6 +1,10 @@
 /** Allocation-free selection and packing of point lights for a fixed shader budget. */
 
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.ts';
+import {
+  POINT_LIGHT_COS_INNER,
+  POINT_LIGHT_COS_OUTER,
+  lightFalloffExponentOf,
+} from './clusteredLights.ts';
 import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.ts';
 import { gatherLights } from './lightGrid.ts';
 import type { LightGrid } from './lightGrid.ts';
@@ -198,6 +202,14 @@ export interface PointLightSource {
    * whose uniform budget has none to spare.
    */
   inLightField?: boolean;
+  /**
+   * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
+   * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
+   * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
+   * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
+   * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+   */
+  falloffExponent?: number;
 }
 
 export interface PointLightBuffer {
@@ -256,6 +268,11 @@ export interface PointLightBuffer {
   readonly directions: Float32Array;
   /** Two per slot: the cosine of the inner cone angle, then of the outer. */
   readonly coneCos: Float32Array;
+  /**
+   * One per slot: the light's own falloff exponent, or 0 for the frame's falloff. See
+   * `PointLightSource.falloffExponent`.
+   */
+  readonly falloffExponents: Float32Array;
   /** One per slot: a row of the photometric atlas, or −1 for a light with no profile. */
   readonly iesProfiles: Float32Array;
   /** Internal insertion-sort storage; exposed only to keep one flat object. */
@@ -307,6 +324,7 @@ export function createPointLightBuffer(capacity: number = MAX_POINT_LIGHTS): Poi
     weights: new Float32Array(shaded),
     directions: new Float32Array(shaded * 3),
     coneCos: new Float32Array(shaded * 2),
+    falloffExponents: new Float32Array(shaded),
     /* −1 rather than 0, because row 0 is a real fixture and a light that asked for none must not
        be shaped by whichever profile happened to load first. */
     iesProfiles: new Float32Array(shaded).fill(-1),
@@ -587,6 +605,7 @@ function choose(
      * Restricting it to spots would be a smaller feature for no saving.
      */
     out.iesProfiles[slot] = light.iesProfile ?? -1;
+    out.falloffExponents[slot] = lightFalloffExponentOf(light.falloffExponent);
   }
   out.count = chosen;
 

package/src/render/renderQuality.ts

@@ -219,13 +219,14 @@ export interface RenderQuality {
    * **`'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
+   * Burley's blur in the picture as well: a skin draw writes the light its diffuse is made of to a
+   * target of its own and its colour to another (it is drawn three times to do so), and the light is
+   * spread across the pixels its scatter distance covers, multiplied by the colour 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: three half-float targets the size of the frame, and two multisampled ones
+   * 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.

package/src/render/rendererHarness.ts

@@ -119,6 +119,9 @@ export function recordingGl(
     ONE: 1,
     ONE_MINUS_SRC_ALPHA: 0x0303,
     TRIANGLES: 0x0004,
+    /* The winding a pass names, so a test can tell which one it chose. */
+    CW: 0x0900,
+    CCW: 0x0901,
     TEXTURE0: 0x84c0,
     DEPTH_BUFFER_BIT: 0x00000100,
     DEPTH_TEST: 0x0b71,

package/src/render/rgb9e5.ts

@@ -0,0 +1,52 @@
+/**
+ * rgb9e5: three 9-bit mantissas over one shared 5-bit exponent, an unsigned float colour in four
+ * bytes. `EXT_texture_shared_exponent`'s encoding, the one a GPU's `rgb9e5ufloat` reads, written
+ * out so a lightmap page can hold its irradiance in four bytes a texel against a half float's eight.
+ *
+ * **What it gives up**: precision in the smaller channels, which share the largest one's exponent —
+ * a channel a thousandth of its neighbour keeps about one bit — and anything negative or past
+ * 65,408, which it clamps. Light is neither, and a bake's colours rarely span more than a few
+ * octaves within one texel, so a lightmap loses nothing visible; a value that needs each channel
+ * exact wants a format of its own.
+ *
+ * The bits, low to high: red in 0–8, green in 9–17, blue in 18–26, the exponent in 27–31, biased by
+ * 15, and a value is `mantissa * 2^(exponent - 15 - 9)`.
+ */
+
+const BIAS = 15;
+const MANTISSA_BITS = 9;
+const MANTISSA_VALUES = 1 << MANTISSA_BITS;
+const MAX_EXPONENT = 31;
+
+/** The largest value the format holds: 511/512 of 2^16. */
+export const RGB9E5_MAX = ((MANTISSA_VALUES - 1) / MANTISSA_VALUES) * 2 ** (MAX_EXPONENT - BIAS);
+
+const clampChannel = (v: number): number => (v > 0 ? Math.min(v, RGB9E5_MAX) : 0);
+
+/** One colour packed into its 32 bits, rounding to nearest; NaN and negatives are zero. */
+export function packRgb9e5(red: number, green: number, blue: number): number {
+  const r = clampChannel(red);
+  const g = clampChannel(green);
+  const b = clampChannel(blue);
+  const largest = Math.max(r, g, b);
+  let exponent = Math.max(-BIAS - 1, Math.floor(Math.log2(largest))) + 1 + BIAS;
+  let scale = 2 ** (exponent - BIAS - MANTISSA_BITS);
+  /* Rounding the largest channel up to 512 needs one more exponent, which the spec allows for. */
+  if (Math.floor(largest / scale + 0.5) === MANTISSA_VALUES) {
+    exponent += 1;
+    scale *= 2;
+  }
+  /* Inline rather than a helper: a page packs millions of texels, and a closure a call is one each. */
+  const mr = Math.min(MANTISSA_VALUES - 1, Math.floor(r / scale + 0.5));
+  const mg = Math.min(MANTISSA_VALUES - 1, Math.floor(g / scale + 0.5));
+  const mb = Math.min(MANTISSA_VALUES - 1, Math.floor(b / scale + 0.5));
+  return (mr | (mg << 9) | (mb << 18) | (exponent << 27)) >>> 0;
+}
+
+/** A packed colour's three channels, into `out[at…at+2]`. */
+export function unpackRgb9e5(bits: number, out: { [index: number]: number }, at = 0): void {
+  const scale = 2 ** ((bits >>> 27) - BIAS - MANTISSA_BITS);
+  out[at] = (bits & 511) * scale;
+  out[at + 1] = ((bits >>> 9) & 511) * scale;
+  out[at + 2] = ((bits >>> 18) & 511) * scale;
+}

package/src/render/sceneCapture.ts

@@ -0,0 +1,56 @@
+/**
+ * A scene capture: a texture the world is drawn into from a camera of the caller's, which a material
+ * then shows like any image — a screen in the world showing what a camera elsewhere sees, a monitor,
+ * a security feed. The planar reflection's pass, for a caller's camera rather than a mirrored one.
+ *
+ * **It holds radiance, not display pixels**, as a probe does: drawn with the output transform held
+ * off, at the colour format a probe takes — half floats under `hdrScene`, bytes otherwise — and
+ * sampled linear, so a material showing it as its `emissive` emits the light the capture saw and the
+ * frame's grade then applies once, to the screen as to everything around it.
+ *
+ * **What it gives up**: it is the mesh pass alone, as a probe bake is — the sky, water, particles and
+ * anything else a scene draws after its world are in the capture only if the callback draws them;
+ * no temporal resolve, bloom or other effect after the world runs on it; and it has no mip chain, so
+ * a screen seen small and far shimmers where a mipmapped image would not.
+ */
+
+/** What a capture's texture is made from, in place of an image: its size and colour format. */
+export interface SceneCaptureTexels {
+  readonly kind: 'scene-capture';
+  readonly width: number;
+  readonly height: number;
+  /** Half floats, which hold light past one; bytes otherwise. */
+  readonly float: boolean;
+}
+
+/** The largest side a capture may have, the size every WebGL2 device must take. */
+export const MAX_SCENE_CAPTURE_SIZE = 4096;
+
+/** A capture's description, refused by name where a side is not a whole number of pixels it can be. */
+export function sceneCaptureTexels(
+  width: number,
+  height: number,
+  float: boolean,
+): SceneCaptureTexels {
+  for (const [name, side] of [
+    ['width', width],
+    ['height', height],
+  ] as const) {
+    if (!Number.isInteger(side) || side < 1 || side > MAX_SCENE_CAPTURE_SIZE) {
+      throw new Error(
+        `createSceneCapture: ${name} must be a whole number from 1 to ${MAX_SCENE_CAPTURE_SIZE}, ` +
+          `not ${String(side)}`,
+      );
+    }
+  }
+  return { kind: 'scene-capture', width, height, float };
+}
+
+/** Whether a texture source is a capture's description rather than an image. */
+export function isSceneCaptureTexels(source: unknown): source is SceneCaptureTexels {
+  return (
+    typeof source === 'object' &&
+    source !== null &&
+    (source as { kind?: unknown }).kind === 'scene-capture'
+  );
+}

package/src/render/screenSpaceReflection.ts

@@ -350,9 +350,30 @@ export function towardCameraFade(direction: ReadonlyVec3, viewDirection: Readonl
   return Math.min(1, Math.max(0, (along + 1) / 2));
 }
 
+/**
+ * What a `ReflectiveSurface` is made with: its box, which way the surfaces inside it face, and how
+ * much and how far they reflect. Every number but the box has a default; see each field.
+ */
 export interface ReflectiveSurfaceOptions extends DecalBox {
-  /** How much of what the ray finds lands on the surface, 0 to 1. */
+  /**
+   * How much of what the ray finds lands on the surface, 0 to 1: one share over the box, or with
+   * `fresnel` the surface's reflectance head-on.
+   */
   readonly strength?: number;
+  /**
+   * Whether `strength` is the surface's reflectance head-on, F0, rather than one share over the
+   * box. Each pixel then returns `F0 · A + B` of what its ray finds, the split-sum environment BRDF
+   * at its own view and `roughness` — Karis's fit, the one the lit stage reflects its environment
+   * by — so a floor returns more toward the horizon than underfoot, and the share follows the
+   * camera as Unreal weighs its reflections. **False by default**, the one share as before.
+   *
+   * **What it gives up**: the pass has no material buffer, so the roughness and F0 are the box's,
+   * not each pixel's, and nothing occludes the reflection where the lit stage's ambient occlusion
+   * would. A floor of one material is what it is for.
+   */
+  readonly fresnel?: boolean;
+  /** The surface's roughness, 0 to 1, that `fresnel` weighs by. 0, a polished surface, if absent. */
+  readonly roughness?: number;
   /** How far a ray may travel, world metres. */
   readonly reachM?: number;
   /** How deep a depth sample is treated as being. See `ScreenSpaceMarch.thicknessM`. */
@@ -382,6 +403,9 @@ export class ReflectiveSurface {
   readonly tint = new Float32Array(3);
 
   strength: number;
+  /** See `ReflectiveSurfaceOptions.fresnel`. */
+  fresnel: boolean;
+  roughness: number;
   reachM: number;
   thicknessM: number;
   steps: number;
@@ -405,6 +429,8 @@ export class ReflectiveSurface {
     /* Half, because a mirror is the rare case: a wet floor, polished stone and a car bonnet all
        return a fraction of what lands on them, and a consumer who wants a mirror asks for one. */
     this.strength = options.strength ?? 0.5;
+    this.fresnel = options.fresnel ?? false;
+    this.roughness = options.roughness ?? 0;
     /* Eight metres covers a room and a street corner. Further costs steps rather than accuracy,
        since the step is the reach divided by them. */
     this.reachM = options.reachM ?? 8;
@@ -469,6 +495,8 @@ export interface RecordedReflection {
   readonly axis: Float32Array;
   readonly tint: Float32Array;
   strength: number;
+  fresnel: boolean;
+  roughness: number;
   reachM: number;
   thicknessM: number;
   steps: number;
@@ -482,6 +510,8 @@ function newRecord(): RecordedReflection {
     axis: new Float32Array(3),
     tint: new Float32Array(3),
     strength: 0.5,
+    fresnel: false,
+    roughness: 0,
     reachM: 8,
     thicknessM: 0.25,
     steps: 24,
@@ -537,6 +567,8 @@ export class ReflectionQueue {
     record.axis.set(surface.axis);
     record.tint.set(surface.tint);
     record.strength = Math.min(1, Math.max(0, surface.strength));
+    record.fresnel = surface.fresnel;
+    record.roughness = Math.min(1, Math.max(0, surface.roughness));
     record.reachM = Math.max(0, surface.reachM);
     record.thicknessM = Math.max(0, surface.thicknessM);
     record.steps = Math.min(32, Math.max(1, Math.round(surface.steps)));

package/src/render/shaders/bolt.ts

@@ -107,7 +107,13 @@ void main() {
    * the glow. A single falloff gives either a hard line with no atmosphere or a
    * soft smudge with no filament.
    */
-  float across = 1.0 - abs(vSide);
+  /*
+   * Clamped, because a multisampled target shades a pixel on the quad's edge at its centre, which
+   * may lie outside the quad: there 'vSide' runs past one, 'across' goes negative, and 'pow' of a
+   * negative number is NaN. One NaN pixel is a dark speck; bloom then spreads it into a white disc
+   * the size of the blur. Found by a fight drawing short arcs at 4 samples.
+   */
+  float across = clamp(1.0 - abs(vSide), 0.0, 1.0);
   float core = pow(across, 10.0);
   /*
    * A *wide* halo, deliberately. This exponent is the single biggest control over

package/src/render/shaders/depth.ts

@@ -101,6 +101,12 @@ void main() {
 #endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
+  /* The bottom row is the instance's texture cell, rebuilt as the row it stands for: see flat. */
+  vec4 instanceCell = vec4(model[0].w, model[1].w, model[2].w, model[3].w);
+  model[0].w = 0.0;
+  model[1].w = 0.0;
+  model[2].w = 0.0;
+  model[3].w = 1.0;
 #else
   mat4 model = uModel;
 #endif
@@ -125,7 +131,12 @@ void main() {
   vLightPosition = uLightViewProj * vec4(bent, world.w);
   gl_Position = vLightPosition;
 #if CUTOUT
+#if INSTANCED
+  /* A cutout instance's shadow is cut by its own cell, as its picture is. */
+  vUv = vec3((aUv.xy * instanceCell.xy + instanceCell.zw) * uUvScale + uUvOffset, aUv.z);
+#else
   vUv = vec3(aUv.xy * uUvScale + uUvOffset, aUv.z);
+#endif
   vAlphaCutout = uAlphaCutout;
 #endif
 #if GLASS

package/src/render/shaders/flat/anisotropic.ts

@@ -30,7 +30,16 @@ void anisotropicSurface() {
     direction.x * uModelParams[0].y - direction.y * uModelParams[0].z,
     direction.x * uModelParams[0].z + direction.y * uModelParams[0].y
   );
-  aAlong = normalize(mTangent * turned.x + mBitangent * turned.y);
+  vec3 along = mTangent * turned.x + mBitangent * turned.y;
+  /*
+   * A mesh with neither tangents nor texture coordinates has no frame to take a direction from,
+   * and normalising the zero it gives was a NaN that drew the whole surface black. Any direction in
+   * the surface stands in, the one across the world's up, so the highlight is stretched somewhere.
+   */
+  if (dot(along, along) < 1e-12) {
+    along = cross(abs(mNormal.y) < 0.999 ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0), mNormal);
+  }
+  aAlong = normalize(along);
   aAcross = cross(mNormal, aAlong);
   aStrength = strength;
 }
@@ -50,12 +59,37 @@ float anisotropicLobe(vec3 h, float sourceRadius, float dist) {
   return energy / max(d * d, 1e-8);
 }
 
+/**
+ * The same stretch as GGX's own BRDF, \`π · D · Vis · N·L\`, for a surface whose highlight is
+ * physical: the distribution normalised, and Smith's height-correlated masking stretched with it
+ * (Heitz 2014, as Filament writes it). \`anisotropicPhysicalLobe\` in anisotropicLobe.ts.
+ */
+float anisotropicPhysical(vec3 l, vec3 h, float ndl, float sourceRadius, float dist) {
+  float alpha = max(mRoughness * mRoughness, MIN_LOBE_ALPHA);
+  float alongWidth = alpha + (1.0 - alpha) * aStrength * aStrength;
+  float grow = sourceRadius / max(2.0 * dist, 1e-3);
+  float along = clamp(alongWidth + grow, alongWidth, 1.0);
+  float across = clamp(alpha + grow, alpha, 1.0);
+  float x = dot(aAlong, h) / along;
+  float y = dot(aAcross, h) / across;
+  float z = dot(mNormal, h);
+  float d = x * x + y * y + z * z;
+  float distribution = 1.0 / max(3.14159265 * along * across * d * d, 1e-8);
+  float ndv = max(dot(mNormal, mToEye), 1e-4);
+  float viewed = ndl * length(vec3(along * dot(aAlong, mToEye), across * dot(aAcross, mToEye), ndv));
+  float lit = ndv * length(vec3(along * dot(aAlong, l), across * dot(aAcross, l), ndl));
+  return 3.14159265 * distribution * (0.5 / max(viewed + lit, 1e-5)) * ndl;
+}
+
 void anisotropicLight(vec3 l, float sourceRadius, float dist) {
   float ndl = max(dot(mNormal, l), 0.0);
   vec3 h = normalize(l + mToEye);
-  vec3 tint = mix(mSpecColor, vec3(1.0), pow(1.0 - max(dot(mToEye, h), 0.0), 5.0) * mMetal);
+  vec3 tint = highlightTint(mSpecColor, max(dot(mToEye, h), 0.0), mMetal);
   mDiffuse = mAlbedo * ndl * (1.0 - mMetal);
-  mSpecular = ndl > 0.0 ? tint * anisotropicLobe(h, sourceRadius, dist) : vec3(0.0);
+  float lobe = physicalSpecular()
+    ? anisotropicPhysical(l, h, ndl, sourceRadius, dist)
+    : anisotropicLobe(h, sourceRadius, dist);
+  mSpecular = ndl > 0.0 ? tint * lobe : vec3(0.0);
 }
 
 /* The environment's normal, bent toward the stretch by its strength and the surface's roughness. */

package/src/render/shaders/flat/areaLight.ts

@@ -23,6 +23,52 @@ float areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {
   return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);
 }
 
+/**
+ * How far along one of a rectangle's axes a fragment still sees it past the barn door on that axis's
+ * positive edge: \`p\` the fragment's place along the axis, \`height\` its height above the
+ * rectangle's plane, \`halfSize\` the rectangle's half extent, and the door's tip \`tipOut\` beyond
+ * the edge and \`tipUp\` above the plane. Points of the rectangle past the answer are hidden.
+ *
+ * Above the tip, the tip's shadow on the plane as seen from the fragment is the limit. Below it, a
+ * fragment beside the door and outside its line is hidden from all of it, and one inside the door's
+ * reach is hidden from none of it.
+ */
+float barnDoorLimit(float p, float height, float halfSize, float tipOut, float tipUp) {
+  float tipAt = halfSize + tipOut;
+  if (height > tipUp) return (height * tipAt - tipUp * p) / (height - tipUp);
+  if (p > halfSize && height * tipOut < tipUp * (p - halfSize)) return -1e9;
+  return 1e9;
+}
+
+/**
+ * The part of a rectangle a fragment sees past its barn doors, written into \`centre\` and
+ * \`halfSize\` as the smaller rectangle that is left, or false where the doors hide all of it.
+ * \`doors\` is the cosine of their angle from the normal and their length; a length of 0 is no doors.
+ * Each axis is clipped by its own two doors, which is what makes this four projections and a min.
+ */
+bool areaBarnDoors(inout vec3 centre, vec3 right, vec3 up, inout vec2 halfSize, vec2 doors) {
+  if (doors.y <= 0.0) return true;
+  vec3 toFragment = vWorldPos - centre;
+  float height = dot(toFragment, cross(right, up));
+  /* Behind the emitting side: nothing to clip, and the form factor already answers it. */
+  if (height <= 0.0) return true;
+  float tipOut = doors.y * sqrt(max(1.0 - doors.x * doors.x, 0.0));
+  float tipUp = doors.y * doors.x;
+  vec2 p = vec2(dot(toFragment, right), dot(toFragment, up));
+  vec2 hi = vec2(
+    min(halfSize.x, barnDoorLimit(p.x, height, halfSize.x, tipOut, tipUp)),
+    min(halfSize.y, barnDoorLimit(p.y, height, halfSize.y, tipOut, tipUp))
+  );
+  vec2 lo = vec2(
+    max(-halfSize.x, -barnDoorLimit(-p.x, height, halfSize.x, tipOut, tipUp)),
+    max(-halfSize.y, -barnDoorLimit(-p.y, height, halfSize.y, tipOut, tipUp))
+  );
+  if (hi.x <= lo.x || hi.y <= lo.y) return false;
+  centre += right * (0.5 * (lo.x + hi.x)) + up * (0.5 * (lo.y + hi.y));
+  halfSize = 0.5 * (hi - lo);
+  return true;
+}
+
 /**
  * What one rectangle of colour \`color\` and form factor \`form\` adds to the lamps' two sums, open
  * and shadowed by \`occl\` and \`glass\`.

package/src/render/shaders/flat/glassTint.ts

@@ -29,7 +29,12 @@ vec4 glassUnmix(vec4 mip, float centreClarity) {
  * about which optional code a lit program carries. See `litSwitchesGlsl`.
  */
 export type LitSwitch =
-  'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT';
+  | 'GLASS_SHADOWS'
+  | 'CLUSTERED_LIGHTS'
+  | 'LIGHT_FIXTURES'
+  | 'SURFACE_EFFECTS'
+  | 'DRIFT_LIGHT'
+  | 'PHYSICAL_SPECULAR';
 
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export function noLitSwitches(): Record<LitSwitch, boolean> {
@@ -39,6 +44,7 @@ export function noLitSwitches(): Record<LitSwitch, boolean> {
     LIGHT_FIXTURES: false,
     SURFACE_EFFECTS: false,
     DRIFT_LIGHT: false,
+    PHYSICAL_SPECULAR: false,
   };
 }
 
@@ -61,7 +67,8 @@ export interface LitSwitches {
  * first uses them — a measured profile or a cookie, a material with an effects table, a DriftLight
  * volume — and then on for good; see `PipelineCache.enable` and the WebGL2 renderer's rebuild.
  * Measured on RADV against the lit shader with glass already out: 6,852 instructions and 120
- * registers, 4,641 and 96 with all four out.
+ * registers, 4,641 and 96 with all four out. `PHYSICAL_SPECULAR` is a sixth, declared with the
+ * models so that theirs keep their ids (`modelsGlsl`).
  */
 export function litSwitchesGlsl(switches: LitSwitches): string {
   return /* glsl */ `

package/src/render/shaders/flat/index.ts

@@ -14,7 +14,7 @@ import { CLOTH_BINDING_GLSL } from '../clothBinding.ts';
 import { SKINNING_GLSL } from '../skinning.ts';
 import { SURFACE_GLSL } from './surface.ts';
 import { MAIN_GLSL } from './main.ts';
-import { MODELS_GLSL } from './models.ts';
+import { modelsGlsl } from './models.ts';
 import { AREA_LIGHT_GLSL } from './areaLight.ts';
 import { NORMAL_MAP_GLSL } from './normalMap.ts';
 import { DRIFT_LIGHT_GLSL } from './driftLight.ts';
@@ -245,6 +245,15 @@ void main() {
 #endif
 #if INSTANCED
   mat4 model = mat4(aInstanceModel0, aInstanceModel1, aInstanceModel2, aInstanceModel3);
+  /*
+   * **The bottom row is the instance's texture cell** (\`MeshInstances.uvRegions\`), which an
+   * affine placement leaves free: read, and rebuilt as the \`[0, 0, 0, 1]\` it stands for.
+   */
+  vec4 instanceCell = vec4(model[0].w, model[1].w, model[2].w, model[3].w);
+  model[0].w = 0.0;
+  model[1].w = 0.0;
+  model[2].w = 0.0;
+  model[3].w = 1.0;
   vec3 tint = aInstanceTint.rgb;
   if (LIGHTMAP_REGIONS) tint = vec3(1.0);
 #else
@@ -293,7 +302,12 @@ void main() {
   vColor = aColor * tint;
   vEmissive = aEmissive;
   vSpecular = aSpecular;
+#if INSTANCED
+  /* The instance's cell first, then the material's scale and offset. */
+  vUv = vec3((aUv.xy * instanceCell.xy + instanceCell.zw) * uUvScale + uUvOffset, aUv.z);
+#else
   vUv = vec3(aUv.xy * uUvScale + uUvOffset, aUv.z);
+#endif
   vEmissiveColor = aEmissiveColor;
   vRoughness = aRoughness;
   vGrain = aGrain;
@@ -449,6 +463,11 @@ export interface FlatShaderOptions {
   readonly surfaceEffects?: boolean;
   /** Whether it reads a DriftLight volume. True when absent. See `litSwitchesGlsl`. */
   readonly driftLight?: boolean;
+  /**
+   * Whether it carries GGX's own highlight for a material that asks (`physicalSpecular`). True
+   * when absent. See `modelsGlsl`.
+   */
+  readonly physicalSpecular?: boolean;
   /**
    * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
    *
@@ -593,7 +612,7 @@ export function flatFrag(options: FlatShaderOptions): string {
       DRIFT_LIGHT_GLSL,
       SURFACE_EFFECTS_GLSL,
       /* Depth zero and after the tangent frame and the lobes it calls; see models.ts. */
-      MODELS_GLSL,
+      modelsGlsl(options.physicalSpecular ?? true),
       /* After the models, whose answer to a rectangle it asks for. See areaLight.ts. */
       AREA_LIGHT_GLSL,
       MAIN_GLSL,

package/src/render/shaders/flat/lobes.ts

@@ -30,6 +30,55 @@ export const EMISSIVE_SHADOW_SHARE = 0.55;
  */
 export const MIN_LOBE_ALPHA = 0.01;
 
+/**
+ * Karis's fit to the split-sum environment BRDF, as GLSL: the lit stage's, and the screen-space
+ * reflection's when a surface asks for its Fresnel (`ReflectiveSurface.fresnel`). One text, so the
+ * two cannot drift.
+ */
+export const ENV_BRDF_GLSL = `/**
+ * The other half of the split-sum approximation: what fraction of an environment a surface returns.
+ *
+ * The convolution decides *what* a surface reflects at a given roughness; this decides *how much*.
+ * Before it the amount was fresnel times one-minus-roughness, which is a curve somebody chose
+ * standing in for an integral.
+ *
+ * Karis's analytic fit to the environment BRDF, so there is **no lookup texture and no texture
+ * unit**: a few multiply-adds against roughness and the view angle. x scales the surface's own
+ * reflectance at normal incidence and y is the additive grazing term, so a smooth dielectric at
+ * f0 0.04 returns about 0.046 head-on and approaches 1 at the edge, which is what a dielectric
+ * does. At roughness 1 it returns about 0.016 rather than the zero one-minus-roughness gave, which
+ * is the substantive difference: a fully rough dielectric does reflect its surroundings.
+ *
+ * **It replaces the Fresnel factor as well as the thinning**, because the fit already contains the
+ * angular dependence; multiplying by a separate Fresnel term would apply it twice.
+ *
+ * **How much this is worth was measured, and it is worth less than it looks on a dark room.**
+ * On demo/dev/ibl.html?ladder=1 the whole ladder moved by at most 0.2 of 255 when the old term was
+ * replaced. That is not the term failing: at high roughness the surface reads the coarsest levels
+ * of the chain, and in a room of five dark walls and one bright one those levels are dark, so a
+ * weight three times larger against a near-zero radiance is still near zero. It is worth much more
+ * against a bright environment, which is what a loaded sky is and what no captured room here is.
+ *
+ * **A warning about reading that page, paid for once.** The ladder falls about five-fold from
+ * mirror to rough, and that reads as energy being lost. It is not: a mirror concentrates the one
+ * bright wall into a sharp image and a rough surface averages it against five dark ones, so the
+ * falloff is the room's own content. The normalised falloff also happens to track one-minus-
+ * roughness closely, which made the old term look like the cause — and removing that term entirely
+ * changed nothing, which is what settled it. Perturb before believing a match.
+ *
+ * **What it costs** is a fit rather than the integral: the published error is around one per cent
+ * of the tabulated term, far below what an eight-bit frame can show. **What would make it wrong**
+ * is a material model this shader does not have — a clearcoat or a sheen lobe carries its own BRDF
+ * and its own integral, and this fit is Trowbridge-Reitz with Smith masking and nothing else.
+ */
+vec2 envBrdfApprox(float ndv, float roughness) {
+  const vec4 c0 = vec4(-1.0, -0.0275, -0.572, 0.022);
+  const vec4 c1 = vec4(1.0, 0.0425, 1.04, -0.04);
+  vec4 r = roughness * c0 + c1;
+  float a004 = min(r.x * r.x, exp2(-9.28 * ndv)) * r.x + r.y;
+  return vec2(-1.04, 1.04) * a004 + r.zw;
+}`;
+
 export const LOBES_GLSL = `float shadowReach(float distance, float maxDistance) {
   return 1.0 - smoothstep(
     maxDistance * ${POINT_SHADOW_FADE_START.toFixed(2)},
@@ -156,49 +205,7 @@ float sphereLobe(float ndh, float roughness, float sourceRadius, float dist) {
   return energy * (w2 * w2) / max(d * d, 1e-8);
 }
 
-/**
- * The other half of the split-sum approximation: what fraction of an environment a surface returns.
- *
- * The convolution decides *what* a surface reflects at a given roughness; this decides *how much*.
- * Before it the amount was fresnel times one-minus-roughness, which is a curve somebody chose
- * standing in for an integral.
- *
- * Karis's analytic fit to the environment BRDF, so there is **no lookup texture and no texture
- * unit**: a few multiply-adds against roughness and the view angle. x scales the surface's own
- * reflectance at normal incidence and y is the additive grazing term, so a smooth dielectric at
- * f0 0.04 returns about 0.046 head-on and approaches 1 at the edge, which is what a dielectric
- * does. At roughness 1 it returns about 0.016 rather than the zero one-minus-roughness gave, which
- * is the substantive difference: a fully rough dielectric does reflect its surroundings.
- *
- * **It replaces the Fresnel factor as well as the thinning**, because the fit already contains the
- * angular dependence; multiplying by a separate Fresnel term would apply it twice.
- *
- * **How much this is worth was measured, and it is worth less than it looks on a dark room.**
- * On demo/dev/ibl.html?ladder=1 the whole ladder moved by at most 0.2 of 255 when the old term was
- * replaced. That is not the term failing: at high roughness the surface reads the coarsest levels
- * of the chain, and in a room of five dark walls and one bright one those levels are dark, so a
- * weight three times larger against a near-zero radiance is still near zero. It is worth much more
- * against a bright environment, which is what a loaded sky is and what no captured room here is.
- *
- * **A warning about reading that page, paid for once.** The ladder falls about five-fold from
- * mirror to rough, and that reads as energy being lost. It is not: a mirror concentrates the one
- * bright wall into a sharp image and a rough surface averages it against five dark ones, so the
- * falloff is the room's own content. The normalised falloff also happens to track one-minus-
- * roughness closely, which made the old term look like the cause — and removing that term entirely
- * changed nothing, which is what settled it. Perturb before believing a match.
- *
- * **What it costs** is a fit rather than the integral: the published error is around one per cent
- * of the tabulated term, far below what an eight-bit frame can show. **What would make it wrong**
- * is a material model this shader does not have — a clearcoat or a sheen lobe carries its own BRDF
- * and its own integral, and this fit is Trowbridge-Reitz with Smith masking and nothing else.
- */
-vec2 envBrdfApprox(float ndv, float roughness) {
-  const vec4 c0 = vec4(-1.0, -0.0275, -0.572, 0.022);
-  const vec4 c1 = vec4(1.0, 0.0425, 1.04, -0.04);
-  vec4 r = roughness * c0 + c1;
-  float a004 = min(r.x * r.x, exp2(-9.28 * ndv)) * r.x + r.y;
-  return vec2(-1.04, 1.04) * a004 + r.zw;
-}
+${ENV_BRDF_GLSL}
 
 /**
  * How much of a prefiltered environment a surface returns, with the light that bounces more than