@driftengine/core 3.61.0

package/dist/render/shaders/particle.js

@@ -0,0 +1,431 @@
+import { FOG_GLSL } from './fog.js';
+import { OUTPUT_TRANSFORM_GLSL } from './outputTransform.js';
+import { MAX_POINT_LIGHTS } from '../lightBudget.js';
+/**
+ * Particle materials: soft smoke, hot sparks, and unlit motes.
+ *
+ * One vertex program, three fragment programs, and the split is the same one the
+ * plumes already make — `PLUME_VERT` places a volume and the fragment decides
+ * whether it is fire or smoke. Here the vertex program places a particle as a
+ * **camera-facing quad**, or as a world-fixed cross of two when a caller asks, and
+ * the fragment decides whether it is a puff of grit, an ember, or an unlit point.
+ *
+ * **The cross was the only option and then the default, and is now neither.** The
+ * argument for it is the one `plumeRenderer` records at length, and it is a real
+ * one: a billboard has no parallax, so orbiting a plume shows the identical
+ * silhouette from every angle and the whole effect swivels as a sheet, where two
+ * fixed blades genuinely bring one broadside as the other goes edge-on. What that
+ * argument leaves out is what the going-edge-on blade *draws*. It does not fade as
+ * it turns; it compresses, and a sprite compressed into a one-pixel column spends
+ * its entire brightness in that column. On smoke it hides inside the noise. On an
+ * additive spark it is a bright straight line through the middle of every particle,
+ * which is how it was finally caught. `uCameraFacing` carries the full account and
+ * the terms of the trade for anyone who wants the blades back.
+ *
+ * **These replace drawing particles through the foliage shader**, which is what
+ * every effect built on `ParticlePool` used to do. Grass is opaque, lit
+ * two-sided, and has no opacity channel — so a grain of smoke was a solid cube
+ * lit like a leaf, and its "fade" was its colour being driven to black — which reads
+ * as squared-off smoke that never had a shader of its own, against fire that did.
+ * This is that missing quality: a soft body eroded by
+ * the same value noise, an honest alpha, and real lighting.
+ */
+/**
+ * Blades in the cross, and the vertices and indices that costs.
+ *
+ * Still two under `facing: 'camera'`, where the second is collapsed to zero area in the
+ * vertex stage rather than dropped here — so one pair of buffers serves both facings and a
+ * batch chooses per pool. See `uCameraFacing`.
+ */
+export const PARTICLE_BLADES = 2;
+export const PARTICLE_VERTS = PARTICLE_BLADES * 4;
+export const PARTICLE_INDICES = PARTICLE_BLADES * 6;
+/**
+ * Shared noise. Value noise, two octaves, exactly the construction `SMOKE_FRAG`
+ * uses — a particle and a plume standing in the same scene must not be eroded by
+ * different mathematics, or the small effect reads as a different material from
+ * the large one it is supposed to be a wisp of.
+ */
+const PARTICLE_NOISE = `
+float hash21(vec2 p) {
+  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);
+}
+
+float valueNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  return mix(
+    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),
+    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x),
+    u.y
+  );
+}
+
+float billow(vec2 p, float t, int octaves) {
+  float v = valueNoise(p * 2.4 + vec2(0.0, -t * 0.5)) * 0.62;
+  if (octaves == 1) return v / 0.62;
+  v += valueNoise(p * 5.1 + vec2(t * 0.15, -t * 0.8)) * 0.38;
+  return v / 1.0;
+}
+`;
+export const PARTICLE_VERT = `#version 300 es
+/** Per-vertex: the quad corner, and which blade of the cross it belongs to. */
+layout(location = 0) in vec2 aCorner;
+layout(location = 1) in float aBlade;
+/** Per-instance. */
+layout(location = 2) in vec3 aPos;
+layout(location = 3) in float aSize;
+layout(location = 4) in float aSpin;
+layout(location = 5) in vec3 aColor;
+/** Opacity, age as a share of life, and this particle's own seed. */
+layout(location = 6) in float aAlpha;
+layout(location = 7) in float aAge;
+layout(location = 8) in float aSeed;
+layout(location = 9) in vec3 aVelocity;
+
+uniform mat4 uViewProj;
+uniform vec3 uCameraPos;
+/**
+ * How far a particle is stretched along its own motion, in seconds of travel.
+ *
+ * Zero for smoke, which has no direction worth seeing. A spark is the opposite
+ * case: an ember crossing a metre in a frame drawn as a round dot reads as a
+ * floating pixel, and the same ember drawn as a short streak along its velocity
+ * reads as a thrown spark. The eye gets its motion cue from the shape.
+ */
+uniform float uStretchSec;
+/**
+ * 1 to turn a single quad to face the camera, 0 to draw the world-fixed cross.
+ *
+ * **Camera-facing is the default, and the cross is the option.** It was the other way
+ * round until a caller drew an additive glow with a camera looking down -Z and got a
+ * bright straight line through the middle of every sprite. The cross is two blades at
+ * right angles in *world* space: blade 0 spans X, blade 1 spans Z. Look down either
+ * axis and that blade is edge-on, and a disc squeezed into a one-pixel column does not
+ * lose the energy it was drawn with — it puts all of it in that column. Alpha-blended
+ * smoke half hides it behind its own noise. Additive has nothing to hide it with.
+ *
+ * Fading a blade out as it turns edge-on fixes that one case and not the matching one:
+ * both blades contain world Y, so a camera looking straight down sees *both* edge-on
+ * and the puff is a plus sign of two lines, or nothing at all once they are faded. A
+ * camera-facing quad has no angle at which it thins, which is why it is what particle
+ * systems generally draw.
+ *
+ * The cross is still worth keeping. Two blades give real parallax when a camera moves
+ * through a puff, and that is a volume cue a single quad cannot fake — worth having in
+ * a ground-level world whose camera never looks far off the horizontal, where the
+ * edge-on blade stays a thin sliver inside soft smoke rather than a line across a
+ * spark. It also costs a brightness that swings with the view: a cross covers one
+ * sprite of area seen down an axis and about 1.4 seen from the diagonal, so a puff
+ * quietly pulses as the camera orbits it. A camera-facing quad covers the same area
+ * from everywhere.
+ */
+uniform float uCameraFacing;
+
+out vec2 vUv;
+out vec3 vColor;
+out float vAlpha;
+out float vAge;
+out float vSeed;
+out vec3 vWorldPos;
+out vec3 vNormal;
+
+void main() {
+  float s = sin(aSpin);
+  float c = cos(aSpin);
+  // Roll within the blade's own plane, so the two blades never look like one
+  // rigid object turning.
+  vec2 rolled = vec2(aCorner.x * c - aCorner.y * s, aCorner.x * s + aCorner.y * c);
+
+  /*
+   * The plane the corners are laid out in, built from the particle's centre rather than
+   * from the corner being transformed, so all four corners of a quad share one basis and
+   * the quad stays planar and rectangular.
+   */
+  vec3 across;
+  vec3 up;
+  float bladeGain;
+  if (uCameraFacing > 0.5) {
+    vec3 toCamera = normalize(uCameraPos - aPos);
+    /* Any reference not parallel to the view. World up serves everywhere except looking
+       straight up or down it, where the two are the same line and the cross product
+       vanishes; +Z takes over there. */
+    vec3 reference = abs(toCamera.y) > 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(0.0, 1.0, 0.0);
+    across = normalize(cross(reference, toCamera));
+    up = cross(toCamera, across);
+    /*
+     * One quad, not two. Both blades face the camera here, so they would land on exactly
+     * the same pixels and the second would be nothing but the first drawn again: double
+     * the fill for double the brightness no caller asked for. Collapsing it to zero area
+     * costs nothing — the rasteriser drops a degenerate triangle before it shades — and
+     * leaves the vertex and index buffers the shape both backends already build, so a
+     * batch picks its facing without either one rebuilding its geometry.
+     */
+    bladeGain = aBlade < 0.5 ? 1.0 : 0.0;
+  } else {
+    across = aBlade < 0.5 ? vec3(1.0, 0.0, 0.0) : vec3(0.0, 0.0, 1.0);
+    up = vec3(0.0, 1.0, 0.0);
+    bladeGain = 1.0;
+  }
+  vec3 offset = (across * rolled.x + up * rolled.y) * aSize;
+
+  /*
+   * Stretched along travel. Applied as an extra displacement on the component of
+   * the corner that already points along the motion, so a stationary particle is
+   * untouched and a fast one lengthens without also getting fatter.
+   */
+  if (uStretchSec > 0.0) {
+    vec3 travel = aVelocity * uStretchSec;
+    float along = dot(normalize(offset + vec3(1e-6)), normalize(travel + vec3(1e-6)));
+    offset += travel * along * 0.5;
+  }
+
+  /* bladeGain applied here, after the stretch rather than before it, so a dropped blade
+     is degenerate whatever the stretch added: all four of its corners land on aPos. */
+  vec3 world = aPos + offset * bladeGain;
+  vUv = aCorner;
+  vColor = aColor;
+  vAlpha = aAlpha;
+  vAge = aAge;
+  vSeed = aSeed;
+  vWorldPos = world;
+  /*
+   * The blade's own facing, flipped toward the viewer. A cross has no meaningful
+   * outward normal, and a puff of smoke is not a surface — but it does have to be
+   * *lit*, and a normal facing the camera is the standard, honest cheat for a
+   * volume approximated by cards: it makes the puff read as a lump catching light
+   * from wherever the light is, rather than as a flat panel that goes black at
+   * some angles.
+   */
+  vec3 face = cross(across, up);
+  vec3 toEye = normalize(uCameraPos - world);
+  vNormal = dot(face, toEye) < 0.0 ? -face : face;
+
+  gl_Position = uViewProj * vec4(world, 1.0);
+}
+`;
+/**
+ * Smoke, grit and dust: a soft body eroded by noise, alpha blended, and lit.
+ *
+ * Lit by the sun, the ambient *and* the nearby point lights, which is the half
+ * the foliage path could never do. A drift at night beside a brazier threw grey
+ * grit whatever the brazier was doing, because grass has no point-light term —
+ * and unlit smoke in a world lit by fires is the tell that gives an effect away
+ * fastest. A puff catching a flame's colour is most of what makes it belong.
+ */
+export const PARTICLE_SMOKE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+in vec3 vColor;
+in float vAlpha;
+in float vAge;
+in float vSeed;
+in vec3 vWorldPos;
+in vec3 vNormal;
+
+uniform float uTime;
+uniform vec3 uDirectionalDir;
+uniform vec3 uDirectionalColor;
+uniform vec3 uAmbient;
+uniform vec3 uCameraPos;
+uniform int uNoiseOctaves;
+/** How strongly the noise eats into the puff. 0 is a plain soft ball. */
+uniform float uErosion;
+
+#define MAX_LIGHTS ${MAX_POINT_LIGHTS}
+uniform int uLightCount;
+uniform vec3 uLightPos[MAX_LIGHTS];
+uniform vec3 uLightColor[MAX_LIGHTS];
+uniform float uLightRadius[MAX_LIGHTS];
+// How present each light is, 0 to 1. See pointLightSelection.ts.
+uniform float uLightWeight[MAX_LIGHTS];
+
+${FOG_GLSL}
+${PARTICLE_NOISE}
+
+out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
+
+void main() {
+  /*
+   * A round, soft body first. 'smoothstep' rather than a hard disc: the edge is
+   * the entire difference between a puff and a sprite, and a cut-off circle reads
+   * as a decal however good the noise inside it is.
+   */
+  float r = length(vUv);
+  float body = 1.0 - smoothstep(0.35, 1.0, r);
+  if (body <= 0.0) discard;
+
+  /*
+   * Then eaten into by noise that drifts and coarsens as the puff ages, so it
+   * dissipates by *breaking up* rather than by uniformly thinning. Uniform
+   * thinning is what a fading sprite does, and it is what the old cube did.
+   */
+  float t = uTime * 0.55 + vSeed * 7.31;
+  float n = billow(vUv * (0.9 + vAge * 1.4) + vec2(vSeed * 3.7, 0.0), t, uNoiseOctaves);
+  float erode = mix(1.0, n, uErosion * (0.35 + vAge * 0.65));
+  float mask = clamp(body * erode, 0.0, 1.0);
+  // Feather the last of it out rather than letting a noise threshold flicker.
+  mask *= smoothstep(0.0, 0.25, mask);
+  if (mask <= 0.002) discard;
+
+  vec3 n3 = normalize(vNormal);
+  /*
+   * Wrapped diffuse. Smoke transmits as well as reflects, so the terminator on a
+   * puff sits well past 90° — a hard 'max(dot, 0)' gives a lump with a black side,
+   * which is exactly the "coloured box" failure the fidelity rules name.
+   */
+  float ndl = dot(n3, uDirectionalDir) * 0.5 + 0.5;
+  vec3 lit = uAmbient + uDirectionalColor * ndl;
+
+  for (int i = 0; i < MAX_LIGHTS; i++) {
+    if (i >= uLightCount) break;
+    vec3 toLight = uLightPos[i] - vWorldPos;
+    float dist = length(toLight);
+    float radius = uLightRadius[i];
+    if (radius <= 0.0 || dist >= radius) continue;
+    float falloff = 1.0 - dist / radius;
+    float wrapped = dot(n3, toLight / max(dist, 1e-4)) * 0.5 + 0.5;
+    lit += uLightColor[i] * falloff * falloff * wrapped * uLightWeight[i];
+  }
+
+  vec3 shaded = vColor * lit;
+  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+  outColor = vec4(applyOutputTransform(mix(shaded, mediumColor(), fog)), mask * vAlpha);
+}
+`;
+/**
+ * Sparks and embers: additive, hot in the middle, and stretched along travel.
+ *
+ * No lighting at all, deliberately — a spark *is* a light source, and shading it
+ * is what turned the first version into a grey cube at night. The core is allowed
+ * past white so it reads as incandescent rather than as a pale dot.
+ */
+export const PARTICLE_SPARK_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+in vec3 vColor;
+in float vAlpha;
+in float vAge;
+in float vSeed;
+in vec3 vWorldPos;
+in vec3 vNormal;
+
+uniform float uTime;
+uniform vec3 uCameraPos;
+/** How far past white the centre may go. */
+uniform float uCoreGain;
+${FOG_GLSL}
+${PARTICLE_NOISE}
+
+out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
+
+void main() {
+  float r = length(vUv);
+  if (r > 1.0) discard;
+
+  /*
+   * Two falloffs again — a tight core and a broad halo — because one gives either
+   * a hard dot or a soft smudge. The halo is what makes a shower of embers read
+   * as glowing air rather than as a scatter of points.
+   */
+  float core = pow(1.0 - clamp(r, 0.0, 1.0), 6.0);
+  float halo = pow(1.0 - clamp(r, 0.0, 1.0), 1.6);
+
+  /*
+   * Embers flicker as they tumble and cool. Per-particle phase from the seed, so
+   * a shower crackles instead of pulsing as one body.
+   */
+  float flick = 0.7 + 0.3 * valueNoise(vec2(uTime * 9.0 + vSeed * 13.0, vSeed));
+
+  // Cooling: the last of a spark's life is dimmer as well as smaller.
+  float cool = 1.0 - vAge * vAge;
+  float energy = (halo * 0.55 + core * uCoreGain) * flick * cool * vAlpha;
+
+  float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+  energy *= 1.0 - fog;
+  /*
+   * Alpha 1, energy in the colour — see the note in 'bolt.ts'. Additive blending is
+   * 'rgb * a', so carrying the energy in both channels squares it and quietly halves
+   * every emissive effect in the game.
+   */
+  outColor = vec4(applyOutputTransform(vColor * energy), 1.0);
+}
+`;
+/**
+ * Dust motes and drifting glints: unlit, alpha blended, and fogged only when the caller asks.
+ *
+ * **What neither existing material could draw.** `'spark'` is unlit but additive — its
+ * fragment stage folds its whole brightness into colour and always writes alpha 1, because
+ * additive blending is `rgb * a` and a real alpha there would double the energy (the note at
+ * the end of `PARTICLE_SPARK_FRAG` explains why). `'smoke'` has a real, varying alpha, but pays
+ * for it with lighting it can never turn off. A point that is unlit *and* genuinely
+ * translucent — what three.js's `PointsMaterial` draws, and what drei's `Sparkles` is built on
+ * — was not expressible by either.
+ *
+ * No noise, no core-and-halo split: a mote is not a body being eroded and it is not
+ * incandescent, so borrowing either shape would draw the wrong material behind the right blend
+ * state. This is the plainest fragment stage in the file on purpose — a soft round point whose
+ * colour is nothing but its own vColor and whose opacity is nothing but its own vAlpha.
+ *
+ * **Fog is the one thing this material still asks the caller about.** A mote is the one
+ * particle a scene legitimately wants both ways: dust caught in a shaft of light recedes into
+ * haze exactly like anything else out there, but a field of them meant to read as flat, close
+ * atmosphere — the look this exists for — must not. `'spark'` and `'smoke'` take no such
+ * option and stay unconditionally fogged, matching every particle drawn before this material
+ * existed; see `ParticleBatchOptions.fog`.
+ */
+export const PARTICLE_MOTE_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+in vec3 vColor;
+in float vAlpha;
+in float vAge;
+in float vSeed;
+in vec3 vWorldPos;
+in vec3 vNormal;
+
+uniform vec3 uCameraPos;
+/**
+ * Whether the fragment stage mixes toward the medium's own colour at all. 0 — what a batch
+ * gets by leaving ParticleBatchOptions.fog unset — leaves vColor untouched by distance, which
+ * is what a caller reaching for this material over 'spark'/'smoke' is usually asking for: an
+ * unlit point drawn exactly as its own colour says. 1 mixes toward mediumColor() by
+ * mediumFog(), the same medium every other pass in the frame recedes into.
+ */
+uniform int uFogEnabled;
+${FOG_GLSL}
+
+out vec4 outColor;
+${OUTPUT_TRANSFORM_GLSL}
+
+void main() {
+  /*
+   * One soft, round falloff — no erosion, no core past white, because this material draws
+   * neither a body being eaten by noise nor a light source. Squared rather than linear so the
+   * edge feathers instead of ramping, which is what keeps a field of these reading as dust
+   * rather than as a scatter of hard-edged discs.
+   */
+  float r = length(vUv);
+  float body = 1.0 - smoothstep(0.4, 1.0, r);
+  if (body <= 0.0) discard;
+  float alpha = body * body * vAlpha;
+  if (alpha <= 0.002) discard;
+
+  vec3 color = vColor;
+  if (uFogEnabled != 0) {
+    float fog = mediumFog(distance(vWorldPos, uCameraPos), vWorldPos.y);
+    color = mix(color, mediumColor(), fog);
+  }
+  /*
+   * A real alpha blend (SRC_ALPHA, ONE_MINUS_SRC_ALPHA) rather than spark's energy-in-colour
+   * trick: this point genuinely occludes what little is behind it instead of adding light to it.
+   */
+  outColor = vec4(applyOutputTransform(color), alpha);
+}
+`;

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

@@ -0,0 +1,37 @@
+/** The convolutions that fill one level of one probe layer, reflection and ambient alike. */
+/**
+ * One level of one probe layer, convolved with the lobe that level stands for.
+ *
+ * **Directions, not texture coordinates**, for the same reason the mip blit it replaces used
+ * them: the neighbouring texels across a cube edge belong to a different face, and taking them
+ * from the same face is exactly how a seam appears along every edge. The fragment rebuilds the
+ * direction its texel stands for and samples the cube, which crosses edges the way the hardware
+ * does when the shader reads it back later.
+ *
+ * **The target is one octahedral layer rather than six cube faces**, so a level is one draw
+ * instead of six and there is no face basis at all — `octInsetDir` turns a texel into the
+ * direction it holds, and in the level's one-texel gutter that direction is the folded one. The
+ * source stays a cube, which is what `sourceLevelForSample`'s six-face solid angle assumes.
+ *
+ * **Two kernels, one pass.** Levels up to the GGX chain's top convolve against the lobe; the level
+ * above it convolves against the cosine and is the scene's diffuse ambient. They differ in the
+ * weight and in nothing else, so `uPrefilterIrradiance` chooses between them and the whole rest of
+ * the shader is shared. That fold is what lets one binding carry both terms and keeps the last
+ * texture unit free.
+ *
+ * **It samples a cube and writes an array, which are different objects by construction.**
+ * `uPrefilterSource` is the captured probe with its box-filtered chain, and it is one scratch cube
+ * reused by every probe in the grid rather than one per layer. That buys two things: WebGL2's
+ * feedback-loop check is per texture object, so a draw sampling the source while a layer of the
+ * target is attached never arises; and a level is never convolved from a level that was already
+ * convolved, which applies the lobe twice and compounds up the chain.
+ *
+ * **The approximation, stated because it is the one people are surprised by.** This is the split
+ * of the specular integral everybody uses: the view direction is assumed equal to the normal and
+ * to the reflection direction, so a level cannot know about stretched grazing highlights and a
+ * rough metal seen edge-on reflects a slightly rounder lobe than it should. That is what buys a
+ * bake that depends on roughness alone rather than on roughness and view angle, which is the
+ * 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";