@driftengine/core 4.8.6 → 4.9.0

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

@@ -9,4 +9,4 @@
  */
 /** Shared billboard vertex stage: used by fire, smoke and any future plume. */
 export declare const PLUME_VERT = "#version 300 es\nlayout(location = 0) in vec3 aCenter;\nlayout(location = 1) in vec2 aCorner;\nlayout(location = 2) in vec2 aSize;\nlayout(location = 3) in float aSeed;\nlayout(location = 4) in float aBlade;\n\nuniform mat4 uViewProj;\nuniform vec3 uCameraPos;\nuniform float uTime;\n/** Amplitude of the size pulse; 0 keeps the quad a fixed size. */\nuniform float uSizePulse;\n/**\n * Horizontal wind, m/s. Plumes lean with it, increasingly toward their top \u2014\n * the base is anchored to whatever is burning, the crown is free. Sharing one\n * wind with the rest of the world is the point: smoke drifting one way while\n * foliage leans another is the clearest tell that a scene is a pile of effects\n * rather than a place.\n */\nuniform vec2 uWind;\n/**\n * Whole-batch offset. Plume centres live in a static buffer because braziers\n * never move; a batch that *does* move \u2014 a tornado \u2014 shifts by a uniform rather\n * than rewriting geometry every frame.\n */\nuniform vec3 uOrigin;\n/** How strongly this plume type answers the wind; smoke far more than flame. */\nuniform float uWindResponse;\n\nout vec2 vUv;\nout float vSeed;\nout float vDistance;\nout vec3 vWorldPos;\n\n/**\n * Plumes are not a constant size: a fire flares and dies back, a smoke column\n * swells and thins. Two out-of-phase sines, offset per plume, so the whole\n * effect breathes rather than only its interior pattern animating.\n */\nfloat sizePulse(float seed) {\n  return 1.0 + uSizePulse * (\n    sin(uTime * 1.7 + seed * 9.1) * 0.62 +\n    sin(uTime * 3.3 + seed * 4.7) * 0.38\n  );\n}\n\nvoid main() {\n  // Height swells more than width, the way a real flame stretches upward.\n  vec3 anchor = aCenter + uOrigin;\n\n  /*\n   * No billboarding at all: the blade's heading is fixed in the world.\n   *\n   * Each plume is drawn as a CROSS of two blades 90 degrees apart (see BLADES in\n   * plumeRenderer), and aSeed advances by the golden ratio per plume, so the crosses\n   * themselves are scattered by the golden angle rather than aligned into a grid.\n   *\n   * Nothing here reads the camera, and that is the fix. Anything that does - a full\n   * billboard, or merely leaning edge-on cards toward the viewer - rotates geometry\n   * as the camera moves, which is exactly what reads as flat: orbiting a fire showed\n   * the same silhouette from every angle. A cross cannot track the viewer, so turning\n   * around a fire genuinely brings one blade broadside while the other goes edge-on.\n   * That is the parallax a volume has, and it is also why no blade needs to be turned\n   * to stay visible - its partner is square-on whenever it is not.\n   *\n   * World up stays the vertical axis: a flame that tilts with the camera reads as a\n   * decal.\n   */\n  vec3 up = vec3(0.0, 1.0, 0.0);\n  float yaw = aSeed * 6.28318530718 + aBlade * 1.57079632679;\n  vec3 right = vec3(cos(yaw), 0.0, sin(yaw));\n  float pulse = sizePulse(aSeed);\n  vec2 size = vec2(aSize.x * mix(1.0, pulse, 0.55), aSize.y * pulse);\n\n  float rise = aCorner.y * 0.5 + 0.5;\n  vec3 world = anchor\n    + right * (aCorner.x * size.x)\n    + up * (rise * size.y);\n\n  // Quadratic in height: a column bends away from its anchor rather than\n  // shearing uniformly, which would slide its base off the fire.\n  world.xz += uWind * (uWindResponse * rise * rise * size.y);\n\n  vUv = vec2(aCorner.x * 0.5 + 0.5, aCorner.y * 0.5 + 0.5);\n  vSeed = aSeed;\n  vDistance = distance(world, uCameraPos);\n  vWorldPos = world;\n  gl_Position = uViewProj * vec4(world, 1.0);\n}\n";
