three-realtime-rt 0.3.2 → 0.4.0

package/README.md

@@ -10,6 +10,18 @@ the scene, **ReSTIR many-light sampling** (flat cost in light count),
 **blue-noise sampling**, and real-time **temporal denoising + anti-aliasing**.
 Runs on plain WebGL2.
 
+This round adds **GGX PBR specular** — Cook-Torrance dielectric highlights in a
+separate specular buffer, so `roughness` finally matters on non-metals — plus
+**normal / roughness / metalness maps**, **alpha-blended transparency**
+(single-layer deferred blend), **deforming dynamic meshes** (a mirror-water pool
+whose traced reflections follow the live wave surface), **overscan** to hide
+leading-edge convergence noise while the camera turns, and **emissive importance
+sampling** (area × luminance) for calmer area lights. The zero-config renderer
+now ships **conservative, self-scaling defaults** — it starts low-but-ray-traced
+and an on-by-default governor scales quality up toward `targetFps`; an optional
+async **GPU tier probe** reads real WebGPU adapter limits for a smarter starting
+point.
+
 The library ships as **untranspiled ES modules** (the `src/` folder) — it has no
 build step of its own, so you consume it through your bundler (Vite, webpack,
 esbuild, …) or a browser import map that resolves the bare `three` /
@@ -101,6 +113,17 @@ loop();
 On hardware that can't trace, `rt.render` transparently falls back to
 `renderer.render` — no capability branch needed (see [Running everywhere](#running-everywhere-capability-tiers)).
 
+> **Defaults are conservative.** Zero-config construction
+> (`new RealtimeRaytracer(renderer)`) starts *low but still ray traced* — half
+> lighting resolution, stochastic direct light, a lean denoise — so it runs
+> acceptably on weak discrete and integrated GPUs out of the box. The adaptive
+> governor is **on by default** and scales quality **up** toward `targetFps`
+> when it measures headroom (a strong desktop climbs to full-resolution
+> lighting within a couple of seconds). Want to start higher, or pin a level?
+> Pass `RealtimeRaytracer.recommendedOptions(RealtimeRaytracer.detectTier(renderer))`
+> (or `probeGPUTier()` — see [Running everywhere](#running-everywhere-capability-tiers)),
+> or explicit options.
+
 ### Integrating into an existing app
 
 A checklist for dropping the tracer into a scene you already have:
@@ -179,6 +202,46 @@ that is re-baked and refit per frame. `updateDynamic()` therefore costs
 ~1 ms for dozens of moving objects *regardless of how big the static world is* —
 skip it entirely on frames where nothing moved.
 
+### Deforming meshes (water, cloth)
+
+By default a dynamic mesh is **rigid**: its vertices are snapshotted at compile
+time and only re-transformed by `mesh.matrixWorld` each frame — so CPU edits to
+its `position` attribute show in the rasterized image but the *traced* rays
+(shadows, GI, reflections) still hit the original shape. For a mesh whose
+vertices actually move on the CPU (a water surface, cloth, a morph target), set
+`userData.rtDeforming` so the raytracer re-reads its live geometry every frame:
+
+```js
+water.userData.rtDeforming = true;           // opt in
+rt.compileScene(scene, { dynamicMeshes: [water, ...crates] });
+
+// each frame:
+deformWaterVertices(water.geometry, t);       // your CPU wave/cloth solver
+water.geometry.attributes.position.needsUpdate = true;
+water.geometry.computeVertexNormals();        // REQUIRED — see below
+rt.updateDynamic();                            // re-reads the live vertices
+rt.render(scene, camera);
+```
+
+Two requirements:
+
+- **You own the normals.** The tracer reads the mesh's live `normal` attribute
+  for deforming segments — it does not recompute them. Call
+  `geometry.computeVertexNormals()` (or update the attribute yourself) after
+  moving the vertices, or the shading/reflections will track the old silhouette.
+- **The vertex count is fixed at compile time.** Deforming an existing surface is
+  free; changing its topology (adding/removing vertices) is not — `updateDynamic()`
+  throws with a clear message telling you to `compileScene()` again.
+
+**Cost model.** A deforming segment is re-baked from its live vertices every
+frame and its normals are re-uploaded every frame (rigid movers amortize the
+normal upload over 8 frames). Both are O(dynamic triangles), and the cheap
+per-frame BVH `refit()` (kept for surfaces that stay roughly in place, like a
+water plane) is O(dynamic tris) too — so **keep deforming meshes low-poly**. A
+`48×48` plane is ≈ 4.6k triangles, which refits in well under a millisecond; a
+`256×256` plane (~131k tris) will dominate the frame. The demo's mirror-water
+pool is a `48×48` plane.
+
 ## Live lighting & sky
 
 Lights can be toggled, moved, and recoloured every frame without recompiling:
@@ -208,10 +271,12 @@ const rt = new RealtimeRaytracer(renderer, {
 
 ## What is and isn't supported
 
-Primary visibility is ordinary rasterized three.js, so **whatever three.js draws,
-you still see** — transparency, blending, sorting, custom shaders and post effects
-behave exactly as normal. The ray tracer computes only the *lighting*, and it
-reads a deliberately small, fixed slice of the material and light model. This is
+Primary visibility is rasterized into a G-buffer, so **whatever three.js draws,
+you still see** — the ray tracer computes only the *lighting*, reading a
+deliberately small, fixed slice of the material and light model. The one place
+the G-buffer diverges from a plain three.js draw is transparency: it is a
+**single-layer deferred blend** (see the `transparent` row below and the
+Rendering-model notes), not three.js's per-fragment sorted over-blend. This is
 the honest map of what actually feeds the traced lighting.
 
 ### Materials
@@ -223,13 +288,17 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 | Property | Feeds lighting? | Notes |
 |----------|-----------------|-------|
 | `color` + `map` | ✅ | Albedo = `color × map.rgb`. Textures stay sharp (irradiance is demodulated, then re-multiplied). |
-| `roughness` | ✅ | **Scalar only.** Drives shadow / GI softness and reflection sharpness. |
-| `metalness` | ✅ | **Scalar only.** Metallic pixels trace a reflection ray. |
-| `emissive` | ✅ | A *static* emissive mesh becomes a real **area light** (NEE) — casts soft light + shadows. |
+| `roughness` | ✅ | Drives shadow / GI softness, reflection sharpness **and the GGX specular lobe width** (see *dielectric specular* below). |
+| `metalness` | ✅ | Metallic pixels trace a reflection ray whose analytic-light glints are shadowed; `F0 = mix(0.04, albedo, metalness)`. |
+| `emissive` | ✅ | A *static* emissive mesh becomes a real **area light** (NEE) — casts soft light + shadows, including a GGX highlight. |
 | `emissiveMap` | ⚠️ visible only | A map-masked emissive **glows on screen** but the map **zeroes its area-light table** — it lights nothing. Use a flat `emissive` colour (no map) for an emitter that should illuminate. |
-| `transmission` (Physical) | ✅ | Glass: Fresnel reflection + two-interface refraction. |
-| `roughnessMap` / `metalnessMap` | ❌ | Only the scalar `roughness` / `metalness` are used; these maps are ignored by lighting. |
-| `normalMap` | ❌ | Lighting uses geometric normals; normal maps don't perturb shading. |
+| `transmission` (Physical) | ✅ | Glass: Fresnel reflection (with analytic-light glints) + two-interface refraction. |
+| `transparent` + `opacity` | ✅ | Alpha blend: the surface is composited over the geometry behind it (a straight-through traced ray), weighted by scalar `opacity` and **tinted by `color`/`map`**. The behind-radiance rides the **specular buffer** and the opacity blend happens at **composite** (where the pane's albedo lives), so **needs `specular: true`** — with the specular buffer off, blend surfaces degrade to opaque. Single layer — nearest transparent surface wins, overlapping panes don't inter-sort. Kept out of the BVH, so it casts no shadow. Toggle with `transparency`. |
+| `opacity` on an opaque material | ❌ | Only read when `transparent: true`; an opaque material always writes at full coverage. |
+| **dielectric specular** | ✅ | Cook-Torrance **GGX** direct highlights for *every* surface, in a separate white (`F0 ≈ 0.04`) specular buffer the composite adds without the albedo multiply. Toggle with `specular` (default on). |
+| `roughnessMap` | ✅ | `roughness × roughnessMap.g` (three.js convention) — sampled in the G-buffer. |
+| `metalnessMap` | ✅ | `metalness × metalnessMap.b` (a packed ORM texture works — G = roughness, B = metalness). |
+| `normalMap` | ✅ | Perturbs the shading normal via a screen-space cotangent frame (no tangent attribute needed); respects `material.normalScale`. |
 | `clearcoat`, `sheen`, `iridescence` | ❌ | Not modelled. |
 | vertex colors | ❌ | Not read into albedo. |
 | per-material `ior` | ❌ | Refraction uses the single **global** `rt.ior` (default 1.5), never `material.ior`. |
@@ -246,6 +315,13 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 | `RectAreaLight` | ❌ | Use an emissive mesh instead. |
 | `HemisphereLight` / `AmbientLight` | ❌ | Ignored — the procedural `sky` (or `envColor`) provides ambient. |
 
+- **Emissive noise caveat:** emissive NEE is the noisiest direct-light path — one
+  uniformly-picked triangle sample per pixel per frame, with a `1/dist²` term that
+  sparkles into fireflies near small, close emitters. **Keep `restir: true` in any
+  scene that leans on emissive lighting** (the reservoirs converge each pixel onto
+  the emitter that matters; the library logs a hint if you compile emissive
+  geometry with ReSTIR off). Prefer larger/dimmer emitter surfaces over tiny
+  bright ones, and let `fireflyClamp` do its job.
 - Up to **32** point/directional lights (`MAX_LIGHTS`); further lights are dropped.
 - Moving, toggling, recolouring or dimming a light → `rt.updateLights(scene)` (cheap, no recompile).
 - Changing a mesh's **emissive** (it's an area light baked at compile time) → `rt.compileScene(...)` again.
@@ -265,7 +341,7 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 - **Reflections** are a single traced bounce into a **diffuse-shaded** view of the world — no recursive mirror-in-mirror; a metal shows its surroundings, not a second full render.
 - **Refraction** is two-interface (front + back) with a single global IOR — convincing glass, not a spectral / dispersive renderer.
 - **Volumetric** is **single-scatter** god rays, not multiple-scattering fog.
-- Because primary visibility is rasterized, **blending, sorting and transparency composite exactly like normal three.js** — the tracer never changes how your transparent surfaces layer.
+- **Transparency** is a **single-layer deferred blend**: a `transparent` surface writes as the nearest layer of the G-buffer and the lighting pass composites it over the geometry behind by tracing one straight-through ray. The behind-radiance is fully lit (direct + 1-bounce GI) and tinted by the pane's albedo. Overlapping transparent surfaces do **not** inter-sort (only the nearest is kept), and there is no per-pixel back-to-front over-blend of many layers as in raster three.js. Turn it off with `transparency: false` (blend surfaces then render fully opaque).
 
 ### Platform
 
@@ -278,16 +354,22 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 | Option | Default | What |
 |--------|---------|------|
 | `renderScale` | `0.5` | Lighting resolution vs. the G-buffer. `1.0` = max quality. |
+| `overscan` | `0` | Render past the canvas edges and crop the centre back, so leading-edge disocclusion noise during camera motion is born off-screen. Padding fraction per edge (0–0.25); `0.1` costs 1.44× the pixels. See *Edge convergence and overscan*. |
+| `adaptiveQuality` | `true` | Governor that steers `renderScale` / `denoiseIterations` / `stochasticLights` toward `targetFps` — scales **up** on strong hardware, **down** on weak. Turn off for manual control. |
+| `denoiseIterations` | `2` | À-trous denoise passes; the governor raises this as it lowers resolution. |
 | `taa` | `true` | Temporal anti-aliasing (jitter + neighbourhood clamp). |
 | `denoise` | `true` | Edge-aware à-trous denoiser. |
 | `gi` | `true` | 1-bounce global illumination (vs. direct-only). |
 | `emissiveNEE` | `true` | Sample static emissive meshes as area lights (next-event estimation). Off = emitters only light via lucky GI rays. |
+| `emissiveImportance` | `true` | Pick WHICH emissive triangle NEE samples proportional to **area × emitted luminance** (compile-time power CDF) instead of a uniform 1-of-N. Same mean, far less sparkle when emitters differ in size/brightness. Off = legacy uniform pick. |
+| `specular` | `true` | Cook-Torrance **GGX** dielectric highlights for every surface, in a separate white (`F0 ≈ 0.04`) buffer the composite adds without the albedo multiply. Off = the old Lambert-only look. Also required by `transparency`. |
 | `reflections` | `true` | Traced mirror/glossy reflections on metallic surfaces (sharpest at `renderScale: 1`). |
 | `refraction` | `true` | Traced two-interface refraction for `MeshPhysicalMaterial.transmission` surfaces. |
+| `transparency` | `true` | Alpha-blended transparency: composite `transparent` meshes over the geometry behind them (single-layer, weighted by `opacity`, tinted by albedo). Needs the specular buffer (`specular: true`). Off = they render fully opaque. |
 | `restir` | `true` | ReSTIR direct lighting: per-pixel reservoirs with temporal + spatial reuse, one visibility ray regardless of light count. Flat cost in light count; cuts emissive area-light noise. |
 | `ior` | `1.5` | Index of refraction used by `refraction`. |
 | `volumetric` | *off* | Physically-based god rays: single-scatter fog, one BVH-shadowed light sample per lighting pixel per frame, temporally accumulated. `{ enabled, density, maxDist, zones }`, where `zones` is an optional array of up to 8 AABBs `{ min:[x,y,z], max:[x,y,z], density }` that add localized fog on top of (or instead of) the global `density`. |
-| `stochasticLights` | `false` | One direct shadow ray per pixel per frame (random source) instead of one per light. |
+| `stochasticLights` | `true` | One direct shadow ray per pixel per frame (random source) instead of one per light. The governor turns it off once it has scaled resolution up on strong hardware. |
 | `temporalReprojection` | `true` | Keep samples across camera/object motion. |
 | `maxHistory` | `128` | History cap — higher is smoother, slower to react. |
 | `fireflyClamp` | `4.0` | Clamp on indirect luminance to suppress fireflies. |
@@ -300,9 +382,42 @@ rasterizes and gets lit — useful for water / translucent surfaces).
 Transparent materials never act as occluders (a glass case shouldn't cast an
 opaque shadow); `alphaTest` cut-outs still do.
 
+## Edge convergence and overscan
+
+Lighting is accumulated over time (temporal reprojection). When the camera
+moves, pixels newly revealed at the **leading screen edge** have no history to
+reproject from, so they start from a single noisy sample and take several frames
+to converge — a shimmering band that rides the edge you are turning toward.
+
+`overscan` hides it by rendering *bigger than the screen*. Every internal pass
+(G-buffer, lighting, denoise, volumetric, composite, TAA history) runs at a
+padded resolution with a proportionally **widened field of view**, and only the
+final on-screen draw crops the central canvas-sized region out. Disoccluded
+pixels are then born in the padding — off-screen — and have already converged by
+the time the camera turns far enough to bring them into view.
+
+```js
+const rt = new RealtimeRaytracer(renderer, { overscan: 0.1 });
+// or live: rt.overscan = 0.05;  (reallocates targets; resets accumulation)
+```
+
+`overscan` is the padding fraction **per edge**. `0.1` on a 1000×600 canvas
+renders 1200×720 internally and crops the central 1000×600 — both axes pad by
+the same fraction, so aspect ratio is preserved and the widened frustum stays
+centred on your camera's. The cost is purely the extra pixels: `1 + 2·overscan`
+per axis, so **0.1 → 1.44×** the work of every pass. **0.05–0.1** is the useful
+range; more just spends pixels on padding you will rarely turn fast enough to
+need. Changing it live reallocates the targets and resets accumulation, so treat
+it as a settings-time knob rather than a per-frame one. The camera you pass to
+`render()` is never mutated — the widened projection is applied and restored
+internally each frame, exactly like the TAA jitter.
+
 ## Running everywhere (capability tiers)
 
-Nothing adaptive is imposed — everything below is **opt-in**:
+The zero-config defaults are **conservative and self-scaling**: construction
+starts low-but-ray-traced and the adaptive governor (on by default) walks
+quality up or down toward `targetFps`. The knobs below let you set a smarter
+starting point or take manual control:
 
 - **No usable GPU** (missing WebGL2 float targets, or a software rasterizer
   like SwiftShader): the library logs one console warning and `rt.render()`
@@ -321,7 +436,30 @@ Nothing adaptive is imposed — everything below is **opt-in**:
   });
   ```
 
-- **Adaptive quality** (`adaptiveQuality: true`, default **false**): continuous
+- **GPU probe** (`await RealtimeRaytracer.probeGPUTier(renderer?)`): an optional,
+  async, more-informed alternative to `detectTier`. When the browser exposes
+  **WebGPU** it inspects the real adapter limits; otherwise it falls back to the
+  WebGL heuristic. Returns `{ tier, source: "webgpu"|"webgl"|"fallback", details }`.
+
+  ```js
+  const probe = await RealtimeRaytracer.probeGPUTier(renderer);
+  const rt = new RealtimeRaytracer(renderer, RealtimeRaytracer.recommendedOptions(probe.tier));
+  ```
+
+  **Honest heuristic — WebGPU does NOT expose VRAM.** There is no API for actual
+  video memory, so the probe uses `adapter.limits` (`maxBufferSize`,
+  `maxTextureDimension2D`, …) as a *proxy* for GPU class — two cards with wildly
+  different VRAM can report the same limits. `adapter.info`
+  (vendor/architecture/description) is masked on many browsers, so it is a hint
+  only. Screen resolution is factored in: `screenPixels = screen.width *
+  screen.height * min(devicePixelRatio, 2)`; a 4K-class panel (`>= 6e6`) has to
+  fill ~4× the pixels of 1080p, so a GPU is only rated `"high"` on such a screen
+  when `maxBufferSize >= 4GiB` (otherwise it is demoted to `"mid"`). Software
+  renderers (SwiftShader / llvmpipe) rate `"none"`. Every threshold and the raw
+  values are echoed back in `details`. The constructor stays synchronous — this
+  is a pre-construction, opt-in call.
+
+- **Adaptive quality** (`adaptiveQuality: true`, default **true**): continuous
   dynamic resolution scaling. Watches real frame time and steers the lighting
   resolution smoothly toward `targetFps` (in 5% steps with a cooldown), pairing
   low resolutions with MORE denoise passes (they run at lighting res, so
@@ -342,16 +480,29 @@ npm install
 npm run dev       # http://localhost:8115
 ```
 
-The demo ([`examples/`](examples/)) is an ordinary three.js app — see
+The demo ([`examples/`](examples/)) is a **panoramic museum gallery** — a
+Cornell-style room (saturated red/teal side walls for obvious colour bleed, open
+top) staged as an exhibit where every renderer feature gets its own vignette: a
+**deforming mirror-water pool** under the emissive gallery light, the
+DamagedHelmet hero on a pedestal under a toggleable **spotlight** (normal /
+roughness maps + analytic-light glints), a glossy teapot showing **GGX dielectric
+specular** against the teal wall, a gold torus knot and mirror sphere (traced
+reflections), a glass sphere (refraction), a roughness ramp on plinths, and the
+**duck in a glass vitrine** (alpha-blended transparency that casts no shadow onto
+the exhibit). An always-on **fps readout** sits top-left and a **collapsible
+control panel** (starts collapsed on phones) toggles every feature, drives a
+clerestory-window light slider, and spawns the 40-body physics pile. See
 [`examples/main.js`](examples/main.js) for the full, commented integration
 (scene → physics → compile → render loop). `npm run deploy` builds and publishes
 it to GitHub Pages.
 
 ## Gallery & benchmarks
 
-[`gallery.html`](gallery.html) drops the raytracer into **stock glTF scenes it
-was never authored for** — LittlestTokyo, Lantern, Antique Camera, BoomBox,
-Corset, Water Bottle, and the Damaged Helmet — streamed straight from their
+[`gallery.html`](gallery.html) opens on a built-in **Cornell box** (the classic
+GI reference — coloured walls, an emissive ceiling panel) and drops the raytracer
+into **stock glTF scenes it was never authored for** — Littlest Tokyo, Lantern,
+Damaged Helmet, Antique Camera, BoomBox, Corset, Water Bottle, Toy Car,
+Iridescence Lamp, Mosquito in Amber, and Fox — streamed straight from their
 public hosts (no assets committed). A one-button toggle A/Bs ray tracing against
 plain rasterized three.js with an fps + triangle readout, and a compact options
 strip exposes GI / emissive NEE / reflections / refraction / ReSTIR / denoise /
@@ -361,6 +512,22 @@ TAA / volumetric plus lighting-resolution and auto-quality controls.
 GPU-**fence-timed** frame costs and a temporal **ghosting metric**, writing each
 run's results to [`bench-results/`](bench-results/) for tracking regressions.
 
+### Movement-artifact harness
+
+[`harness.html`](harness.html) makes the **edge-of-screen convergence noise seen
+while the camera moves** measurable and eyeball-able. It drives the demo scene
+along a deterministic path (`strafe` — sinusoidal side-to-side — or `orbit`;
+pose is a pure function of sim-time) and, every couple of frames, reads three
+vertical bands off the drawing buffer — the outer 10% at each edge and the
+central 10% — tracking **per-pixel temporal luminance variance** over a sliding
+window. The HUD reports the three mean-variance numbers; the headline is the
+**edge-vs-center ratio** (>1 = edges noisier than the middle — the artifact the
+overscan feature targets). A magnified side-by-side inset shows a left-edge strip
+next to a center strip for human comparison, and the metric triple is logged as a
+JSON line to the console every 2s for automated scraping. The overscan control
+is **feature-detected** — it appears only when the loaded build exposes an
+`overscan` property.
+
 ## Roadmap
 
 | Stage | Status | What |
@@ -375,7 +542,8 @@ run's results to [`bench-results/`](bench-results/) for tracking regressions.
 | 6. Specular | ✅ | Mirror/glossy reflections on metals + two-interface glass refraction |
 | 6b. Sampling | ✅ | Blue-noise sampling + ReSTIR direct lighting (temporal + spatial reuse) |
 | 6c. Any-hit shadows | ✅ | Unordered early-out BVH traversal for occlusion rays — same image, up to ~2× cheaper shadows |
-| 7. Publish | — | npm publish; refractive water; per-material IOR |
+| 6d. PBR materials | ✅ | Cook-Torrance GGX dielectric specular + normal/roughness/metalness maps, alpha-blended transparency, deforming (water) meshes, overscan |
+| 7. Next | — | Skinned-mesh (animated) shadows; DDGI irradiance probes; ReSTIR GI (indirect reservoir reuse); WGSL / WebGPU backend; per-material IOR |
 
 ## Credits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-realtime-rt",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Turn-on ray traced lighting for three.js: a hybrid deferred renderer with BVH-traced soft shadows, one-bounce global illumination, temporal reprojection, an a-trous denoiser and TAA.",
   "type": "module",
   "main": "src/index.js",

package/src/CompositePass.js

@@ -19,6 +19,8 @@ in vec2 vUv;
 ${SKY_GLSL}
 
 uniform sampler2D uIrradiance;
+uniform sampler2D uSpecular;   // dielectric direct specular (added WITHOUT albedo)
+uniform bool uSpecEnabled;
 uniform sampler2D uGAlbedoRough;
 uniform sampler2D uGNormalMetal;
 uniform sampler2D uGWorldPos;
@@ -27,7 +29,8 @@ uniform sampler2D uVolumetric; // in-scattered light (quarter canvas res, smooth
 uniform vec2 uVolTexelSize;
 uniform bool uVolEnabled;
 uniform vec3 uBackgroundColor;
-// 0 composite, 1 albedo, 2 normal, 3 irradiance (direct+GI), 4 worldPos, 5 emissive
+// 0 composite, 1 albedo, 2 normal, 3 irradiance (direct+GI), 4 worldPos,
+// 5 emissive, 6 specular
 uniform int uOutputMode;
 
 // joint bilateral upsample (lighting may be rendered below full resolution)
@@ -35,6 +38,11 @@ uniform bool uUpsample;
 uniform vec2 uIrrTexelSize;
 uniform vec3 uCameraPos;
 
+// Overscan crop: maps this on-screen pixel's UV into the central region of the
+// padded internal image (scale.xy, offset.zw). Identity (1,1,0,0) when overscan
+// is 0 or when compositing into the offscreen target that TAA later crops.
+uniform vec4 uCrop;
+
 // distance fog (applied in linear space, before tonemap)
 uniform bool uFogEnabled;
 uniform vec3 uFogColor;
@@ -63,8 +71,8 @@ vec3 acesFilm(vec3 x) {
 // Upsample low-res irradiance to this full-res pixel: 4 nearest low-res taps,
 // bilinear weights modulated by geometric similarity (plane distance + normal)
 // so lighting never bleeds across depth or orientation discontinuities.
-vec3 sampleIrradiance(vec2 uv, vec3 P, vec3 N) {
-  if (!uUpsample) return texture(uIrradiance, uv).rgb;
+vec3 upsampleGuided(sampler2D tex, vec2 uv, vec3 P, vec3 N) {
+  if (!uUpsample) return texture(tex, uv).rgb;
 
   float planeTol = 0.01 * distance(P, uCameraPos) + 1e-3;
   vec2 base = uv / uIrrTexelSize - 0.5;
@@ -80,7 +88,7 @@ vec3 sampleIrradiance(vec2 uv, vec3 P, vec3 N) {
   for (int dy = 0; dy <= 1; dy++) {
     for (int dx = 0; dx <= 1; dx++) {
       vec2 tuv = uv00 + vec2(float(dx), float(dy)) * uIrrTexelSize;
-      vec3 irr = texture(uIrradiance, tuv).rgb;
+      vec3 irr = texture(tex, tuv).rgb;
       float bw = (dx == 0 ? 1.0 - f.x : f.x) * (dy == 0 ? 1.0 - f.y : f.y);
       if (bw > bestBilW) { bestBilW = bw; bestBil = irr; }
 
@@ -106,22 +114,41 @@ vec3 sampleIrradiance(vec2 uv, vec3 P, vec3 N) {
 }
 
 void main() {
-  vec4 wp = texture(uGWorldPos, vUv);
-  vec4 albedoRough = texture(uGAlbedoRough, vUv);
-  vec3 N = normalize(texture(uGNormalMetal, vUv).xyz);
-  vec3 irradiance = sampleIrradiance(vUv, wp.xyz, N);
-  vec3 emissive = texture(uGEmissive, vUv).rgb;
+  // Sample the padded internal image at the cropped UV (identity when no crop).
+  // Everything below lives in padded space, so one remap here covers all taps.
+  vec2 uv = vUv * uCrop.xy + uCrop.zw;
+  vec4 wp = texture(uGWorldPos, uv);
+  vec4 albedoRough = texture(uGAlbedoRough, uv);
+  vec4 nmFull = texture(uGNormalMetal, uv);
+  vec3 N = normalize(nmFull.xyz);
+  vec3 irradiance = upsampleGuided(uIrradiance, uv, wp.xyz, N);
+  vec3 specular = uSpecEnabled ? upsampleGuided(uSpecular, uv, wp.xyz, N) : vec3(0.0);
+  vec3 emissive = texture(uGEmissive, uv).rgb;
 
   vec3 color;
   if (wp.w < 0.5) {
     // Background: the procedural sky (with sun), else fog colour, else flat.
     if (uSkyEnabled) {
-      color = skyColor(viewRay(vUv), uSunDir, uSunColor, uSkyZenith, uSkyHorizon, uSkyIntensity);
+      color = skyColor(viewRay(uv), uSunDir, uSunColor, uSkyZenith, uSkyHorizon, uSkyIntensity);
     } else {
       color = uFogEnabled ? uFogColor : uBackgroundColor;
     }
   } else {
-    color = albedoRough.rgb * irradiance + emissive;
+    // Diffuse is demodulated (albedo re-applied here); the dielectric specular
+    // highlight is white (F0 ~= 0.04) and is added WITHOUT the albedo multiply.
+    if (nmFull.w >= 4.0) {
+      // Alpha blend (packed word >= 4, opacity = w - 4): the irradiance slot
+      // holds the pane's own demodulated surface light and the SPECULAR slot
+      // carries the traced radiance from BEHIND the pane (see RTLightingPass) —
+      // the only place both quantities exist at final-pixel scale alongside the
+      // pane's albedo, so the opacity blend happens here. With the specular
+      // buffer disabled there is no behind-image; degrade to an opaque pane.
+      float opacity = clamp(nmFull.w - 4.0, 0.0, 1.0);
+      vec3 paneCol = albedoRough.rgb * irradiance + emissive;
+      color = uSpecEnabled ? mix(specular, paneCol, opacity) : paneCol;
+    } else {
+      color = albedoRough.rgb * irradiance + specular + emissive;
+    }
     // Volumetric in-scatter (already radiance, not modulated by albedo). Fog
     // is low-frequency, so a wide 9-tap blur costs nothing visually and eats
     // the single-sample grain — crucial with MOVING lights, where the
@@ -130,15 +157,15 @@ void main() {
     if (uVolEnabled) {
       vec2 o1 = uVolTexelSize * 1.5;
       vec2 o2 = uVolTexelSize * 3.5;
-      vec3 vol = texture(uVolumetric, vUv).rgb * 0.24
-        + texture(uVolumetric, vUv + vec2( o1.x,  o1.y)).rgb * 0.12
-        + texture(uVolumetric, vUv + vec2(-o1.x,  o1.y)).rgb * 0.12
-        + texture(uVolumetric, vUv + vec2( o1.x, -o1.y)).rgb * 0.12
-        + texture(uVolumetric, vUv + vec2(-o1.x, -o1.y)).rgb * 0.12
-        + texture(uVolumetric, vUv + vec2( o2.x,  0.0 )).rgb * 0.07
-        + texture(uVolumetric, vUv + vec2(-o2.x,  0.0 )).rgb * 0.07
-        + texture(uVolumetric, vUv + vec2( 0.0 ,  o2.y)).rgb * 0.07
-        + texture(uVolumetric, vUv + vec2( 0.0 , -o2.y)).rgb * 0.07;
+      vec3 vol = texture(uVolumetric, uv).rgb * 0.24
+        + texture(uVolumetric, uv + vec2( o1.x,  o1.y)).rgb * 0.12
+        + texture(uVolumetric, uv + vec2(-o1.x,  o1.y)).rgb * 0.12
+        + texture(uVolumetric, uv + vec2( o1.x, -o1.y)).rgb * 0.12
+        + texture(uVolumetric, uv + vec2(-o1.x, -o1.y)).rgb * 0.12
+        + texture(uVolumetric, uv + vec2( o2.x,  0.0 )).rgb * 0.07
+        + texture(uVolumetric, uv + vec2(-o2.x,  0.0 )).rgb * 0.07
+        + texture(uVolumetric, uv + vec2( 0.0 ,  o2.y)).rgb * 0.07
+        + texture(uVolumetric, uv + vec2( 0.0 , -o2.y)).rgb * 0.07;
       color += vol;
     }
     if (uFogEnabled) {
@@ -153,6 +180,7 @@ void main() {
   else if (uOutputMode == 3) color = irradiance;
   else if (uOutputMode == 4) color = fract(wp.xyz * 0.1);
   else if (uOutputMode == 5) color = emissive;
+  else if (uOutputMode == 6) color = specular;
   else color = acesFilm(color);
 
   outColor = vec4(pow(color, vec3(1.0 / 2.2)), 1.0);
@@ -168,6 +196,8 @@ export class CompositePass {
       fragmentShader: compositeFrag,
       uniforms: {
         uIrradiance: { value: null },
+        uSpecular: { value: null },
+        uSpecEnabled: { value: false },
         uGAlbedoRough: { value: null },
         uGNormalMetal: { value: null },
         uGWorldPos: { value: null },
@@ -180,6 +210,7 @@ export class CompositePass {
         uUpsample: { value: false },
         uIrrTexelSize: { value: new THREE.Vector2() },
         uCameraPos: { value: new THREE.Vector3() },
+        uCrop: { value: new THREE.Vector4(1, 1, 0, 0) },
         uFogEnabled: { value: false },
         uFogColor: { value: new THREE.Color(0.5, 0.6, 0.7) },
         uFogDensity: { value: 0.05 },
@@ -202,13 +233,20 @@ export class CompositePass {
     this.scene.add(this.quad);
   }
 
-  render(renderer, irradianceTexture, gbuffer, background, target = null) {
+  // `crop` is the overscan central-crop transform (THREE.Vector4 scale.xy /
+  // offset.zw); pass null for no crop (identity) — used when compositing into the
+  // padded offscreen target that TAA crops later.
+  render(renderer, irradianceTexture, gbuffer, background, target = null, specularTexture = null, crop = null) {
     const u = this.material.uniforms;
     u.uIrradiance.value = irradianceTexture;
+    u.uSpecular.value = specularTexture;
+    u.uSpecEnabled.value = specularTexture !== null;
     u.uGAlbedoRough.value = gbuffer.albedoRough;
     u.uGNormalMetal.value = gbuffer.normalMetal;
     u.uGWorldPos.value = gbuffer.worldPos;
     u.uGEmissive.value = gbuffer.emissive;
+    if (crop) u.uCrop.value.copy(crop);
+    else u.uCrop.value.set(1, 1, 0, 0);
     if (background && background.isColor) {
       u.uBackgroundColor.value.copy(background);
     }

package/src/DenoisePass.js

@@ -23,6 +23,7 @@ uniform float uStep;             // à-trous step: 1, 2, 4, ...
 uniform vec3 uCameraPos;
 uniform float uEps;
 uniform float uLumSigma;
+uniform bool uBlendIsSpec;       // this instance filters the specular buffer
 
 float luminance(vec3 c) {
   return dot(c, vec3(0.299, 0.587, 0.114));
@@ -42,8 +43,15 @@ void main() {
   // detail is NOT in the G-buffer guides — filtering would smear them, and
   // their signal is nearly deterministic anyway. Scale the filter down as the
   // surface gets more mirror-like.
+  // Packed word ranges (see GBufferPass): [4,5] alpha blend, [2,4) glass,
+  // [0,1] metal. In the IRRADIANCE buffer a blend surface carries diffuse-lit
+  // direct + GI that DOES need filtering (specAmount 0); in the SPECULAR buffer
+  // (uBlendIsSpec) it carries the traced behind-the-pane image, which must be
+  // spared like a mirror — the pane is flat, so the G-buffer guides would let
+  // the filter smear the see-through content into mush.
   float matW = nm.w;
-  float specAmount = matW >= 2.0 ? clamp(matW - 2.0, 0.0, 1.0) : matW;
+  float specAmount = matW >= 4.0 ? (uBlendIsSpec ? 1.0 : 0.0)
+    : (matW >= 2.0 ? clamp(matW - 2.0, 0.0, 1.0) : matW);
   float specKeep = specAmount * (1.0 - clamp(wp.w - 1.0, 0.0, 1.0));
 
   // Fewer accumulated samples -> noisier pixel -> wider luminance tolerance.
@@ -123,7 +131,12 @@ void main() {
  * pixels get blurred hard, converged pixels stay crisp.
  */
 export class DenoisePass {
-  constructor(width, height) {
+  // `blendIsSpec`: the SPECULAR-buffer instance passes true — for blend pixels
+  // that buffer holds the traced behind-the-pane image, whose detail is not in
+  // the G-buffer guides (the pane itself is flat), so filtering would smear it
+  // into mush. The irradiance instance keeps false: there a blend pixel holds
+  // the pane's own diffuse-lit surface, which does want filtering.
+  constructor(width, height, { blendIsSpec = false } = {}) {
     this.targetA = this._makeTarget(width, height);
     this.targetB = this._makeTarget(width, height);
 
@@ -140,6 +153,7 @@ export class DenoisePass {
         uCameraPos: { value: new THREE.Vector3() },
         uEps: { value: 1e-3 },
         uLumSigma: { value: 0.25 },
+        uBlendIsSpec: { value: blendIsSpec },
       },
       depthTest: false,
       depthWrite: false,