@driftengine/core 4.2.1 → 4.4.0

package/dist/render/shaders/gi/driftLight.wgsl.js

@@ -0,0 +1,49 @@
+/**
+ * DriftLight's lookup in hand-written WGSL, for the traced probe bake: the summed light arriving on
+ * a surface a probe's ray struck, which is how candles past the frame's choice reach the bounce.
+ *
+ * **A transcription of `flat/driftLight.ts`, line for line**, because a compute shader cannot
+ * include the generated WGSL of a fragment stage. Two spellings of one lookup is the hazard the
+ * 2026-08-13 rule is about, and `driftLight.test.ts` beside this holds them together by reading
+ * both: change one and it names the line of the other.
+ *
+ * **Integer arithmetic for the brick's corner**, by the 2026-09-20 rule: a device divides a float by
+ * multiplying by its reciprocal, and a brick number off by one is a brick from somewhere else.
+ *
+ * The including module declares `driftIndex: texture_3d<u32>`, `driftAtlas: texture_3d<f32>` and a
+ * filtering `driftSampler`; `origin` is the field's first sample and, in `w`, the spacing.
+ */
+export const DRIFT_LIGHT_WGSL = /* wgsl */ `
+fn driftLightIrradiance(world: vec3<f32>, n: vec3<f32>, origin: vec4<f32>) -> vec3<f32> {
+  let spacing = origin.w;
+  let at = (world + n * (0.5 * spacing) - origin.xyz) / (3.0 * spacing);
+  let cell = vec3<i32>(floor(at));
+  if (any(cell < vec3<i32>(0)) || any(cell >= vec3<i32>(textureDimensions(driftIndex, 0)))) {
+    return vec3<f32>(0.0);
+  }
+  let id = textureLoad(driftIndex, cell, 0).r;
+  if (id == 0u) {
+    return vec3<f32>(0.0);
+  }
+  let size = vec3<i32>(textureDimensions(driftAtlas, 0));
+  let brick = i32(id) - 1;
+  let across = size.x / 8;
+  let down = size.y / 4;
+  let corner = vec3<f32>(
+    f32((brick % across) * 8),
+    f32(((brick / across) % down) * 4),
+    f32((brick / (across * down)) * 4)
+  );
+  let texel = 1.0 / vec3<f32>(size);
+  let inside = (at - vec3<f32>(cell)) * 3.0 + 0.5;
+  let light = textureSampleLevel(driftAtlas, driftSampler, (corner + inside) * texel, 0.0);
+  if (light.a < 1e-3) {
+    return vec3<f32>(0.0);
+  }
+  let toward = textureSampleLevel(driftAtlas, driftSampler, (corner + vec3<f32>(4.0, 0.0, 0.0) + inside) * texel, 0.0);
+  let arriving = light.rgb / light.a;
+  let towardLight = toward.xyz / light.a;
+  let facing = max(dot(n, towardLight), 0.0) + (1.0 - min(length(towardLight), 1.0)) * 0.25;
+  return arriving * facing;
+}
+`;

package/dist/render/shaders/gi/probeBake.wgsl.d.ts

@@ -41,20 +41,45 @@ export declare const BAKE_COUNTS = 8;
 export declare const BAKE_EDGE = 11;
 export declare const BAKE_FRAME = 12;
 export declare const BAKE_SCHEDULED = 13;
+/** How much of what a layer held a refresh keeps. See `PROBE_HISTORY` and `convolveMain`. */
+export declare const BAKE_HISTORY = 14;
 /** The sun, which the trace evaluates itself so a light that moves changes the bounce. */
 export declare const BAKE_SUN_DIR = 16;
 export declare const BAKE_SUN_COLOUR = 20;
-/** What a ray that left the world finds. The frame's ambient, so nothing rasterised is read. */
+/**
+ * What a ray that left the world finds: the sky's horizon colour where the frame drew a sky, and the
+ * whole of the sky, flat, where it drew none. The flag says which, in the fourth float of the row,
+ * which is where an f32 declared after a vec3 lands. The rest of the sky the frame drew follows.
+ */
 export declare const BAKE_SKY_COLOUR = 24;
-/** Rounded up to the struct's own sixteen-byte alignment, with two vec3 rows for the sun. */
-export declare const PROBE_BAKE_FLOATS = 28;
+export declare const BAKE_SKY_DRAWN = 27;
+export declare const BAKE_SKY_TOP = 28;
+export declare const BAKE_SKY_DEEP = 32;
+/** The sky's own sun, which at night is not the key light: the moon is. The sunset reads this. */
+export declare const BAKE_SKY_SUN = 36;
+/**
+ * DriftLight's field, as `driftLight/uniforms.ts` resolves it for a probe: how much is in and its
+ * scale in `x` and `w`, and where its grid starts with the spacing in `w`. Zero switches it off.
+ */
+export declare const BAKE_DRIFT_LIGHT = 40;
+export declare const BAKE_DRIFT_ORIGIN = 44;
+/**
+ * How many of the frame's exact lights `bounceLights` holds, and how the renderer shades a point
+ * light: 1 inverse-square, 0 the shaped falloff. See `gi/bounceLights.ts`.
+ */
+export declare const BAKE_LIGHT_COUNT = 48;
+export declare const BAKE_FALLOFF = 49;
+/** Rounded up to the struct's own sixteen-byte alignment: the lattice, five vec3 rows, three vec4. */
+export declare const PROBE_BAKE_FLOATS = 52;
+/** Rows of `bounceLights`: three a light. */
+export declare const BOUNCE_LIGHT_ROWS: number;
 /** Invocations a workgroup, for both entry points. 64 is this backend's default everywhere. */
 export declare const PROBE_BAKE_WORKGROUP = 64;
 /** Floats a ray's radiance takes in the intermediate buffer. */
 export declare const PROBE_RAY_FLOATS = 3;
 /** Floats a baked texel takes. Three and not four: the alpha of an irradiance map means nothing. */
 export declare const PROBE_TEXEL_FLOATS = 3;
-export declare const PROBE_BAKE_STRUCT_WGSL = "\nstruct ProbeBake {\n  /* Where the grid's first probe stands, and how far apart they are. */\n  origin: vec3<f32>,\n  spacing: vec3<f32>,\n  /* How many probes along each axis. Whole numbers carried as floats, as every block here does. */\n  counts: vec3<f32>,\n  /* Texels across one probe's map, gutter included. */\n  edge: f32,\n  /* Which frame this is, which turns the direction set so a probe converges rather than repeats. */\n  frame: f32,\n  /* How many probes this dispatch bakes. The schedule says which. */\n  scheduled: f32,\n  pad: f32,\n  /* Towards the sun, and what colour it is. The trace shades what it hits rather than reading a\n     capture, which is what lets a bounce follow a light that moved. */\n  sunDir: vec3<f32>,\n  sunColour: vec3<f32>,\n  /* And what is outside, for a ray that left. See probeDistantRadiance. */\n  skyColour: vec3<f32>,\n}\n";
+export declare const PROBE_BAKE_STRUCT_WGSL = "\nstruct ProbeBake {\n  /* Where the grid's first probe stands, and how far apart they are. */\n  origin: vec3<f32>,\n  spacing: vec3<f32>,\n  /* How many probes along each axis. Whole numbers carried as floats, as every block here does. */\n  counts: vec3<f32>,\n  /* Texels across one probe's map, gutter included. */\n  edge: f32,\n  /* How far the direction set is turned. The bake holds it at 0; the parity check turns it. */\n  frame: f32,\n  /* How many probes this dispatch bakes. The schedule says which. */\n  scheduled: f32,\n  /* How much of what a layer held each refresh keeps, 0 for a grid not yet traced whole. */\n  history: f32,\n  /* Towards the sun, and what colour it is. The trace shades what it hits rather than reading a\n     capture, which is what lets a bounce follow a light that moved. */\n  sunDir: vec3<f32>,\n  sunColour: vec3<f32>,\n  /* And what is outside, for a ray that left. See probeDistantRadiance and probeSkyAlong. */\n  skyColour: vec3<f32>,\n  skyDrawn: f32,\n  skyTop: vec3<f32>,\n  skyDeep: vec3<f32>,\n  skySun: vec3<f32>,\n  /* The summed light of a scene's many fixed lights. See driftLight.wgsl.ts. */\n  driftLight: vec4<f32>,\n  driftOrigin: vec4<f32>,\n  /* How many of the frame's exact lights bounceLights holds, and 1 for inverse-square falloff. */\n  lightCount: f32,\n  falloff: f32,\n}\n";
 /**
  * The octahedral mapping and the probe lattice, as text.
  *

package/dist/render/shaders/gi/probeBake.wgsl.js

@@ -27,6 +27,8 @@ import { FRAME_TURN, GOLDEN_ANGLE, PROBE_DIRECTIONS } from '../../gi/probeTrace.
 import { PROBE_MARCH_WGSL, PROBE_TRACE_CORE_WGSL } from './probeTrace.wgsl.js';
 import { PROBE_VOLUME_CORE_WGSL, PROBE_VOLUME_STRUCT_WGSL } from './probeVolume.wgsl.js';
 import { SAMPLE_FIELD_WGSL } from './sampleField.wgsl.js';
+import { DRIFT_LIGHT_WGSL } from './driftLight.wgsl.js';
+import { BOUNCE_LIGHT_FLOATS, MAX_BOUNCE_LIGHTS } from '../../gi/bounceLights.js';
 /**
  * Floats in the bake block, and where each field of it starts.
  *
@@ -45,13 +47,38 @@ export const BAKE_COUNTS = 8;
 export const BAKE_EDGE = 11;
 export const BAKE_FRAME = 12;
 export const BAKE_SCHEDULED = 13;
+/** How much of what a layer held a refresh keeps. See `PROBE_HISTORY` and `convolveMain`. */
+export const BAKE_HISTORY = 14;
 /** The sun, which the trace evaluates itself so a light that moves changes the bounce. */
 export const BAKE_SUN_DIR = 16;
 export const BAKE_SUN_COLOUR = 20;