-export declare const FIRE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\nin float vSeed;\nin float vDistance;\nin vec3 vWorldPos;\n\nuniform float uTime;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(t) < 1e-4 ? 1e-4 : t;\n  float air = 1.0 - exp(-uFogDensity * dist * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\nuniform int uNoiseOctaves;\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\n\nout vec4 outColor;\n\nfloat hash21(vec2 p) {\n  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);\n}\n\nfloat valueNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),\n    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x),\n    u.y\n  );\n}\n\n/** Rising turbulence: octaves scrolled upward at different rates. */\nfloat turbulence(vec2 p, float t) {\n  float v = valueNoise(p * 3.0 + vec2(0.0, -t * 1.9)) * 0.55;\n  if (uNoiseOctaves == 1) return v / 0.55;\n  v += valueNoise(p * 6.5 + vec2(t * 0.3, -t * 3.1)) * 0.28;\n  if (uNoiseOctaves == 2) return v / 0.83;\n  return v + valueNoise(p * 13.0 + vec2(-t * 0.2, -t * 4.6)) * 0.17;\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;\n\n  vec2 uv = vUv;\n  float t = uTime + vSeed * 37.0;\n\n  // Taper toward the tip and pinch the sides, so the quad never shows.\n  float sides = 1.0 - abs(uv.x - 0.5) * 2.0;\n  float taper = sides * (1.0 - uv.y * 0.72);\n  if (taper <= 0.0) discard;\n\n  // Sway: the column leans and wanders instead of standing to attention.\n  float sway = (valueNoise(vec2(t * 0.55, vSeed * 11.0)) - 0.5) * 0.34 * uv.y;\n  vec2 p = vec2(uv.x + sway, uv.y);\n\n  float n = turbulence(p, t);\n  // Flame body: noise must beat a threshold that rises with height, which is\n  // what makes the tip break into separate licks.\n  float body = n * taper * 1.9 - uv.y * 0.55;\n  if (body <= 0.02) discard;\n\n  // Colour ramp: white-hot core through yellow and orange to a dark red edge.\n  float heat = clamp(body * 1.5, 0.0, 1.0);\n  vec3 col = mix(vec3(0.62, 0.06, 0.02), vec3(1.0, 0.45, 0.06), smoothstep(0.0, 0.45, heat));\n  col = mix(col, vec3(1.0, 0.85, 0.35), smoothstep(0.45, 0.75, heat));\n  col = mix(col, vec3(1.0, 0.98, 0.88), smoothstep(0.78, 1.0, heat));\n\n  float alpha = clamp(body * 2.2, 0.0, 1.0) * (1.0 - smoothstep(0.72, 1.0, uv.y));\n  // Additive light must lose alpha as it scatters, or mixing its colour alone\n  // still makes a distant flame glow through fog and through water.\n  float fog = mediumFog(vDistance, vWorldPos.y);\n  col = mix(col, mediumColor(), fog);\n  alpha *= 1.0 - fog;\n\n  outColor = vec4(col, alpha);\n}\n";
+export declare const FIRE_FRAG = "#version 300 es\nprecision highp float;\n\nin vec2 vUv;\nin float vSeed;\nin float vDistance;\nin vec3 vWorldPos;\n\nuniform float uTime;\n\nuniform vec3 uFogColor;\n/** Extinction per metre **at the camera's own height**, not at the base. */\nuniform float uFogDensity;\n/** Reciprocal scale height of the haze, per metre. 0 is a uniform medium. */\nuniform float uFogHeightFalloff;\n/** The camera's height, so a fragment's own height is one subtraction away. */\nuniform float uFogEyeY;\nuniform vec3 uUnderwaterColor;\nuniform float uUnderwaterFogDensity;\nuniform float uUnderwaterFactor;\n/** 0 integrates a medium (Beer-Lambert); 1 ramps linearly between near and far. */\nuniform int uFogMode;\n/** Linear mode only: where haze begins, and where it is total. */\nuniform float uFogNear;\nuniform float uFogFar;\n\n/** What distance converges toward: the day's haze, or the water column. */\nvec3 mediumColor() {\n  return mix(uFogColor, uUnderwaterColor, uUnderwaterFactor);\n}\n\n/**\n * How much of a surface standing at height pointY, dist metres away, is lost to\n * the medium in between. 0 is perfectly clear, 1 is the medium's own colour.\n */\nfloat mediumFog(float dist, float pointY) {\n  /*\n   * A depth ramp rather than a medium, for worlds authored against one.\n   *\n   * Beer-Lambert is the honest model and stays the default: it integrates something\n   * physically there, so extinction begins at the eye and never stops. A linear near/far\n   * fog is not that \u2014 it is a *look*, with a hard start distance before which the air is\n   * perfectly clear, and it is what the fixed-function pipeline offered and what several\n   * renderers still expose. Approximating one with the other is not a matter of tuning:\n   * matched at half occlusion, the exponential curve still lays haze over everything\n   * inside near, where the ramp lays none, and near-field colour desaturates toward the\n   * fog colour with nothing to show for it.\n   *\n   * Height falloff has no meaning here and is ignored: a ramp is defined on distance\n   * alone.\n   */\n  if (uFogMode == 1) {\n    float span = max(uFogFar - uFogNear, 1e-4);\n    float ramp = clamp((dist - uFogNear) / span, 0.0, 1.0);\n    if (uUnderwaterFactor <= 0.0) return ramp;\n    float wetLinear = uUnderwaterFogDensity * dist;\n    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), uUnderwaterFactor);\n  }\n\n  // Where the medium begins along the ray: uFogNear, the linear mode's slot, which this mode\n  // never read before Atmosphere.fogStart. The ray is integrated from there on, at the density\n  // of that point; at a start of 0 every term is the one it always was. See render/fog.ts.\n  float start = min(uFogNear, dist);\n  float before = dist > 0.0 ? start / dist : 0.0;\n  float t = (pointY - uFogEyeY) * uFogHeightFalloff;\n  float rest = t * (1.0 - before);\n  // (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than\n  // branched: at t = 0 the quotient is 0/0, and 1e-4 of a scale height is 8 mm.\n  float denom = abs(rest) < 1e-4 ? 1e-4 : rest;\n  float air =\n    1.0 - exp(-uFogDensity * exp(-t * before) * (dist - start) * (1.0 - exp(-denom)) / denom);\n  if (uUnderwaterFactor <= 0.0) return air;\n  // Water is its own medium and keeps its own curve, so crossing the surface\n  // changes nothing about how the water column reads.\n  float wet = uUnderwaterFogDensity * dist;\n  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), uUnderwaterFactor);\n}\n\nuniform int uNoiseOctaves;\nuniform vec4 uClipPlane;\nuniform int uClipEnabled;\n\nout vec4 outColor;\n\nfloat hash21(vec2 p) {\n  return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123);\n}\n\nfloat valueNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  return mix(\n    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),\n    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x),\n    u.y\n  );\n}\n\n/** Rising turbulence: octaves scrolled upward at different rates. */\nfloat turbulence(vec2 p, float t) {\n  float v = valueNoise(p * 3.0 + vec2(0.0, -t * 1.9)) * 0.55;\n  if (uNoiseOctaves == 1) return v / 0.55;\n  v += valueNoise(p * 6.5 + vec2(t * 0.3, -t * 3.1)) * 0.28;\n  if (uNoiseOctaves == 2) return v / 0.83;\n  return v + valueNoise(p * 13.0 + vec2(-t * 0.2, -t * 4.6)) * 0.17;\n}\n\nvoid main() {\n  if (uClipEnabled != 0 && dot(vec4(vWorldPos, 1.0), uClipPlane) < 0.0) discard;\n\n  vec2 uv = vUv;\n  float t = uTime + vSeed * 37.0;\n\n  // Taper toward the tip and pinch the sides, so the quad never shows.\n  float sides = 1.0 - abs(uv.x - 0.5) * 2.0;\n  float taper = sides * (1.0 - uv.y * 0.72);\n  if (taper <= 0.0) discard;\n\n  // Sway: the column leans and wanders instead of standing to attention.\n  float sway = (valueNoise(vec2(t * 0.55, vSeed * 11.0)) - 0.5) * 0.34 * uv.y;\n  vec2 p = vec2(uv.x + sway, uv.y);\n\n  float n = turbulence(p, t);\n  // Flame body: noise must beat a threshold that rises with height, which is\n  // what makes the tip break into separate licks.\n  float body = n * taper * 1.9 - uv.y * 0.55;\n  if (body <= 0.02) discard;\n\n  // Colour ramp: white-hot core through yellow and orange to a dark red edge.\n  float heat = clamp(body * 1.5, 0.0, 1.0);\n  vec3 col = mix(vec3(0.62, 0.06, 0.02), vec3(1.0, 0.45, 0.06), smoothstep(0.0, 0.45, heat));\n  col = mix(col, vec3(1.0, 0.85, 0.35), smoothstep(0.45, 0.75, heat));\n  col = mix(col, vec3(1.0, 0.98, 0.88), smoothstep(0.78, 1.0, heat));\n\n  float alpha = clamp(body * 2.2, 0.0, 1.0) * (1.0 - smoothstep(0.72, 1.0, uv.y));\n  // Additive light must lose alpha as it scatters, or mixing its colour alone\n  // still makes a distant flame glow through fog and through water.\n  float fog = mediumFog(vDistance, vWorldPos.y);\n  col = mix(col, mediumColor(), fog);\n  alpha *= 1.0 - fog;\n\n  outColor = vec4(col, alpha);\n}\n";

package/dist/render/shaders/flat/anisotropic.d.ts

@@ -12,4 +12,4 @@
  * Lamps widen both of the lobe's widths by the source's angle, as `sphereLobe` widens the standard
  * lobe, with the energy kept; at strength 0 that is `sphereLobe` exactly.
  */
-export declare const ANISOTROPIC_GLSL = "\n/* The stretch's frame and strength, gathered once with the surface. */\nvec3 aAlong;\nvec3 aAcross;\nfloat aStrength;\n\nvoid anisotropicSurface() {\n  vec2 direction = vec2(1.0, 0.0);\n  float strength = uModelParams[0].x;\n  if (uModelParams[1].w > 0.0) {\n    vec2 mapped = mMap.rg * 2.0 - 1.0;\n    direction = dot(mapped, mapped) > 1e-8 ? normalize(mapped) : direction;\n    strength *= mMap.b;\n  }\n  vec2 turned = vec2(\n    direction.x * uModelParams[0].y - direction.y * uModelParams[0].z,\n    direction.x * uModelParams[0].z + direction.y * uModelParams[0].y\n  );\n  aAlong = normalize(mTangent * turned.x + mBitangent * turned.y);\n  aAcross = cross(mNormal, aAlong);\n  aStrength = strength;\n}\n\n/** The stretched lobe at a half vector, 1 at the mirror direction: anisotropicLobe.ts. */\nfloat anisotropicLobe(vec3 h, float sourceRadius, float dist) {\n  float alpha = max(mRoughness * mRoughness, MIN_LOBE_ALPHA);\n  float alongWidth = alpha + (1.0 - alpha) * aStrength * aStrength;\n  float grow = sourceRadius / max(2.0 * dist, 1e-3);\n  float alongWide = clamp(alongWidth + grow, alongWidth, 1.0);\n  float acrossWide = clamp(alpha + grow, alpha, 1.0);\n  float energy = (alongWidth / alongWide) * (alpha / acrossWide);\n  float x = dot(aAlong, h) / alongWide;\n  float y = dot(aAcross, h) / acrossWide;\n  float z = dot(mNormal, h);\n  float d = x * x + y * y + z * z;\n  return energy / max(d * d, 1e-8);\n}\n\nvoid anisotropicLight(vec3 l, float sourceRadius, float dist) {\n  float ndl = max(dot(mNormal, l), 0.0);\n  vec3 h = normalize(l + mToEye);\n  vec3 tint = mix(mSpecColor, vec3(1.0), pow(1.0 - max(dot(mToEye, h), 0.0), 5.0) * mMetal);\n  mDiffuse = mAlbedo * ndl * (1.0 - mMetal);\n  mSpecular = ndl > 0.0 ? tint * anisotropicLobe(h, sourceRadius, dist) : vec3(0.0);\n}\n\n/* The environment's normal, bent toward the stretch by its strength and the surface's roughness. */\nvec3 anisotropicReflectNormal(vec3 n) {\n  vec3 across = cross(aAcross, mToEye);\n  vec3 bent = cross(across, aAcross);\n  float bend = aStrength * clamp(5.0 * mRoughness, 0.0, 1.0);\n  return normalize(mix(n, bent, bend));\n}\n";
+export declare const ANISOTROPIC_GLSL = "\n/* The stretch's frame and strength, gathered once with the surface. */\nvec3 aAlong;\nvec3 aAcross;\nfloat aStrength;\n\nvoid anisotropicSurface() {\n  vec2 direction = vec2(1.0, 0.0);\n  float strength = uModelParams[0].x;\n  if (uModelParams[1].w > 0.0) {\n    vec2 mapped = mMap.rg * 2.0 - 1.0;\n    direction = dot(mapped, mapped) > 1e-8 ? normalize(mapped) : direction;\n    strength *= mMap.b;\n  }\n  vec2 turned = vec2(\n    direction.x * uModelParams[0].y - direction.y * uModelParams[0].z,\n    direction.x * uModelParams[0].z + direction.y * uModelParams[0].y\n  );\n  vec3 along = mTangent * turned.x + mBitangent * turned.y;\n  /*\n   * A mesh with neither tangents nor texture coordinates has no frame to take a direction from,\n   * and normalising the zero it gives was a NaN that drew the whole surface black. Any direction in\n   * the surface stands in, the one across the world's up, so the highlight is stretched somewhere.\n   */\n  if (dot(along, along) < 1e-12) {\n    along = cross(abs(mNormal.y) < 0.999 ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0), mNormal);\n  }\n  aAlong = normalize(along);\n  aAcross = cross(mNormal, aAlong);\n  aStrength = strength;\n}\n\n/** The stretched lobe at a half vector, 1 at the mirror direction: anisotropicLobe.ts. */\nfloat anisotropicLobe(vec3 h, float sourceRadius, float dist) {\n  float alpha = max(mRoughness * mRoughness, MIN_LOBE_ALPHA);\n  float alongWidth = alpha + (1.0 - alpha) * aStrength * aStrength;\n  float grow = sourceRadius / max(2.0 * dist, 1e-3);\n  float alongWide = clamp(alongWidth + grow, alongWidth, 1.0);\n  float acrossWide = clamp(alpha + grow, alpha, 1.0);\n  float energy = (alongWidth / alongWide) * (alpha / acrossWide);\n  float x = dot(aAlong, h) / alongWide;\n  float y = dot(aAcross, h) / acrossWide;\n  float z = dot(mNormal, h);\n  float d = x * x + y * y + z * z;\n  return energy / max(d * d, 1e-8);\n}\n\n/**\n * The same stretch as GGX's own BRDF, `\u03C0 \u00B7 D \u00B7 Vis \u00B7 N\u00B7L`, for a surface whose highlight is\n * physical: the distribution normalised, and Smith's height-correlated masking stretched with it\n * (Heitz 2014, as Filament writes it). `anisotropicPhysicalLobe` in anisotropicLobe.ts.\n */\nfloat anisotropicPhysical(vec3 l, vec3 h, float ndl, float sourceRadius, float dist) {\n  float alpha = max(mRoughness * mRoughness, MIN_LOBE_ALPHA);\n  float alongWidth = alpha + (1.0 - alpha) * aStrength * aStrength;\n  float grow = sourceRadius / max(2.0 * dist, 1e-3);\n  float along = clamp(alongWidth + grow, alongWidth, 1.0);\n  float across = clamp(alpha + grow, alpha, 1.0);\n  float x = dot(aAlong, h) / along;\n  float y = dot(aAcross, h) / across;\n  float z = dot(mNormal, h);\n  float d = x * x + y * y + z * z;\n  float distribution = 1.0 / max(3.14159265 * along * across * d * d, 1e-8);\n  float ndv = max(dot(mNormal, mToEye), 1e-4);\n  float viewed = ndl * length(vec3(along * dot(aAlong, mToEye), across * dot(aAcross, mToEye), ndv));\n  float lit = ndv * length(vec3(along * dot(aAlong, l), across * dot(aAcross, l), ndl));\n  return 3.14159265 * distribution * (0.5 / max(viewed + lit, 1e-5)) * ndl;\n}\n\nvoid anisotropicLight(vec3 l, float sourceRadius, float dist) {\n  float ndl = max(dot(mNormal, l), 0.0);\n  vec3 h = normalize(l + mToEye);\n  vec3 tint = highlightTint(mSpecColor, max(dot(mToEye, h), 0.0), mMetal);\n  mDiffuse = mAlbedo * ndl * (1.0 - mMetal);\n  float lobe = physicalSpecular()\n    ? anisotropicPhysical(l, h, ndl, sourceRadius, dist)\n    : anisotropicLobe(h, sourceRadius, dist);\n  mSpecular = ndl > 0.0 ? tint * lobe : vec3(0.0);\n}\n\n/* The environment's normal, bent toward the stretch by its strength and the surface's roughness. */\nvec3 anisotropicReflectNormal(vec3 n) {\n  vec3 across = cross(aAcross, mToEye);\n  vec3 bent = cross(across, aAcross);\n  float bend = aStrength * clamp(5.0 * mRoughness, 0.0, 1.0);\n  return normalize(mix(n, bent, bend));\n}\n";

package/dist/render/shaders/flat/anisotropic.js

@@ -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/dist/render/shaders/flat/areaLight.d.ts

@@ -7,4 +7,4 @@
  *
  * Depth zero and after the models, whose `modelLight` it calls; see `flatFrag`.
  */
-export declare const AREA_LIGHT_GLSL = "\n/**\n * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the\n * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural\n * order \u2014 minus, plus, plus, minus \u2014 winds the other way, and every one-sided light then clamped to\n * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive\n * part and a two-sided one the magnitude.\n */\nfloat areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {\n  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);\n}\n\n/**\n * What one rectangle of colour `color` and form factor `form` adds to the lamps' two sums, open\n * and shadowed by `occl` and `glass`.\n *\n * **A model answers a rectangle as it answers a lamp at its centre**, carried at the rectangle's\n * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by the\n * form factor. An approximation, stated: a model's lobe is not integrated over the rectangle as the\n * standard lobe is, so a glossy model under a large softbox shows a lobe from its centre rather than\n * its shape.\n *\n * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.\n * What stood here once handed the closest point on the rectangle to `sphereLobe` and scaled it by\n * `form`, the *diffuse* form factor. Measured against a brute-force integral by\n * `scripts/areaSpecular.mjs`, that lost the reflection rather than blurring it: on polished metal\n * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface\n * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the\n * surface reflects and 79.0% for one overhead. `quadCoverage` says what fraction of the specular\n * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split\n * the probe path uses. **`dfg.x + dfg.y` and not `envSpecularEnergy`**, deliberately: the\n * compensation returns the multiply-scattered share, and every direct lobe in this shader is\n * single-scattering, so adding it here returns energy the light never had. Measured at 211%\n * against 40.1%.\n */\nvoid areaLightAdd(\n  vec3 centre,\n  vec3 right,\n  vec3 up,\n  vec2 halfSize,\n  vec3 color,\n  float form,\n  float occl,\n  vec3 glass,\n  vec3 n,\n  vec3 albedo,\n  float metal,\n  vec3 specColor,\n  float roughness,\n  bool modelled,\n  inout vec3 lampOpen,\n  inout vec3 lampShadowed\n) {\n  if (modelled) {\n    vec3 areaL = normalize(centre - vWorldPos);\n    modelLight(areaL, 0.0, 0.0);\n    vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form) * color;\n    lampOpen += areaModel;\n    lampShadowed += areaModel * occl * glass;\n    return;\n  }\n  /* Held back with the point lamps', and shadowed by the same term it always was. */\n  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);\n  lampOpen += areaDiffuse;\n  lampShadowed += areaDiffuse * occl * glass;\n\n  if (vSpecular > 0.0 || metal > 0.0) {\n    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);\n    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);\n    if (coverage > 0.0) {\n      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);\n      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);\n      vec3 areaHighlight = areaSpec * color * coverage;\n      lampOpen += areaHighlight;\n      lampShadowed += areaHighlight * occl * glass;\n    }\n  }\n}\n";
+export declare const AREA_LIGHT_GLSL = "\n/**\n * The rectangle's signed form factor at this fragment: its corners **wound so a surface on the\n * emitting side sees them counter-clockwise**, which is what makes it positive there. The natural\n * order \u2014 minus, plus, plus, minus \u2014 winds the other way, and every one-sided light then clamped to\n * zero and the frame was black. The sign is the sidedness: a one-sided rectangle takes the positive\n * part and a two-sided one the magnitude.\n */\nfloat areaSignedForm(vec3 n, vec3 centre, vec3 right, vec3 up, vec2 halfSize) {\n  vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n  vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n  vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n  vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n  return quadFormFactor(n, vWorldPos, c0, c1, c2, c3);\n}\n\n/**\n * How far along one of a rectangle's axes a fragment still sees it past the barn door on that axis's\n * positive edge: `p` the fragment's place along the axis, `height` its height above the\n * rectangle's plane, `halfSize` the rectangle's half extent, and the door's tip `tipOut` beyond\n * the edge and `tipUp` above the plane. Points of the rectangle past the answer are hidden.\n *\n * Above the tip, the tip's shadow on the plane as seen from the fragment is the limit. Below it, a\n * fragment beside the door and outside its line is hidden from all of it, and one inside the door's\n * reach is hidden from none of it.\n */\nfloat barnDoorLimit(float p, float height, float halfSize, float tipOut, float tipUp) {\n  float tipAt = halfSize + tipOut;\n  if (height > tipUp) return (height * tipAt - tipUp * p) / (height - tipUp);\n  if (p > halfSize && height * tipOut < tipUp * (p - halfSize)) return -1e9;\n  return 1e9;\n}\n\n/**\n * The part of a rectangle a fragment sees past its barn doors, written into `centre` and\n * `halfSize` as the smaller rectangle that is left, or false where the doors hide all of it.\n * `doors` is the cosine of their angle from the normal and their length; a length of 0 is no doors.\n * Each axis is clipped by its own two doors, which is what makes this four projections and a min.\n */\nbool areaBarnDoors(inout vec3 centre, vec3 right, vec3 up, inout vec2 halfSize, vec2 doors) {\n  if (doors.y <= 0.0) return true;\n  vec3 toFragment = vWorldPos - centre;\n  float height = dot(toFragment, cross(right, up));\n  /* Behind the emitting side: nothing to clip, and the form factor already answers it. */\n  if (height <= 0.0) return true;\n  float tipOut = doors.y * sqrt(max(1.0 - doors.x * doors.x, 0.0));\n  float tipUp = doors.y * doors.x;\n  vec2 p = vec2(dot(toFragment, right), dot(toFragment, up));\n  vec2 hi = vec2(\n    min(halfSize.x, barnDoorLimit(p.x, height, halfSize.x, tipOut, tipUp)),\n    min(halfSize.y, barnDoorLimit(p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  vec2 lo = vec2(\n    max(-halfSize.x, -barnDoorLimit(-p.x, height, halfSize.x, tipOut, tipUp)),\n    max(-halfSize.y, -barnDoorLimit(-p.y, height, halfSize.y, tipOut, tipUp))\n  );\n  if (hi.x <= lo.x || hi.y <= lo.y) return false;\n  centre += right * (0.5 * (lo.x + hi.x)) + up * (0.5 * (lo.y + hi.y));\n  halfSize = 0.5 * (hi - lo);\n  return true;\n}\n\n/**\n * What one rectangle of colour `color` and form factor `form` adds to the lamps' two sums, open\n * and shadowed by `occl` and `glass`.\n *\n * **A model answers a rectangle as it answers a lamp at its centre**, carried at the rectangle's\n * own energy: the diffuse by the exact form factor over the centre's cosine, the specular by the\n * form factor. An approximation, stated: a model's lobe is not integrated over the rectangle as the\n * standard lobe is, so a glossy model under a large softbox shows a lobe from its centre rather than\n * its shape.\n *\n * **The standard lobe is integrated over the rectangle**, rather than sampled at one point on it.\n * What stood here once handed the closest point on the rectangle to `sphereLobe` and scaled it by\n * `form`, the *diffuse* form factor. Measured against a brute-force integral by\n * `scripts/areaSpecular.mjs`, that lost the reflection rather than blurring it: on polished metal\n * facing a softbox it returned 0.000233 where the integral is 0.9207, and head-on on a rough surface\n * it was 3.7 times too bright. Worst 287% either way; this is 40.1% where the light is what the\n * surface reflects and 79.0% for one overhead. `quadCoverage` says what fraction of the specular\n * lobe the rectangle covers and the environment BRDF says how much the surface returns, the split\n * the probe path uses. **`dfg.x + dfg.y` and not `envSpecularEnergy`**, deliberately: the\n * compensation returns the multiply-scattered share, and every direct lobe in this shader is\n * single-scattering, so adding it here returns energy the light never had. Measured at 211%\n * against 40.1%.\n */\nvoid areaLightAdd(\n  vec3 centre,\n  vec3 right,\n  vec3 up,\n  vec2 halfSize,\n  vec3 color,\n  float form,\n  float occl,\n  vec3 glass,\n  vec3 n,\n  vec3 albedo,\n  float metal,\n  vec3 specColor,\n  float roughness,\n  bool modelled,\n  inout vec3 lampOpen,\n  inout vec3 lampShadowed\n) {\n  if (modelled) {\n    vec3 areaL = normalize(centre - vWorldPos);\n    modelLight(areaL, 0.0, 0.0);\n    vec3 areaModel = (mDiffuse * (form / max(dot(n, areaL), 1e-3)) + mSpecular * form) * color;\n    lampOpen += areaModel;\n    lampShadowed += areaModel * occl * glass;\n    return;\n  }\n  /* Held back with the point lamps', and shadowed by the same term it always was. */\n  vec3 areaDiffuse = albedo * color * form * (1.0 - metal);\n  lampOpen += areaDiffuse;\n  lampShadowed += areaDiffuse * occl * glass;\n\n  if (vSpecular > 0.0 || metal > 0.0) {\n    vec3 c0 = centre - right * halfSize.x + up * halfSize.y;\n    vec3 c1 = centre + right * halfSize.x + up * halfSize.y;\n    vec3 c2 = centre + right * halfSize.x - up * halfSize.y;\n    vec3 c3 = centre - right * halfSize.x - up * halfSize.y;\n    vec3 toEyeArea = normalize(uCameraPos - vWorldPos);\n    float coverage = quadCoverage(n, vWorldPos, toEyeArea, roughness, c0, c1, c2, c3);\n    if (coverage > 0.0) {\n      vec2 areaDfg = envBrdfApprox(max(dot(n, toEyeArea), 0.0), roughness);\n      vec3 areaSpec = specColor * areaDfg.x + vec3(areaDfg.y);\n      vec3 areaHighlight = areaSpec * color * coverage;\n      lampOpen += areaHighlight;\n      lampShadowed += areaHighlight * occl * glass;\n    }\n  }\n}\n";

package/dist/render/shaders/flat/areaLight.js

@@ -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/dist/render/shaders/flat/glassTint.d.ts

@@ -8,7 +8,7 @@ export declare function glassTintGlsl(glassShadows: boolean): string;
  * The lit stage's switches, by the name of the constant each is: the decision both backends make
  * about which optional code a lit program carries. See `litSwitchesGlsl`.
  */
-export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT';
+export type LitSwitch = 'GLASS_SHADOWS' | 'CLUSTERED_LIGHTS' | 'LIGHT_FIXTURES' | 'SURFACE_EFFECTS' | 'DRIFT_LIGHT' | 'PHYSICAL_SPECULAR' | 'SURFACE_OVERLAY' | 'REFLECTION_MAPS';
 /** Every switch off: what a renderer starts from before its profile and its content say otherwise. */
 export declare function noLitSwitches(): Record<LitSwitch, boolean>;
 /** Which of the lit stage's optional features a build reads. See `litSwitchesGlsl`. */
@@ -29,6 +29,7 @@ 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 declare function litSwitchesGlsl(switches: LitSwitches): string;

package/dist/render/shaders/flat/glassTint.js

@@ -31,6 +31,9 @@ export function noLitSwitches() {
         LIGHT_FIXTURES: false,
         SURFACE_EFFECTS: false,
         DRIFT_LIGHT: false,
+        PHYSICAL_SPECULAR: false,
+        SURFACE_OVERLAY: false,
+        REFLECTION_MAPS: false,
     };
 }
 /**
@@ -44,7 +47,8 @@ export function noLitSwitches() {
  * 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) {
     return /* glsl */ `

package/dist/render/shaders/flat/index.d.ts

@@ -104,6 +104,21 @@ 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;
+    /**
+     * Whether it carries a draw's surface overlay, `uOverlay` and all (`setSurfaceOverlay`). True
+     * when absent. See `overlayGlsl`.
+     */
+    readonly surfaceOverlay?: boolean;
+    /**
+     * Whether the frame's own draws write the reflection maps beside their colour: WebGL2's way to
+     * the frame's materials' reflections. True when absent. See `reflectionSurfaceGlsl`.
+     */
+    readonly reflectionMaps?: boolean;
     /**
      * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
      *

package/dist/render/shaders/flat/index.js

@@ -14,11 +14,13 @@ import { CLOTH_BINDING_GLSL } from '../clothBinding.js';
 import { SKINNING_GLSL } from '../skinning.js';
 import { SURFACE_GLSL } from './surface.js';
 import { MAIN_GLSL } from './main.js';
-import { MODELS_GLSL } from './models.js';
+import { modelsGlsl } from './models.js';
 import { AREA_LIGHT_GLSL } from './areaLight.js';
 import { NORMAL_MAP_GLSL } from './normalMap.js';
 import { DRIFT_LIGHT_GLSL } from './driftLight.js';
 import { SURFACE_EFFECTS_GLSL } from './surfaceEffects.js';
+import { overlayGlsl } from './overlay.js';
+import { reflectionSurfaceGlsl } from './reflectionSurface.js';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.js';
 import { FULL_LIGHT_BUDGET } from '../../uniformVectorBudget.js';
 /**
@@ -244,6 +246,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
@@ -292,7 +303,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;
@@ -456,7 +472,11 @@ export function flatFrag(options) {
         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, so its switch takes the next id; depth zero, as main calls it. */
+        overlayGlsl(options.surfaceOverlay ?? true),
+        /* After the overlay, so its switch takes the next id. See reflectionSurface.ts. */
+        reflectionSurfaceGlsl(options.reflectionMaps ?? true),
         /* After the models, whose answer to a rectangle it asks for. See areaLight.ts. */
         AREA_LIGHT_GLSL,
         MAIN_GLSL,

package/dist/render/shaders/flat/lobes.d.ts

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

package/dist/render/shaders/flat/lobes.js

@@ -27,6 +27,54 @@ export const EMISSIVE_SHADOW_SHARE = 0.55;
  * deliberately not this.
  */
 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)},
@@ -153,49 +201,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