-/** What a ray that left the world finds. The frame's ambient, so nothing rasterised is read. */
+/**
+ * What a ray that left the world finds: the sky's horizon colour where the frame drew a sky, and the
+ * whole of the sky, flat, where it drew none. The flag says which, in the fourth float of the row,
+ * which is where an f32 declared after a vec3 lands. The rest of the sky the frame drew follows.
+ */
 export const BAKE_SKY_COLOUR = 24;
-/** Rounded up to the struct's own sixteen-byte alignment, with two vec3 rows for the sun. */
-export const PROBE_BAKE_FLOATS = 28;
+export const BAKE_SKY_DRAWN = 27;
+export const BAKE_SKY_TOP = 28;
+export const BAKE_SKY_DEEP = 32;
+/** The sky's own sun, which at night is not the key light: the moon is. The sunset reads this. */
+export const BAKE_SKY_SUN = 36;
+/**
+ * DriftLight's field, as `driftLight/uniforms.ts` resolves it for a probe: how much is in and its
+ * scale in `x` and `w`, and where its grid starts with the spacing in `w`. Zero switches it off.
+ */
+export const BAKE_DRIFT_LIGHT = 40;
+export const BAKE_DRIFT_ORIGIN = 44;
+/**
+ * How many of the frame's exact lights `bounceLights` holds, and how the renderer shades a point
+ * light: 1 inverse-square, 0 the shaped falloff. See `gi/bounceLights.ts`.
+ */
+export const BAKE_LIGHT_COUNT = 48;
+export const BAKE_FALLOFF = 49;
+/** Rounded up to the struct's own sixteen-byte alignment: the lattice, five vec3 rows, three vec4. */
+export const PROBE_BAKE_FLOATS = 52;
+/** Rows of `bounceLights`: three a light. */
+export const BOUNCE_LIGHT_ROWS = (MAX_BOUNCE_LIGHTS * BOUNCE_LIGHT_FLOATS) / 4;
 /** Invocations a workgroup, for both entry points. 64 is this backend's default everywhere. */
 export const PROBE_BAKE_WORKGROUP = 64;
 /** Floats a ray's radiance takes in the intermediate buffer. */
@@ -67,17 +94,28 @@ struct ProbeBake {
   counts: vec3<f32>,
   /* Texels across one probe's map, gutter included. */
   edge: f32,
-  /* Which frame this is, which turns the direction set so a probe converges rather than repeats. */
+  /* How far the direction set is turned. The bake holds it at 0; the parity check turns it. */
   frame: f32,
   /* How many probes this dispatch bakes. The schedule says which. */
   scheduled: f32,
-  pad: f32,
+  /* How much of what a layer held each refresh keeps, 0 for a grid not yet traced whole. */
+  history: f32,
   /* Towards the sun, and what colour it is. The trace shades what it hits rather than reading a
      capture, which is what lets a bounce follow a light that moved. */
   sunDir: vec3<f32>,
   sunColour: vec3<f32>,
-  /* And what is outside, for a ray that left. See probeDistantRadiance. */
+  /* And what is outside, for a ray that left. See probeDistantRadiance and probeSkyAlong. */
   skyColour: vec3<f32>,
+  skyDrawn: f32,
+  skyTop: vec3<f32>,
+  skyDeep: vec3<f32>,
+  skySun: vec3<f32>,
+  /* The summed light of a scene's many fixed lights. See driftLight.wgsl.ts. */
+  driftLight: vec4<f32>,
+  driftOrigin: vec4<f32>,
+  /* How many of the frame's exact lights bounceLights holds, and 1 for inverse-square falloff. */
+  lightCount: f32,
+  falloff: f32,
 }
 `;
 /**
@@ -228,11 +266,18 @@ fn convolveMain(@builtin(global_invocation_id) id: vec3<u32>) {
      zero rather than dividing is what keeps it from being a hole if it ever does. */
   let scale = select(0.0, 1.0 / weights, weights > 0.0);
   let value = max(vec3<f32>(0.0), sum * scale);
+  /*
+   * **Blended into what the layer held, because one refresh is one estimate.** 256 rays over a set
+   * that turns every frame put two refreshes of a probe a few per cent apart, and written as they
+   * landed they were a shimmer about nine times a second. "bake.history" is 0 until the grid has
+   * been traced whole, so a first fill lands at once.
+   */
+  let kept = mix(value, probeHistory(schedule[slot], u, v), bake.history);
 
   let out = id.x * ${String(PROBE_TEXEL_FLOATS)}u;
-  irradiance[out] = value.x;
-  irradiance[out + 1u] = value.y;
-  irradiance[out + 2u] = value.z;
+  irradiance[out] = kept.x;
+  irradiance[out + 1u] = kept.y;
+  irradiance[out + 2u] = kept.z;
 }
 `;
 /**
@@ -281,6 +326,11 @@ fn probeLayerSample(layer: u32, uv: vec2<f32>) -> vec3<f32> {
   return vec3<f32>(probeValues[at], probeValues[at + 1u], probeValues[at + 2u]);
 }
 
+/* No history: this module's refreshes are checked as single estimates, and "bake.history" is 0. */
+fn probeHistory(layer: u32, u: u32, v: u32) -> vec3<f32> {
+  return vec3<f32>(0.0);
+}
+
 /* The same flat value: this module checks the blend, and what a production texture holds at its
    two levels is what makes them different. */
 fn probeLayerIrradiance(layer: u32, uv: vec2<f32>) -> vec3<f32> {
@@ -364,6 +414,10 @@ fn echoMain(@builtin(global_invocation_id) id: vec3<u32>) {
   irradiance[9] = bake.edge;
   irradiance[10] = bake.frame;
   irradiance[11] = bake.scheduled;
+  irradiance[12] = bake.skyDrawn;
+  irradiance[13] = bake.skyTop.x;
+  irradiance[14] = bake.skyDeep.x;
+  irradiance[15] = bake.skySun.x;
 }
 
 /* The encode, which is a different function from the fold "texelMain" checks and needs its own. */
@@ -440,7 +494,19 @@ ${PROBE_VOLUME_STRUCT_WGSL}
 @group(0) @binding(9) var probeSampler: sampler;
 /* The colour of whatever won the union at each sample, three floats, same layout as the field. */
 @group(0) @binding(10) var<storage, read> albedoField: array<f32>;
+/* DriftLight's brick index and atlas, or one-texel stand-ins while driftLight.x is zero. */
+@group(0) @binding(11) var driftIndex: texture_3d<u32>;
+@group(0) @binding(12) var driftAtlas: texture_3d<f32>;
+@group(0) @binding(13) var driftSampler: sampler;
+/* The frame's exact lights, three rows each: see gi/bounceLights.ts for what each row holds. */
+@group(0) @binding(14) var<uniform> bounceLights: array<vec4<f32>, ${String(BOUNCE_LIGHT_ROWS)}>;
 ${SAMPLE_FIELD_WGSL}
+${DRIFT_LIGHT_WGSL}
+
+/* What a layer's irradiance level holds at a texel, which the convolution blends into. */
+fn probeHistory(layer: u32, u: u32, v: u32) -> vec3<f32> {
+  return textureLoad(probeArray, vec2<i32>(i32(u), i32(v)), i32(layer), i32(volume.level)).rgb;
+}
 
 /*
  * The albedo at a world point, from the finest cascade that holds it, by nearest sample.
@@ -553,13 +619,111 @@ fn probeSurfaceRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32> {
   /*
    * And what has already bounced, which is the level this bake writes — so the loop closes.
    *
-   * **Divided by pi once and not twice.** "convolveProbe" normalises by the cosine weights it
-   * actually used, so what a probe stores is the cosine-weighted *mean radiance*, which is already
-   * the irradiance over pi — the convention a Lambertian's outgoing radiance multiplies directly
-   * by its albedo. Only the sun's own irradiance needs the division.
+   * **Neither term is divided by pi, because the frame divides neither.** "convolveProbe"
+   * normalises by the cosine weights it actually used, so a probe stores the cosine-weighted
+   * *mean radiance*, which a Lambertian's outgoing radiance multiplies directly by its albedo. And
+   * the flat shader lights a surface with "albedo * (ambient + directionalColor * cosine)", so
+   * "directionalColor" is the radiance a white surface facing the sun sends back rather than an
+   * irradiance. This divided the sun by pi until 2026-09-27, and every sunlit wall a probe struck
+   * came back a third as bright as the frame drew it: a room lit through its one open side read
+   * 66 of 255 on its far wall against a path-traced 200 ("scripts/bounce-check.mjs"). What would
+   * make it wrong is a flat shader that divides its own sun by pi; "probeBake.test.ts" reads both.
    */
   let bounced = probeVolumeIrradianceAt(p, n);
-  return albedo * (direct * ${String(1 / Math.PI)} + bounced);
+  /*
+   * And the summed light of the scene's many fixed lights, which is how a candle nobody is near
+   * reaches the bounce: the trace shades a hit with the sun alone otherwise. At the presence and
+   * scale the frame reads it with, and with no share, because a probe sees every fixed light through
+   * the volume (driftLight/uniforms.ts).
+   */
+  let summed = driftLightIrradiance(p, n, bake.driftOrigin) * (bake.driftLight.x * bake.driftLight.w);
+  return albedo * (direct + bounced + summed + probeLampsAt(p, n));
+}
+
+/*
+ * Whether a lamp reaches a point, by marching the field towards it and stopping short.
+ *
+ * **Short of the lamp by its fixture.** A flame stands inside a lantern and a bulb inside a shade,
+ * and a field a quarter of a metre fine draws those as solid: a march that ran all the way would
+ * find the lantern round every lantern and shade every one of them out. So it stops a fixture's
+ * width away, the larger of 30 cm and two of the finest voxels, and what it gives up is an occluder
+ * that close to a lamp.
+ */
+fn probeLampVisible(p: vec3<f32>, n: vec3<f32>, toward: vec3<f32>, span: f32) -> f32 {
+  let lifted = p + n * (PROBE_FIELD_START_VOXELS * march.finestStep);
+  var travelled = 0.0;
+  for (var step = 0u; step < march.steps; step = step + 1u) {
+    if (travelled >= span) { return 1.0; }
+    let at = lifted + toward * travelled;
+    if (probeFieldInside(at) <= 0.0) { return 1.0; }
+    let distance = probeFieldAt(at);
+    if (distance <= march.hitEpsilonM) { return 0.0; }
+    travelled = travelled + max(distance, march.finestStep * 0.25);
+  }
+  return 1.0;
+}
+
+/*
+ * The frame's exact lights on a surface a ray struck: the lit shader's lamp term, line for line
+ * (probeBake.test.ts holds the two together), with the field's own shadow in place of a lamp's
+ * shadow map. Not a photometric profile or a cookie, which the bounce reads as a plain cone.
+ */
+fn probeLampsAt(p: vec3<f32>, n: vec3<f32>) -> vec3<f32> {
+  var sum = vec3<f32>(0.0);
+  let count = u32(bake.lightCount);
+  for (var i = 0u; i < count; i = i + 1u) {
+    let at = bounceLights[i * 3u];
+    let colour = bounceLights[i * 3u + 1u];
+    let aim = bounceLights[i * 3u + 2u];
+    let lightRadius = at.w;
+    let toLight = at.xyz - p;
+    let dist = length(toLight);
+    let coneFalloff = smoothstep(aim.w, colour.w, dot(-toLight / max(dist, 1e-4), aim.xyz));
+    var falloff: f32;
+    if (bake.falloff == 1.0) {
+      let window = clamp(1.0 - pow(dist / max(lightRadius, 1e-4), 4.0), 0.0, 1.0);
+      falloff = window * window / max(dist * dist, 0.01);
+    } else {
+      falloff = clamp(1.0 - dist / lightRadius, 0.0, 1.0);
+    }
+    if (falloff <= 0.0) { continue; }
+    let ndl = max(dot(n, toLight / max(dist, 1e-4)), 0.0);
+    if (ndl <= 0.0) { continue; }
+    let shape = select(falloff * falloff, falloff, bake.falloff == 1.0) * coneFalloff;
+    if (shape <= 0.0) { continue; }
+    let fixture = max(0.3, 2.0 * march.finestStep);
+    let seen = probeLampVisible(p, n, toLight / max(dist, 1e-4), dist - fixture);
+    sum = sum + colour.rgb * ndl * shape * seen;
+  }
+  return sum;
+}
+
+/*
+ * The sky the frame drew, along a direction: the sky shader's gradient and its two sunset bands,
+ * transcribed line for line (probeBake.test.ts holds the two together). Not its sun, moon, stars or
+ * clouds: the sun reaches a probe as direct light at what the ray strikes, and the rest is a few
+ * per cent of a sky's light. Where the frame drew no sky, the environment's ambient, flat.
+ */
+fn probeSkyAlong(d: vec3<f32>) -> vec3<f32> {
+  if (bake.skyDrawn < 0.5) { return bake.skyColour; }
+  let t = d.y;
+  var col: vec3<f32>;
+  if (t >= 0.0) {
+    col = mix(bake.skyColour, bake.skyTop, pow(min(t, 1.0), 0.55));
+  } else {
+    col = mix(bake.skyColour, bake.skyDeep, min(-t * 1.8, 1.0));
+  }
+  let sunset = (1.0 - smoothstep(-0.03, 0.30, bake.skySun.y)) * smoothstep(-0.35, -0.05, bake.skySun.y);
+  let ember = vec3<f32>(1.0, 0.36, 0.13);
+  let sunBearing = normalize(bake.skySun.xz + vec2<f32>(1e-5));
+  let viewBearing = normalize(d.xz + vec2<f32>(1e-5));
+  let toward = max(dot(viewBearing, sunBearing), 0.0);
+  let fromHorizon = select(-t * 3.0, t, t >= 0.0);
+  let band = pow(1.0 - min(fromHorizon * 2.2, 1.0), 2.6);
+  col += ember * sunset * band * (0.18 + 0.75 * pow(toward, 2.2));
+  let away = max(-dot(viewBearing, sunBearing), 0.0);
+  col += vec3<f32>(0.42, 0.28, 0.45) * sunset * band * away * 0.22;
+  return col;
 }
 
 /*
@@ -567,15 +731,21 @@ fn probeSurfaceRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32> {
  *
  * **Not the probe array's own level 0, and that was measured rather than reasoned.** Level 0 is a
  * *rasterised* capture taken once, so a ray reading it gathers the light the room had when the
- * capture was made — and a room whose red wall was repainted blue went on bouncing red, because
- * most of its rays escaped through the opening and read the capture. With the sky here instead,
- * **nothing in the trace reads anything rasterised**, which is what lets the whole solution follow
- * a scene that changes and is the sentence Wave 4's criterion asks for.
+ * capture was made, and a room whose red wall was repainted blue went on bouncing red, because
+ * most of its rays escaped through the opening and read the capture. The sky is the frame's own
+ * numbers, so **nothing in the trace reads anything rasterised** and the solution follows a scene
+ * that changes.
+ *
+ * **The sky drawn, and not the environment's ambient, since 2026-09-27.** The ambient is a grade's
+ * fill for surfaces the probes do not reach, and a palette sets it apart from the sky: at ten
+ * degrees of sun a courtyard's was five times dimmer than its horizon, and blue where the horizon
+ * was amber, so traced shade at dusk came out cool against the rasterised grid that saw the sky.
  *
- * No albedo and no sun: nothing was struck, so there is no surface to shade.
+ * No albedo and no sun: nothing was struck, so there is no surface to shade. "towards" points back
+ * down the ray, so the sky is read along its opposite.
  */
 fn probeDistantRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32> {
-  return bake.skyColour;
+  return probeSkyAlong(-towards);
 }
 ${PROBE_TRACE_CORE_WGSL}
 ${PROBE_BAKE_CORE_WGSL}

package/dist/render/shaders/globalMedium.js

@@ -290,6 +290,10 @@ void main() {
  */
 export const MEDIUM_UPSAMPLE_FRAG = `#version 300 es
 precision highp float;
+/* highp int, by the rule every fragment stage doing bit arithmetic keeps: the footprint below is
+   picked with a mask and a shift. At four values it would survive sixteen bits, and a gate that
+   has to judge which masks are small is a gate nobody can hold. */
+precision highp int;
 
 in vec2 vUv;
 

package/dist/render/shaders/localExposure.d.ts

@@ -0,0 +1,35 @@
+/** Bands of log luminance, and how many stops each is wide. */
+export declare const LOCAL_BINS = 10;
+export declare const LOCAL_BIN_STOPS: number;
+/** The grid's width in texels: a block of tiles per band, and one for the tiles' means. */
+export declare const LOCAL_GRID_WIDTH: number;
+/** How far a pixel's band level is blended toward its tile's mean. */
+export declare const LOCAL_BLURRED_BLEND = 0.4;
+/** The furthest a region is moved either way, in stops. */
+export declare const LOCAL_RANGE_STOPS = 3;
+/**
+ * The grid: one texel a tile a band. Each reads its tile's 8 × 8 taps, as the meter does, and keeps
+ * the ones in its band; the last block keeps them all. Sum and count are both divided by the taps,
+ * so the filtered pair in the composite is still a weighted mean.
+ */
+export declare const EXPOSURE_LOCAL_FRAG: string;
+/**
+ * The composite's half. Needs `AUTO_EXPOSURE_GLSL` before it, for the held brightness.
+ *
+ * A block is read clamped half a texel inside its own tiles, so the filter never reaches into the
+ * neighbouring band's block. Every fetch is at level zero: the grid has one level, and the branch
+ * on the strength above them is uniform but the pixel's band is not.
+ */
+export declare const LOCAL_EXPOSURE_GLSL: string;
+/** The two bands a pixel at `pixelLog2` reads, and how much of the upper, as the shader finds them. */
+export declare function localBin(pixelLog2: number): {
+    lower: number;
+    upper: number;
+    weight: number;
+};
+/** A pixel's local level from its two bands' sums and counts and its tile's mean, as the shader. */
+export declare function sliceLocal(sumLower: number, countLower: number, sumUpper: number, countUpper: number, weight: number, tileMean: number): number;
+/** A region's gain for a local level and the frame's held one at `strength`, as the composite. */
+export declare function localExposureGain(localLog2: number, heldLog2: number, strength: number): number;
+/** A local exposure strength as the shader takes it: 0 to 1, anything else off. */
+export declare function clampLocalExposure(strength: number): number;

package/dist/render/shaders/localExposure.js

@@ -0,0 +1,138 @@
+/**
+ * Local exposure: each region of the frame brought part of the way toward the frame's own
+ * brightness, so shade and sun can both be read in one picture.
+ *
+ * **A tone curve maps one range, and a sunlit courtyard is two.** Measured in a bought courtyard at
+ * noon, the shaded arcades hold a fiftieth of the light the sunlit paving does, which is what the
+ * place is: a canyon lit mostly by its own walls. Exposed for the paving the arcades go to black,
+ * exposed for the arcades the paving goes to white, and no curve fixes both, because a curve is a
+ * function of a pixel's brightness and the same brightness has to mean shade in one place and sun in
+ * another. A photographer brackets; an eye adapts by region. This is the second.
+ *
+ * **A bilateral grid over the exposure meter's tiles.** The grid pass writes, for each of the
+ * meter's 32 × 32 tiles and each of ten two-stop bands of log luminance, the sum and the share of
+ * the tile's taps that fell in that band, and in an eleventh block the tile's mean. The composite
+ * reads the grid at the pixel's place and in the pixel's own band, filtered in both, so a shaded
+ * pixel beside sunlit ones takes the shade's level rather than the tile's: that is what keeps the
+ * lift from haloing across the edge of a shadow. The band's level is blended 0.4 toward the tile's
+ * mean, which is what stops a texture's own light and dark being flattened into one another.
+ *
+ * **The gain is `strength · (held − local)` stops**, clamped to three: at 0.5 a region five stops
+ * under the frame is lifted two and a half, and one two over is brought down one. The held value is
+ * eye adaptation's, so the frame as a whole still adapts and regions are moved relative to it.
+ *
+ * What it gives up is some of the contrast between regions, which is the point, and a halo a tile
+ * wide where two regions share a band and differ in brightness. What would make it wrong is a scene
+ * whose drama is the contrast itself: a single shaft into a dark room wants the room dark, and the
+ * strength is the caller's for that reason.
+ */
+import { METER_GRID, METER_MAX_LOG2, METER_MIN_LOG2, METER_TAPS } from './exposure.js';
+/** Bands of log luminance, and how many stops each is wide. */
+export const LOCAL_BINS = 10;
+export const LOCAL_BIN_STOPS = (METER_MAX_LOG2 - METER_MIN_LOG2) / LOCAL_BINS;
+/** The grid's width in texels: a block of tiles per band, and one for the tiles' means. */
+export const LOCAL_GRID_WIDTH = METER_GRID * (LOCAL_BINS + 1);
+/** How far a pixel's band level is blended toward its tile's mean. */
+export const LOCAL_BLURRED_BLEND = 0.4;
+/** The furthest a region is moved either way, in stops. */
+export const LOCAL_RANGE_STOPS = 3;
+const BLOCKS = (LOCAL_BINS + 1).toFixed(1);
+const GRID = METER_GRID.toFixed(1);
+const MIN = METER_MIN_LOG2.toFixed(1);
+const MAX = METER_MAX_LOG2.toFixed(1);
+const STOPS = LOCAL_BIN_STOPS.toFixed(1);
+const LAST = (LOCAL_BINS - 1).toFixed(1);
+/**
+ * The grid: one texel a tile a band. Each reads its tile's 8 × 8 taps, as the meter does, and keeps
+ * the ones in its band; the last block keeps them all. Sum and count are both divided by the taps,
+ * so the filtered pair in the composite is still a weighted mean.
+ */
+export const EXPOSURE_LOCAL_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/** The finished scene, in scene light, before any exposure or curve. */
+uniform highp sampler2D uScene;
+
+out vec2 fragColor;
+
+void main() {
+  float uvBlock = vUv.x * ${BLOCKS};
+  float band = floor(uvBlock);
+  vec2 corner = vec2(fract(uvBlock), vUv.y) - vec2(0.5 / ${GRID});
+  float sum = 0.0;
+  float count = 0.0;
+  for (int y = 0; y < ${METER_TAPS}; y++) {
+    for (int x = 0; x < ${METER_TAPS}; x++) {
+      vec2 uv = corner + (vec2(float(x), float(y)) + 0.5) / ${(METER_GRID * METER_TAPS).toFixed(1)};
+      vec3 c = textureLod(uScene, uv, 0.0).rgb;
+      float level = clamp(log2(max(dot(c, vec3(0.2126, 0.7152, 0.0722)), 1e-8)), ${MIN}, ${MAX});
+      float tapBand = floor(clamp((level - ${MIN}) / ${STOPS}, 0.0, ${LAST}));
+      float kept = band > ${LAST} || tapBand == band ? 1.0 : 0.0;
+      sum += level * kept;
+      count += kept;
+    }
+  }
+  fragColor = vec2(sum, count) / ${(METER_TAPS * METER_TAPS).toFixed(1)};
+}
+`;
+/**
+ * The composite's half. Needs `AUTO_EXPOSURE_GLSL` before it, for the held brightness.
+ *
+ * A block is read clamped half a texel inside its own tiles, so the filter never reaches into the
+ * neighbouring band's block. Every fetch is at level zero: the grid has one level, and the branch
+ * on the strength above them is uniform but the pixel's band is not.
+ */
+export const LOCAL_EXPOSURE_GLSL = `
+/** How far each region is brought toward the frame, 0 to 1. 0 is off and the whole of the off path. */
+uniform float uLocalExposure;
+/** The bilateral grid: a block of tiles per band of brightness, and one of the tiles' means. */
+uniform highp sampler2D uExposureLocal;
+
+vec2 localBlock(vec2 uv, float block) {
+  vec2 inside = clamp(uv, vec2(0.5 / ${GRID}), vec2(1.0 - 0.5 / ${GRID}));
+  return textureLod(uExposureLocal, vec2((block + inside.x) / ${BLOCKS}, inside.y), 0.0).rg;
+}
+
+float localExposureGain(vec2 uv, vec3 light) {
+  if (uLocalExposure <= 0.0) return 1.0;
+  float held = texelFetch(uExposureHeld, ivec2(0, 0), 0).r;
+  float pixel = clamp(log2(max(dot(light, vec3(0.2126, 0.7152, 0.0722)), 1e-8)), ${MIN}, ${MAX});
+  float b = (pixel - ${MIN}) / ${STOPS} - 0.5;
+  float lower = clamp(floor(b), 0.0, ${LAST});
+  float upper = min(lower + 1.0, ${LAST});
+  vec2 banded = mix(localBlock(uv, lower), localBlock(uv, upper), clamp(b - lower, 0.0, 1.0));
+  float tileMean = localBlock(uv, ${LOCAL_BINS.toFixed(1)}).r;
+  float bilateral = banded.y > 1e-3 ? banded.x / banded.y : tileMean;
+  float local = mix(bilateral, tileMean, ${LOCAL_BLURRED_BLEND.toFixed(1)});
+  float stops = uLocalExposure * (held - local);
+  return exp2(clamp(stops, -${LOCAL_RANGE_STOPS.toFixed(1)}, ${LOCAL_RANGE_STOPS.toFixed(1)}));
+}
+`;
+const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+/** The two bands a pixel at `pixelLog2` reads, and how much of the upper, as the shader finds them. */
+export function localBin(pixelLog2) {
+    const pixel = clamp(pixelLog2, METER_MIN_LOG2, METER_MAX_LOG2);
+    const b = (pixel - METER_MIN_LOG2) / LOCAL_BIN_STOPS - 0.5;
+    const lower = clamp(Math.floor(b), 0, LOCAL_BINS - 1);
+    return { lower, upper: Math.min(lower + 1, LOCAL_BINS - 1), weight: clamp(b - lower, 0, 1) };
+}
+/** A pixel's local level from its two bands' sums and counts and its tile's mean, as the shader. */
+export function sliceLocal(sumLower, countLower, sumUpper, countUpper, weight, tileMean) {
+    const sum = sumLower + (sumUpper - sumLower) * weight;
+    const count = countLower + (countUpper - countLower) * weight;
+    const bilateral = count > 1e-3 ? sum / count : tileMean;
+    return bilateral + (tileMean - bilateral) * LOCAL_BLURRED_BLEND;
+}
+/** A region's gain for a local level and the frame's held one at `strength`, as the composite. */
+export function localExposureGain(localLog2, heldLog2, strength) {
+    if (!(strength > 0))
+        return 1;
+    const stops = strength * (heldLog2 - localLog2);
+    return 2 ** clamp(stops, -LOCAL_RANGE_STOPS, LOCAL_RANGE_STOPS);
+}
+/** A local exposure strength as the shader takes it: 0 to 1, anything else off. */
+export function clampLocalExposure(strength) {
+    return Number.isFinite(strength) ? clamp(strength, 0, 1) : 0;
+}

package/dist/render/shaders/prefilter.d.ts

@@ -34,4 +34,4 @@
  * difference between one cube and a cube per camera. **What would make it wrong** is a scene
  * where grazing metal is the subject rather than incidental.
  */
-export declare const PREFILTER_FRAG = "#version 300 es\nprecision highp float;\n\nvec2 octEncode(vec3 d) {\n  vec3 n = d / (abs(d.x) + abs(d.y) + abs(d.z));\n  vec2 p = n.z >= 0.0\n    ? n.xy\n    : (1.0 - abs(vec2(n.y, n.x))) * vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);\n  return p * 0.5 + 0.5;\n}\n\nvec3 octDecode(vec2 uv) {\n  vec2 f = uv * 2.0 - 1.0;\n  vec3 n = vec3(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));\n  float t = max(-n.z, 0.0);\n  n.x += n.x >= 0.0 ? -t : t;\n  n.y += n.y >= 0.0 ? -t : t;\n  return normalize(n);\n}\n\nvec2 octWrapUv(vec2 uv) {\n  vec2 f = uv * 2.0 - 1.0;\n  if (f.x < -1.0 || f.x > 1.0) {\n    f.x = (f.x > 0.0 ? 2.0 : -2.0) - f.x;\n    f.y = -f.y;\n  }\n  if (f.y < -1.0 || f.y > 1.0) {\n    f.y = (f.y > 0.0 ? 2.0 : -2.0) - f.y;\n    f.x = -f.x;\n  }\n  return f * 0.5 + 0.5;\n}\n\nvec2 octInsetUv(vec3 d, float edge) {\n  return (octEncode(d) * (edge - 2.0) + 1.0) / edge;\n}\n\nvec3 octInsetDir(vec2 uv, float edge) {\n  return octDecode(octWrapUv((uv * edge - 1.0) / (edge - 2.0)));\n}\n\nin vec2 vUv;\n\n/** The captured probe, box-filtered, which this convolves. Never the cube being written. */\nuniform highp samplerCube uPrefilterSource;\n\n/**\n * The edge of the level being written, in texels, which is what the inset is derived from.\n *\n * The level's own size rather than the array's, because a gutter is one texel at every level and\n * its share of the map therefore doubles as the chain coarsens. A base edge passed here instead\n * would inset every level by the base's fraction, which is a fifth of a texel at the top of the\n * chain and reads as the reflection sliding as roughness rises.\n */\nuniform float uPrefilterEdge;\n\n/** 1 on the level holding the cosine convolution, 0 on every level of the reflection chain. */\nuniform float uPrefilterIrradiance;\n\n/**\n * 1 when the reflection chain is a box filter rather than a GGX convolution.\n *\n * RenderQuality.environmentPrefilter is off by default, and that default is a correction rather\n * than a preference: the prefilter shipped wired straight into the lit pass and changed the\n * picture of every consumer that had a probe, which was reported as metals reading opaque. A\n * profile that has not asked for the lobe chain must get the same reflection it had before probes\n * moved into an array, so the box arm exists and is what that profile bakes.\n *\n * The array edge is twice the source cube's face, so one array level matches one cube level in\n * angular density and the box arm is a single fetch at the same index. There is no second\n * texture: the flag decides what is convolved into the layer rather than which of two chains is\n * bound, so it is read at bake time and a profile that changes it has to bake again.\n */\nuniform float uPrefilterBox;\n\n/** The level being written, for the box arm, which reads the source chain at the same index. */\nuniform float uPrefilterLevel;\n\n/** The roughness this level stands for, from roughnessForLevel. 0 is a mirror. */\nuniform float uPrefilterRoughness;\n/** Samples per texel, from PREFILTER_SAMPLE_COUNTS. A power of two; see the count's own note. */\nuniform float uPrefilterSamples;\n/** The source cube's face width in texels, for the solid-angle comparison below. */\nuniform float uPrefilterSourceTexels;\n/** The source chain's top level, so a wide sample cannot ask for a level that is not there. */\nuniform float uPrefilterSourceMaxLod;\n\nout vec4 fragColor;\n\nconst float PI = 3.14159265359;\n\n/**\n * The radical inverse of a 32-bit integer, base two: the second dimension of a Hammersley set.\n *\n * A bit reversal, written as the standard five-shift sequence rather than a loop, because a loop\n * over 32 bits per sample per texel is the one place in a bake where the arithmetic is the cost.\n * **This is why every sample count is a power of two** \u2014 the sequence's stratification is only\n * even when the count is, and an uneven one shows as a faint directional bias in a rough level\n * rather than as an error anybody would notice.\n */\nfloat radicalInverse(uint bits) {\n  bits = (bits << 16u) | (bits >> 16u);\n  bits = ((bits & 0x55555555u) << 1u) | ((bits & 0xAAAAAAAAu) >> 1u);\n  bits = ((bits & 0x33333333u) << 2u) | ((bits & 0xCCCCCCCCu) >> 2u);\n  bits = ((bits & 0x0F0F0F0Fu) << 4u) | ((bits & 0xF0F0F0F0u) >> 4u);\n  bits = ((bits & 0x00FF00FFu) << 8u) | ((bits & 0xFF00FF00u) >> 8u);\n  return float(bits) * 2.3283064365386963e-10;\n}\n\n/**\n * A half vector drawn from the GGX distribution about the normal, for one Hammersley pair.\n *\n * Importance sampling rather than a uniform hemisphere: at low roughness the lobe occupies a\n * vanishing fraction of the hemisphere, so uniform samples would put almost every one of them\n * where the weight is zero and the few that land in the lobe would carry all the variance.\n */\nvec3 importanceSampleGgx(vec2 xi, vec3 n, float roughness) {\n  float a = roughness * roughness;\n\n  float phi = 2.0 * PI * xi.x;\n  float cosTheta = sqrt((1.0 - xi.y) / (1.0 + (a * a - 1.0) * xi.y));\n  float sinTheta = sqrt(1.0 - cosTheta * cosTheta);\n\n  vec3 h = vec3(sinTheta * cos(phi), sinTheta * sin(phi), cosTheta);\n\n  /*\n   * Any tangent will do as long as it is not parallel to the normal, and the choice of which\n   * axis to cross against has to depend on the normal or it degenerates at the poles \u2014 which is\n   * one face of six coming out as noise, on the two faces the axis points at.\n   */\n  vec3 up = abs(n.z) < 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(1.0, 0.0, 0.0);\n  vec3 tangentX = normalize(cross(up, n));\n  vec3 tangentY = cross(n, tangentX);\n\n  return normalize(tangentX * h.x + tangentY * h.y + n * h.z);\n}\n\n/**\n * A direction drawn from the cosine lobe about the normal, for the diffuse level.\n *\n * **Cosine-weighted, which is what makes the estimator a plain mean.** Irradiance is\n * integral of L cos(theta), the cosine pdf is cos(theta) / pi, so the estimate is\n * pi / N * sum(L) \u2014 and what the lit pass wants is radiance rather than irradiance, so the pi\n * divides straight back out. irradianceSh.ts folds the same division into its band factors and\n * says so, which is what makes a grid of one reproduce what the projection produced.\n */\nvec3 importanceSampleCosine(vec2 xi, vec3 n) {\n  float phi = 2.0 * PI * xi.x;\n  float cosTheta = sqrt(max(1.0 - xi.y, 0.0));\n  float sinTheta = sqrt(xi.y);\n\n  vec3 h = vec3(sinTheta * cos(phi), sinTheta * sin(phi), cosTheta);\n\n  vec3 up = abs(n.z) < 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(1.0, 0.0, 0.0);\n  vec3 tangentX = normalize(cross(up, n));\n  vec3 tangentY = cross(n, tangentX);\n\n  return normalize(tangentX * h.x + tangentY * h.y + n * h.z);\n}\n\n/** Trowbridge-Reitz, in its own normalisation, because this is a probability rather than a look. */\nfloat ggxDistribution(float ndh, float roughness) {\n  float a = roughness * roughness;\n  float a2 = a * a;\n  float d = ndh * ndh * (a2 - 1.0) + 1.0;\n  return a2 / max(PI * d * d, 1e-8);\n}\n\nvoid main() {\n  vec3 n = octInsetDir(vUv, uPrefilterEdge);\n\n  float texelSolidAngle = 4.0 * PI / (6.0 * uPrefilterSourceTexels * uPrefilterSourceTexels);\n\n  /*\n   * The box chain, which is one fetch: the source's own level at the same index, resampled through\n   * the octahedral mapping. It is what a profile that has not asked for the lobe chain gets, and\n   * it is the picture every consumer with a probe already had.\n   */\n  if (uPrefilterBox > 0.5 && uPrefilterIrradiance <= 0.5) {\n    fragColor = vec4(\n      textureLod(uPrefilterSource, n, min(uPrefilterLevel, uPrefilterSourceMaxLod)).rgb,\n      1.0\n    );\n    return;\n  }\n\n  /*\n   * **The diffuse level, and it is a mean rather than a weighted sum.** Every cosine sample is\n   * drawn with the weight already in its density, so there is nothing to accumulate a weight for\n   * and nothing to divide by but the count. A sample below the horizon cannot occur, which is the\n   * other half of why this arm has no continue in it.\n   */\n  if (uPrefilterIrradiance > 0.5) {\n    vec3 diffuse = vec3(0.0);\n    int cosineSamples = int(uPrefilterSamples);\n    for (int i = 0; i < cosineSamples; i++) {\n      vec2 xi = vec2(float(i) / uPrefilterSamples, radicalInverse(uint(i)));\n      vec3 l = importanceSampleCosine(xi, n);\n      /*\n       * The same filtered importance sampling the reflection uses, against the cosine density.\n       * A diffuse sample is wide \u2014 a sixth of the sphere at the median \u2014 so reading the base level\n       * would carry a bright window through as a handful of fireflies in the ambient, which is the\n       * one place they cannot be blurred out later.\n       */\n      float pdf = max(dot(n, l) / PI, 1e-4);\n      float sampleSolidAngle = 1.0 / (uPrefilterSamples * pdf);\n      float lod = clamp(\n        0.5 * log2(sampleSolidAngle / texelSolidAngle),\n        0.0,\n        uPrefilterSourceMaxLod\n      );\n      diffuse += textureLod(uPrefilterSource, l, lod).rgb;\n    }\n    fragColor = vec4(diffuse / max(uPrefilterSamples, 1.0), 1.0);\n    return;\n  }\n\n  /*\n   * A mirror is a fetch rather than an integral, and it is a separate arm on purpose: at\n   * roughness 0 the distribution is a delta, every importance sample collapses onto the same\n   * direction, and the sum is one sample's worth of noise where the answer is exactly the texel.\n   */\n  if (uPrefilterRoughness <= 0.0) {\n    fragColor = vec4(textureLod(uPrefilterSource, n, 0.0).rgb, 1.0);\n    return;\n  }\n\n  vec3 sum = vec3(0.0);\n  float weight = 0.0;\n\n  int samples = int(uPrefilterSamples);\n  for (int i = 0; i < samples; i++) {\n    vec2 xi = vec2(float(i) / uPrefilterSamples, radicalInverse(uint(i)));\n    vec3 h = importanceSampleGgx(xi, n, uPrefilterRoughness);\n    vec3 l = normalize(2.0 * dot(n, h) * h - n);\n\n    float ndl = dot(n, l);\n    if (ndl <= 0.0) continue;\n\n    /*\n     * Filtered importance sampling. A sample covers 1 / (count * pdf) of the sphere; when that\n     * is much wider than a texel, reading the base level lets a few very bright texels land in\n     * some samples and not others, and the variance survives the average as fireflies. The half\n     * in front of the logarithm is a length ratio against an area one \u2014 a level step doubles a\n     * texel's width and quadruples its solid angle. sourceLevelForSample holds the same\n     * arithmetic on the CPU and its test carries the hand-derived numbers.\n     */\n    float ndh = max(dot(n, h), 0.0);\n    float pdf = max(ggxDistribution(ndh, uPrefilterRoughness) * 0.25, 1e-8);\n    float sampleSolidAngle = 1.0 / (uPrefilterSamples * pdf);\n    float lod = clamp(\n      0.5 * log2(sampleSolidAngle / texelSolidAngle),\n      0.0,\n      uPrefilterSourceMaxLod\n    );\n\n    /*\n     * textureLod rather than texture, and the 2026-08-07 rule is why: this fetch sits inside a\n     * loop with a continue in it, which no compiler can prove uniform, and an implicit derivative\n     * in non-uniform control flow is what lets a driver flatten the loop and cost every arm.\n     * The level is wanted here anyway, so the rule costs nothing at all.\n     */\n    sum += textureLod(uPrefilterSource, l, lod).rgb * ndl;\n    weight += ndl;\n  }\n\n  /*\n   * Normalised by the accumulated weight rather than by the sample count, because samples with\n   * a light below the horizon were skipped and dividing by the count would darken every rough\n   * level by the fraction that missed \u2014 which reads as roughness losing energy and is exactly\n   * the artefact uEnvironmentGain has been compensating for.\n   */\n  fragColor = vec4(sum / max(weight, 1e-4), 1.0);\n}\n";
+export declare const PREFILTER_FRAG = "#version 300 es\nprecision highp float;\n/*\n * highp int as well, because the radical inverse below is a 32-bit bit reversal and the fragment\n * default for int and uint is mediump. A driver that computes mediump in sixteen bits returns 0\n * for every sample, and every cosine sample of the diffuse level lands on its own normal.\n */\nprecision highp int;\n\nvec2 octEncode(vec3 d) {\n  vec3 n = d / (abs(d.x) + abs(d.y) + abs(d.z));\n  vec2 p = n.z >= 0.0\n    ? n.xy\n    : (1.0 - abs(vec2(n.y, n.x))) * vec2(n.x >= 0.0 ? 1.0 : -1.0, n.y >= 0.0 ? 1.0 : -1.0);\n  return p * 0.5 + 0.5;\n}\n\nvec3 octDecode(vec2 uv) {\n  vec2 f = uv * 2.0 - 1.0;\n  vec3 n = vec3(f.x, f.y, 1.0 - abs(f.x) - abs(f.y));\n  float t = max(-n.z, 0.0);\n  n.x += n.x >= 0.0 ? -t : t;\n  n.y += n.y >= 0.0 ? -t : t;\n  return normalize(n);\n}\n\nvec2 octWrapUv(vec2 uv) {\n  vec2 f = uv * 2.0 - 1.0;\n  if (f.x < -1.0 || f.x > 1.0) {\n    f.x = (f.x > 0.0 ? 2.0 : -2.0) - f.x;\n    f.y = -f.y;\n  }\n  if (f.y < -1.0 || f.y > 1.0) {\n    f.y = (f.y > 0.0 ? 2.0 : -2.0) - f.y;\n    f.x = -f.x;\n  }\n  return f * 0.5 + 0.5;\n}\n\nvec2 octInsetUv(vec3 d, float edge) {\n  return (octEncode(d) * (edge - 2.0) + 1.0) / edge;\n}\n\nvec3 octInsetDir(vec2 uv, float edge) {\n  return octDecode(octWrapUv((uv * edge - 1.0) / (edge - 2.0)));\n}\n\nin vec2 vUv;\n\n/** The captured probe, box-filtered, which this convolves. Never the cube being written. */\nuniform highp samplerCube uPrefilterSource;\n\n/**\n * The edge of the level being written, in texels, which is what the inset is derived from.\n *\n * The level's own size rather than the array's, because a gutter is one texel at every level and\n * its share of the map therefore doubles as the chain coarsens. A base edge passed here instead\n * would inset every level by the base's fraction, which is a fifth of a texel at the top of the\n * chain and reads as the reflection sliding as roughness rises.\n */\nuniform float uPrefilterEdge;\n\n/** 1 on the level holding the cosine convolution, 0 on every level of the reflection chain. */\nuniform float uPrefilterIrradiance;\n\n/**\n * 1 when the reflection chain is a box filter rather than a GGX convolution.\n *\n * RenderQuality.environmentPrefilter is off by default, and that default is a correction rather\n * than a preference: the prefilter shipped wired straight into the lit pass and changed the\n * picture of every consumer that had a probe, which was reported as metals reading opaque. A\n * profile that has not asked for the lobe chain must get the same reflection it had before probes\n * moved into an array, so the box arm exists and is what that profile bakes.\n *\n * The array edge is twice the source cube's face, so one array level matches one cube level in\n * angular density and the box arm is a single fetch at the same index. There is no second\n * texture: the flag decides what is convolved into the layer rather than which of two chains is\n * bound, so it is read at bake time and a profile that changes it has to bake again.\n */\nuniform float uPrefilterBox;\n\n/** The level being written, for the box arm, which reads the source chain at the same index. */\nuniform float uPrefilterLevel;\n\n/** The roughness this level stands for, from roughnessForLevel. 0 is a mirror. */\nuniform float uPrefilterRoughness;\n/** Samples per texel, from PREFILTER_SAMPLE_COUNTS. A power of two; see the count's own note. */\nuniform float uPrefilterSamples;\n/** The source cube's face width in texels, for the solid-angle comparison below. */\nuniform float uPrefilterSourceTexels;\n/** The source chain's top level, so a wide sample cannot ask for a level that is not there. */\nuniform float uPrefilterSourceMaxLod;\n\nout vec4 fragColor;\n\nconst float PI = 3.14159265359;\n\n/**\n * The radical inverse of a 32-bit integer, base two: the second dimension of a Hammersley set.\n *\n * A bit reversal, written as the standard five-shift sequence rather than a loop, because a loop\n * over 32 bits per sample per texel is the one place in a bake where the arithmetic is the cost.\n * **This is why every sample count is a power of two** \u2014 the sequence's stratification is only\n * even when the count is, and an uneven one shows as a faint directional bias in a rough level\n * rather than as an error anybody would notice.\n */\nfloat radicalInverse(uint bits) {\n  bits = (bits << 16u) | (bits >> 16u);\n  bits = ((bits & 0x55555555u) << 1u) | ((bits & 0xAAAAAAAAu) >> 1u);\n  bits = ((bits & 0x33333333u) << 2u) | ((bits & 0xCCCCCCCCu) >> 2u);\n  bits = ((bits & 0x0F0F0F0Fu) << 4u) | ((bits & 0xF0F0F0F0u) >> 4u);\n  bits = ((bits & 0x00FF00FFu) << 8u) | ((bits & 0xFF00FF00u) >> 8u);\n  return float(bits) * 2.3283064365386963e-10;\n}\n\n/**\n * A half vector drawn from the GGX distribution about the normal, for one Hammersley pair.\n *\n * Importance sampling rather than a uniform hemisphere: at low roughness the lobe occupies a\n * vanishing fraction of the hemisphere, so uniform samples would put almost every one of them\n * where the weight is zero and the few that land in the lobe would carry all the variance.\n */\nvec3 importanceSampleGgx(vec2 xi, vec3 n, float roughness) {\n  float a = roughness * roughness;\n\n  float phi = 2.0 * PI * xi.x;\n  float cosTheta = sqrt((1.0 - xi.y) / (1.0 + (a * a - 1.0) * xi.y));\n  float sinTheta = sqrt(1.0 - cosTheta * cosTheta);\n\n  vec3 h = vec3(sinTheta * cos(phi), sinTheta * sin(phi), cosTheta);\n\n  /*\n   * Any tangent will do as long as it is not parallel to the normal, and the choice of which\n   * axis to cross against has to depend on the normal or it degenerates at the poles \u2014 which is\n   * one face of six coming out as noise, on the two faces the axis points at.\n   */\n  vec3 up = abs(n.z) < 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(1.0, 0.0, 0.0);\n  vec3 tangentX = normalize(cross(up, n));\n  vec3 tangentY = cross(n, tangentX);\n\n  return normalize(tangentX * h.x + tangentY * h.y + n * h.z);\n}\n\n/**\n * A direction drawn from the cosine lobe about the normal, for the diffuse level.\n *\n * **Cosine-weighted, which is what makes the estimator a plain mean.** Irradiance is\n * integral of L cos(theta), the cosine pdf is cos(theta) / pi, so the estimate is\n * pi / N * sum(L) \u2014 and what the lit pass wants is radiance rather than irradiance, so the pi\n * divides straight back out. irradianceSh.ts folds the same division into its band factors and\n * says so, which is what makes a grid of one reproduce what the projection produced.\n */\nvec3 importanceSampleCosine(vec2 xi, vec3 n) {\n  float phi = 2.0 * PI * xi.x;\n  float cosTheta = sqrt(max(1.0 - xi.y, 0.0));\n  float sinTheta = sqrt(xi.y);\n\n  vec3 h = vec3(sinTheta * cos(phi), sinTheta * sin(phi), cosTheta);\n\n  vec3 up = abs(n.z) < 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(1.0, 0.0, 0.0);\n  vec3 tangentX = normalize(cross(up, n));\n  vec3 tangentY = cross(n, tangentX);\n\n  return normalize(tangentX * h.x + tangentY * h.y + n * h.z);\n}\n\n/** Trowbridge-Reitz, in its own normalisation, because this is a probability rather than a look. */\nfloat ggxDistribution(float ndh, float roughness) {\n  float a = roughness * roughness;\n  float a2 = a * a;\n  float d = ndh * ndh * (a2 - 1.0) + 1.0;\n  return a2 / max(PI * d * d, 1e-8);\n}\n\nvoid main() {\n  vec3 n = octInsetDir(vUv, uPrefilterEdge);\n\n  float texelSolidAngle = 4.0 * PI / (6.0 * uPrefilterSourceTexels * uPrefilterSourceTexels);\n\n  /*\n   * The box chain, which is one fetch: the source's own level at the same index, resampled through\n   * the octahedral mapping. It is what a profile that has not asked for the lobe chain gets, and\n   * it is the picture every consumer with a probe already had.\n   */\n  if (uPrefilterBox > 0.5 && uPrefilterIrradiance <= 0.5) {\n    fragColor = vec4(\n      textureLod(uPrefilterSource, n, min(uPrefilterLevel, uPrefilterSourceMaxLod)).rgb,\n      1.0\n    );\n    return;\n  }\n\n  /*\n   * **The diffuse level, and it is a mean rather than a weighted sum.** Every cosine sample is\n   * drawn with the weight already in its density, so there is nothing to accumulate a weight for\n   * and nothing to divide by but the count. A sample below the horizon cannot occur, which is the\n   * other half of why this arm has no continue in it.\n   */\n  if (uPrefilterIrradiance > 0.5) {\n    vec3 diffuse = vec3(0.0);\n    int cosineSamples = int(uPrefilterSamples);\n    for (int i = 0; i < cosineSamples; i++) {\n      vec2 xi = vec2(float(i) / uPrefilterSamples, radicalInverse(uint(i)));\n      vec3 l = importanceSampleCosine(xi, n);\n      /*\n       * The same filtered importance sampling the reflection uses, against the cosine density.\n       * A diffuse sample is wide \u2014 a sixth of the sphere at the median \u2014 so reading the base level\n       * would carry a bright window through as a handful of fireflies in the ambient, which is the\n       * one place they cannot be blurred out later.\n       */\n      float pdf = max(dot(n, l) / PI, 1e-4);\n      float sampleSolidAngle = 1.0 / (uPrefilterSamples * pdf);\n      float lod = clamp(\n        0.5 * log2(sampleSolidAngle / texelSolidAngle),\n        0.0,\n        uPrefilterSourceMaxLod\n      );\n      diffuse += textureLod(uPrefilterSource, l, lod).rgb;\n    }\n    fragColor = vec4(diffuse / max(uPrefilterSamples, 1.0), 1.0);\n    return;\n  }\n\n  /*\n   * A mirror is a fetch rather than an integral, and it is a separate arm on purpose: at\n   * roughness 0 the distribution is a delta, every importance sample collapses onto the same\n   * direction, and the sum is one sample's worth of noise where the answer is exactly the texel.\n   */\n  if (uPrefilterRoughness <= 0.0) {\n    fragColor = vec4(textureLod(uPrefilterSource, n, 0.0).rgb, 1.0);\n    return;\n  }\n\n  vec3 sum = vec3(0.0);\n  float weight = 0.0;\n\n  int samples = int(uPrefilterSamples);\n  for (int i = 0; i < samples; i++) {\n    vec2 xi = vec2(float(i) / uPrefilterSamples, radicalInverse(uint(i)));\n    vec3 h = importanceSampleGgx(xi, n, uPrefilterRoughness);\n    vec3 l = normalize(2.0 * dot(n, h) * h - n);\n\n    float ndl = dot(n, l);\n    if (ndl <= 0.0) continue;\n\n    /*\n     * Filtered importance sampling. A sample covers 1 / (count * pdf) of the sphere; when that\n     * is much wider than a texel, reading the base level lets a few very bright texels land in\n     * some samples and not others, and the variance survives the average as fireflies. The half\n     * in front of the logarithm is a length ratio against an area one \u2014 a level step doubles a\n     * texel's width and quadruples its solid angle. sourceLevelForSample holds the same\n     * arithmetic on the CPU and its test carries the hand-derived numbers.\n     */\n    float ndh = max(dot(n, h), 0.0);\n    float pdf = max(ggxDistribution(ndh, uPrefilterRoughness) * 0.25, 1e-8);\n    float sampleSolidAngle = 1.0 / (uPrefilterSamples * pdf);\n    float lod = clamp(\n      0.5 * log2(sampleSolidAngle / texelSolidAngle),\n      0.0,\n      uPrefilterSourceMaxLod\n    );\n\n    /*\n     * textureLod rather than texture, and the 2026-08-07 rule is why: this fetch sits inside a\n     * loop with a continue in it, which no compiler can prove uniform, and an implicit derivative\n     * in non-uniform control flow is what lets a driver flatten the loop and cost every arm.\n     * The level is wanted here anyway, so the rule costs nothing at all.\n     */\n    sum += textureLod(uPrefilterSource, l, lod).rgb * ndl;\n    weight += ndl;\n  }\n\n  /*\n   * Normalised by the accumulated weight rather than by the sample count, because samples with\n   * a light below the horizon were skipped and dividing by the count would darken every rough\n   * level by the fraction that missed \u2014 which reads as roughness losing energy and is exactly\n   * the artefact uEnvironmentGain has been compensating for.\n   */\n  fragColor = vec4(sum / max(weight, 1e-4), 1.0);\n}\n";