@meimu/mutracer 0.3.0 → 0.3.1

package/docs/technical/display-upscale.md

@@ -0,0 +1,82 @@
+# Display upscale
+
+`createEasuPass` enlarges a reduced-resolution render to the canvas, and with
+`albedoDetail` it restores surface texture detail from full-resolution color AOVs.
+Usage, costs and limits are in [post-processing](../post-processing.md); the AOV
+side is in [surface color AOVs](./aovs.md). This note explains the algorithm. The
+code is `src/renderer/easu.ts` with `wgsl/easu.wgsl.ts` and
+`wgsl/easuDetail.wgsl.ts`.
+
+## Pipeline position
+
+The pass is a display post-process: it runs after composition, tone mapping and
+denoising, on display-encoded RGB. A pass can change the image size through
+`outputSize`, so the upscale is ordinary chain state and needs no special case in
+composition, export or denoising. Beauty, its denoising and the AOVs keep their own
+resolutions; only the displayed image is enlarged.
+
+An input at the output size is copied, and a larger input is area-averaged, so one
+registration serves both a reduced preview and a full-resolution final render.
+
+## EASU
+
+The enlargement is AMD FidelityFX FSR 1 EASU, without RCAS sharpening. It estimates
+a local edge direction and filters along it with a 12-tap lobe. FSR expects inputs
+in [0, 1], so extended-range output normalizes the neighborhood only for the
+direction estimate and filters the original values. EASU cannot invent detail that
+the reduced render does not contain.
+
+## Detail compensation
+
+Texture detail lost at render resolution is still present in the display-resolution
+`diffuseColor` and `specularColor` AOVs. Compensation transfers it:
+
+1. **Low guides.** The full-resolution colors are area-averaged over each render
+   pixel's exact footprint, including noninteger scales, so the low guides match
+   what beauty integrated. No second AOV allocation is needed.
+2. **Local model.** For each render pixel, a guided-filter regression over a 3×3
+   window fits scene-linear radiance as `slope × color + intercept` per channel.
+   Diffuse shading follows color (slope), while highlights and reflections do not
+   (intercept). Flat colors give a slope near zero, so they are left alone.
+3. **Upsampling.** The low guides are enlarged with exactly the same EASU taps and
+   weights as beauty, so beauty and guides share one footprint.
+4. **Ratio.** At each output pixel, the full-resolution color replaces the
+   upsampled one inside the model: `(slope × hi + intercept) / (slope × low +
+   intercept)`, clamped per channel to [0.7, 1.43]. Without a valid model it falls
+   back to the plain color ratio `hi / low`.
+5. **Display transform.** The ratio is scene-linear, but the image is tone-mapped.
+   A lookup table built from the current tone mapping and grading maps displayed
+   RGB back to scene-linear per channel, applies the ratio and maps it forward, so
+   curve shoulders and toes respond as the tone mapper would. Only the change is
+   added to the displayed value, which keeps it exact where the ratio is 1.
+
+Compensation is skipped, leaving EASU alone, where it would be wrong:
+
+- AOV validity or coverage below 0.95 (transmission, cutouts, background,
+  unsupported materials);
+- silhouettes, detected from a change in hit coverage or a break in the planarity
+  of inverse depth (which is linear in screen space on any plane, so sloped
+  surfaces are not silhouettes);
+- color below 10⁻³, treated as black.
+
+Clipped highlights cannot be recovered: the inverse tone mapping has no
+information above the display maximum.
+
+## Retained alternatives
+
+`createEasuPassImpl` keeps three internal variants for comparisons:
+
+- **Plain color ratio.** Scaling all displayed radiance by `hi / low` also scaled
+  highlights and other light that does not follow color, which limited the usable
+  ratio range. The guided model widened it to the current default.
+- **Separate lobes.** Diffuse and specular ratios weighted by lobe shares estimated
+  from the low colors; beauty has no separate lobes to weight them exactly.
+- **Silhouette reconstruction.** Front and back colors from depth-matched
+  low-resolution neighbors, mixed by full-resolution coverage. It sharpens
+  backgrounds but loses detail on thin structures, glass and reflections
+  compared with EASU alone.
+
+Ratios were first applied to encoded display RGB, which over-darkened dark decals;
+applying them in linear and then through the display transform let the clamp range
+grow. The public tuning options were removed; `EASU_DETAIL` holds the shared
+defaults, which native also uses.

package/docs/technical/openpbr.md

@@ -0,0 +1,99 @@
+# OpenPBR implementation
+
+`OpenPBRMaterial` follows the OpenPBR Surface specification with a compact GPU
+BSDF. Parameters, units and user-facing limits are in the
+[materials guide](../materials.md); this note describes how the implementation
+is organized and the rules for changing it.
+
+## Data flow
+
+- **Layout table.** `materialLayoutSchema.ts` lists every material buffer row
+  (one `vec4` each) with its source field and type. The same table generates the
+  TypeScript packing, the WGSL struct (`materialBufferWgsl`) and the GLSL row
+  constants (`materialRowsGlsl`), so the three cannot drift. Reserved rows keep
+  their legacy contents; reusing one is an intentional migration.
+- **Texture slots.** `materialTextureSlots.ts` lists every map with its target
+  parameters, channels, color space, shader define and feature bit. Slot order is
+  the atlas index contract. Public map names live in the scene layer
+  (`materialTextureNames.ts`).
+- **Feature specialization.** Features that a scene does not use, such as
+  anisotropy directions or coat normals, are compiled out by generating different
+  WGSL source, not by patching strings after generation.
+
+## BSDF
+
+The BSDF (`openPbrBsdf.wgsl.ts` and its GLSL counterpart) follows the
+prepare/eval/sample/pdf organization of Adobe's
+[openpbr-bsdf](https://github.com/adobe/openpbr-bsdf) and the
+[OpenPBR viewer](https://github.com/portsmouth/OpenPBR-viewer):
+
+- `openpbr_prepare` resolves the layered material once per path vertex. NEE, BSDF
+  sampling and MIS reuse the result, which made WebGPU samples about 11–15% faster
+  than preparing per evaluation.
+- The lobes are fuzz, coat, metal, dielectric specular, transmission, diffuse and
+  subsurface. Their weights and probabilities are stored as arrays indexed by lobe,
+  rather than one variable per lobe.
+- Metal uses the F82-tint Fresnel; specular anisotropy uses the specification's
+  roughness mapping. The coat roughens the base, changes the IOR ratio below it,
+  absorbs, and darkens through internal reflection (`coatDarkening`, default 1).
+- Fuzz uses an analytic approximation. The specification's LTC fuzz (Zeltner et al.
+  2022) is not implemented.
+
+## Energy compensation
+
+GGX loses energy to single scattering as roughness grows. The renderer uses Adobe's
+tables for opaque dielectric base coupling, ideal-metal multiple scattering and
+solid ideal-dielectric reflection and transmission (`openPbrEnergyLut.ts`). Before
+these tables, rough glass lost 5–36% and rough metal 1.5–20% of its energy in white
+furnace tests.
+
+The tables are stored as 8-bit samples normalized per row, with 16-bit row bounds,
+differences between consecutive rows and exact 16-bit averages. This keeps the
+module about 44 KB gzipped while adding the multiple-scattering tables. On the GPU
+they occupy about 280 KB.
+
+Thin-walled rough transmission has no compensation, as in the reference.
+
+## Import decisions
+
+- Three.js and glTF clearcoat import with `coatDarkening = 0`, because glTF's
+  clearcoat does not darken the base. `userData.mutracerOpenPBR` overrides it.
+- Specification names (`specularRoughnessAnisotropy`, `coatRoughnessAnisotropy`,
+  `subsurfaceScatterAnisotropy`, `geometryOpacity`, `geometryThinWalled`) are the
+  primary names; older names remain deprecated aliases.
+- glTF anisotropy is converted after texture sampling, selected by
+  `specularAnisotropyModel: 'gltf'`.
+
+## Not implemented
+
+- Statistical mixing of two materials.
+- LTC fuzz.
+- Resampled direct lighting on WebGL. It waits for the cause of a small diffuse
+  residual with 8 or 16 WebGPU light candidates; the default of 4 is unaffected.
+
+## Known accuracy limits
+
+- Rough solid glass remains slightly dark in white furnace tests, under 1% without
+  a coat and under 1.5% with one at roughness 0.3. With compensation off it is
+  about 2 percentage points darker than the reference, so the remaining loss is in
+  the transmission integration, not the tables.
+- Strongly tilted coat normals lose about 5% of their energy, because lobes are
+  clipped to the geometric hemisphere. The materials guide documents this.
+- Strong anisotropic metal can retain a small energy error, because the tables use
+  isotropic roughness.
+- A coat with a higher IOR than the base can produce spurious total internal
+  reflection in the thin film, as in the reference.
+
+## Acceptance rules
+
+These maintainer rules apply to material and BSDF changes:
+
+- A white furnace may deviate from 1 by at most 0.5%, and a coated material from
+  its uncoated control by at most 0.5%.
+- Re-encoding the tables may change any material on either backend by at most 0.1%.
+- Measure cold shader compilation with caches invalidated; increases above 10% need
+  a maintainer decision.
+- Sparse pixel differences of at most one half-float step from compiler
+  reassociation are acceptable.
+- Refactors keep default materials (base weight 1, no coat, isotropic, specular
+  color 1) pixel-identical on both backends.

package/docs/technical/pbrt-import.md

@@ -0,0 +1,168 @@
+# PBRT import mapping
+
+This contributor note describes the viewer/tool importer. Usage and limits are
+in [the tool guide](../../tools/pbrt/README.md).
+
+## Coordinates and state
+
+The reference is `mmp/pbrt-v4@b0bdf461ba5dd6504b70ebf0932acc0fe7aa744f`.
+PBRT's camera looks along local +Z. With `M = diag(1,1,-1,1)`, geometry uses
+`M * objectToWorld` and the Three camera uses `M * cameraToWorld * M`.
+The world reflection is baked into geometry so emissive triangles have consistent
+world-space winding and normals. The winding changes when the baked transform
+changes handedness, XOR `ReverseOrientation`; explicit normals only change sign
+for `ReverseOrientation`. Triangle winding is then face-forwarded to shading
+normals, matching PBRT meshes with authored N. Instances retain shared geometry
+and use `M * T * M`.
+Loop shapes refine the control mesh and push vertices to the limit surface;
+area-weighted normals approximate the reference limit-surface tangents.
+A reflection is absorbed into a geometry variant for negative instance transforms.
+
+`LookAt` sets world-to-camera, so its inverse is captured at `Camera`. `WorldBegin`
+resets the object transform. Include filenames and all asset filenames resolve
+against the main scene directory, as `SetSearchDirectory`/`ResolveFilename` do.
+`Import` inherits graphics state but restores it afterward; definitions and scene
+objects remain. Deprecated transform blocks follow PBRT-v4's attribute-block
+rewrite. Only the start transform is retained for animated scenes.
+
+## Camera and microfacets
+
+For aspect `a = width/height`, the vertical field of view is `fov` when `a >= 1`,
+otherwise `2 atan(tan(fov/2)/a)`. Lens conversion uses a 24 mm sensor height:
+`focalLength = .024/(2 tan(verticalFov/2))` metres and
+`fStop = focalLength/(2 lensRadius)` for metre scene units.
+The focus distance stays in scene units. The linear exposure multiplier is
+`ISO/100 * (shutterClose-shutterOpen)`. Film exposuretime is not a PBRT-v4
+parameter and is warned and ignored, as is whitebalance. Unsupported sensors
+produce a separate warning.
+
+The pinned `TrowbridgeReitzDistribution::RoughnessToAlpha` returns `sqrt(r)`.
+Since OpenPBR uses `alpha = roughness²`, the imported roughness is `r^(1/4)` with
+remapping and `sqrt(r)` without it. For anisotropic alphas, the scalar roughness
+is `((alphaU²+alphaV²)/2)^(1/4)` and anisotropy is
+`1-min(alphaU,alphaV)/max(alphaU,alphaV)` (zero for two zero axes). This inverts
+OpenPBR's RMS-preserving formula for both base and coat. The larger alpha is
+assigned to the tangent axis; rotation is π/2 when v is larger, so u stays dpdu.
+Anisotropic meshes also carry UV-derived tangents for the zero-rotation path.
+
+## Colors and light units
+
+RGB inputs are linear sRGB. RGB illumination preserves the RGB multiplier;
+PBRT normalizes the illuminant separately in `SpectrumToPhotometric`. The pinned
+implementation does **not** multiply this integral by 683. The Film's CIE sensor
+integrates the emitted spectrum; this cancels the illuminant normalization for
+white light. Consequently a point light's RGB intensity maps directly to the
+zero-radius SphereLight intensity, and an area light's RGB radiance maps to mesh
+emission. Spot cone angles are half angles and use cosine smoothstep on both sides.
+Distant intensity is irradiance facing the light. Sphere emitters retain meshes:
+MuTracer analytic sphere lights currently do not supply visible primary-ray
+emission, and adding a second emissive sampler would count the source twice.
+
+Power multiplies point intensity by `power/(4π)`. For a spot it multiplies by
+`power/[2π(1-(cos(inner)+cos(outer))/2)]`. Area-light power divides by
+`π * area * (twosided ? 2 : 1)`. Image emission also requires texture-average
+normalization; that case remains an approximation. Constant environment
+illuminance multiplies radiance by `illuminance/π`. Image illuminance follows
+the pinned renderer's `2π/N * sum(Y(pixel)*max(z,0))` normalization in light space.
+
+Named optical data and CIE/D65 tables come from the pinned Apache-2.0 source.
+Conductor normal and edge reflectances integrate Fresnel at cosines 1 and 1/7
+under D65, then convert XYZ to linear sRGB. OpenPBR takes an F82 **tint**,
+so the edge value is divided by `F0+(1-F0)*(6/7)^5` and limited to [0,1]. Glass uses interpolated eta at
+587.56 nm and Abbe `(etaD-1)/(etaF-etaC)`, at 486.13 and 656.27 nm.
+Blackbody emission is normalized to unit luminance before light scaling.
+An RGB renderer and PBRT's spectral renderer can retain material-dependent
+biases; comparisons report them without changing either renderer's algorithms.
+Coated conductor inputs keep `conductor.*` substrate parameters separate from
+`interface.*` coat parameters. Both roughness layers use the same remap rule;
+optical constants are read as curves from named data or SPD files before Fresnel
+integration. Coat IOR and anisotropy use the existing OpenPBR metadata fields.
+
+For coefficient-based subsurface materials, each RGB extinction mean free path is
+`1 / (scale * (sigma_a + sigma_s))`. The largest channel becomes the OpenPBR
+radius and channel ratios become radius scales. Single-scattering albedo
+`sigma_s / (sigma_a + sigma_s)` is converted to the artist-facing subsurface color
+by inverting the existing material packer's mapping. Authored diffuse reflectance
+is already an effective scattering color. These mappings preserve the RGB medium
+coefficients but do not reproduce PBRT's spectral diffusion model.
+Interior homogeneous media encode total extinction, not absorption, in
+transmission color: choose depth `d=1/max(1,max(sigma_t))`, set color
+`exp(-sigma_t*d)` and scatter color `sigma_s/sigma_t`, with scaled coefficients.
+This preserves the existing packer's coefficients without hitting its color floor.
+`MediumInterface` orders inside then outside. The geometric normal points toward
+outside, after ReverseOrientation and handedness. The importer rejects scenes
+with a camera medium. If only an outside medium remains, conversion flips
+winding and normals together and encodes it as the material interior. Two
+media cannot be represented: conversion warns and uses inside only.
+Material variants include both names to avoid sharing different boundaries.
+
+The extra medium-side reversal reciprocates thick dielectric IOR: PBRT's
+DielectricBxDF exchanges eta across its final normal. ReverseOrientation and
+coordinate handedness already affect both normals and do not independently
+reciprocate IOR. ThinDielectricBxDF uses AbsCosTheta and keeps eta unchanged.
+Base specular IOR below one survives Three conversion and material packing;
+both backends use the ratio for Fresnel, total internal reflection and refraction.
+Coat IOR is clamped to at least one and the coat is exterior-only, so reversed
+coats and coat IOR below one receive an ior-orientation warning and are excluded
+from strict comparison. Reciprocal spectral dispersion retains the original
+Abbe number, but a reciprocal Cauchy curve is not itself the same Cauchy fit;
+this receives an ior-dispersion approximation warning and comparison exclusion.
+
+Ordinary PBRT surfaces accept primary back-face hits. One-sided area emission
+uses FrontSide because MuTracer couples primary visibility and emission sidedness;
+its missing back-side surface visibility is warned about.
+
+PBRT image textures evaluate `(s,1-t)`. Decoded images use top-down rows and
+Three textures set `flipY=true`. Infinite lights use the equal-area square map,
+reprojected to world-space latitude/longitude. The direct importer uses nearest
+source lookup to match ImageInfiniteLight. Each target texel averages 4×4
+jittered samples uniform in azimuth and cos(theta), then per-channel spherical
+integrals correct residual quadrature energy error. Source texels use area 4π/N;
+target bands use exact cosine differences. This preserves small bright features'
+total energy while approximating their subpixel distribution. The existing glTF
+metadata adapter retains its previous bilinear reprojection.
+
+Material displacement uses forward UV finite differences with PBRT's `.0005`
+fallback step, including scalar texture scale and UV repeat. The image-row
+v derivative changes sign for `(s,1-t)`. The result is a tangent normal
+`normalize(-dh/du,-dh/dv,1)`, never a geometric height field. This static bake
+assumes unit tangents and omits footprint-dependent steps and curvature terms;
+it is warned and excluded from strict comparison. Only shape displacement uses
+the height-field mapping. In the pinned `interaction.cpp`, NormalMap and BumpMap
+are alternatives (`if/else`): normalmap takes precedence when both exist.
+
+## Comparison and memory
+
+Ordinary byte color maps retain their original data and declared color space;
+unmodified linear HDR maps also share decoded pixel data. Scale graphs carry
+separate multipliers. Scalar and transformed maps retain
+floating-point values. Rectangular/non-power-of-two height fields are resampled
+to the existing displacement layout, with a warning.
+
+The comparison sets PBRT's pixel filter to box with radius 0.5 to match MuTracer's
+uniform pixel jitter. It overrides spp and output resolution, removes Film crop
+windows and pixel bounds, preserves maxdepth,
+sets an opaque black background when no environment exists, removes Film sensor exposure from the reference HDR and never tone maps numerical
+inputs. AOV material IDs identify approximate surface regions. This primary-hit
+mask does not isolate indirect paths that touch approximate materials. PBRT uses
+seeds 0/1; MuTracer uses disjoint sample blocks starting at 0/N with the same Sobol
+scramble. Their difference gives a diagnostic noise estimate, not independent
+Monte Carlo replicas or statistical proof of equivalence.
+Whole-frame RMSE retains every comparable pixel and its noise margin. Regional
+material/tile tests exclude discontinuities in object, instance or material IDs,
+dilated by one pixel. Their statistic is absolute channel mean bias / standard
+error, with threshold 6. Standard error is sqrt(sum of per-pixel replica-difference
+variances) / pixel count; squaring a region-sum difference instead gives an
+unstable single observation. Whole-frame and regional statuses are separate.
+Each MuTracer run uses a fresh Chrome process to avoid retaining both scenes' caches
+and allocations during memory measurement.
+
+Text and gzip Includes are decoded by statements to avoid the single-string size
+limit. The viewer parses them and PLY data in a Worker. Inline P/N/UV/index
+arrays become
+transferable typed views before leaving the Worker; statement locations share
+the same parameter objects. Binary assets are prefetched six at a time before
+conversion; progress sums completed and in-flight bytes. The download preflight
+uses unique encoded input sizes and an 8x expansion estimate against an 8 GiB
+working budget. This estimate is deliberately conservative and cannot predict
+total process/GPU memory or prevent every browser allocation failure.

package/docs/technical/tiling.md

@@ -0,0 +1,74 @@
+# Tile scheduling
+
+A full-frame path-tracing sample can take longer than a display frame and, on slow
+scenes, long enough to stall the browser or trigger a GPU timeout. Renders therefore
+trace each sample as a grid of tiles, sized so that one tile fits `timeBudgetMs`.
+Usage and the related options are in
+[sample batching](../progressive-rendering.md#sample-batching); this note explains how
+the tile grid is chosen. The code is `src/renderer/TileRender.ts`.
+
+## Two predictors
+
+- **WebGPU with timestamp queries** uses `makeTileRenderWithPredict`, which reads
+  the GPU time of each submitted grid.
+- **WebGL 2, and WebGPU without timestamp queries,** use `makeTileRender`, adapted
+  from ray-tracing-renderer. It adjusts a pixels-per-tile count from wall-clock
+  feedback, never below 8192 pixels. WebGL timer queries are not reliable enough to
+  replace it; see [WebGL 2 backend](./webgl.md).
+
+The rest of this note describes the WebGPU predictor.
+
+## Prediction
+
+The first sample uses a probe tile shaped like the frame, large enough that dispatch
+overhead does not dominate it. Each later measurement scales the tile area by the
+ratio of the budget to the measured tile time, limited to 4× (2× per dimension) per
+update so the grid converges without jumping from a small probe to a blocking
+full-frame tile. Tiles are never narrower than one compute workgroup (8 pixels):
+a smaller dispatch occupies the same workgroups and repeats their fixed cost.
+
+The grid is interleaved, so each sample still covers every pixel once. When the
+predicted tile exceeds the frame, several samples are traced per frame instead.
+
+## Why area-proportional prediction is not enough
+
+Tile time is not proportional to tile area. A tile pays a fixed cost for dispatch
+and for its longest path, and small frames leave most of the GPU idle. On a heavy
+scene at a small resolution, 16 tiles can each take more than half the time of the
+whole frame. An area-proportional predictor keeps subdividing toward the budget and
+multiplies the cost of every sample.
+
+Two rules handle this:
+
+- **Refinement check.** When the predictor subdivides, it compares the next
+  measurement with the grid that motivated the change. If the new tile time
+  improves by less than half of the area ratio, and still misses the budget by more
+  than 10%, the predictor returns to the previous grid and uses its tile size as a
+  floor until prediction is invalidated.
+- **Unattainable budgets.** From two measurements at sufficiently different tile
+  areas, the predictor fits tile time as `fixed + perPixel × area`. If the fixed
+  part alone exceeds the budget by more than 10%, no grid can meet it. The predictor then picks the
+  fewest tiles that keep a tile below 350 ms (over 5× below a 2 s GPU timeout) and,
+  where possible, keep the repeated fixed cost below one fifth of the sample. This
+  decision is retained until prediction is invalidated, because refitting on its
+  own grids lets path-cost noise alternate between tile counts.
+
+`maxTiles` still caps the grid in both cases. A long tile is a deliberate trade:
+fewer updates while interacting, in exchange for not multiplying the cost of
+every sample. The guide documents the resulting pauses.
+
+## Measurements
+
+Several samples may be submitted before their timestamps resolve. Each measurement
+is matched to the grid it was submitted with and consumed once, so stale results
+cannot shrink tiles repeatedly. Scene, view and setting changes invalidate the
+prediction (`needsUpdatePredicting`). Photon and light-tracing batches run with the
+first and last tile and are timed separately.
+
+## Changing this code
+
+- Scheduling changes must update `tests/fixtures/display-schedule.json` and the
+  schedule tests, and pass `npm run test:parity`; see `AGENTS.md`.
+- Judge changes by total sample time and by tile time, at both small and normal
+  resolutions on a heavy scene. Fixed-seed HDR must stay identical, because tiling
+  changes only the order of work.

package/docs/technical/webgl.md

@@ -0,0 +1,53 @@
+# WebGL 2 backend
+
+The WebGL 2 backend runs the same path tracer as fragment shaders. It is the
+fallback where WebGPU is unavailable, so it favors working everywhere over speed.
+This note lists the constraints that shape it and the open issues known to
+contributors. Feature differences visible to users are documented with each
+feature.
+
+## Constraints
+
+- **Texture units.** WebGL 2 guarantees 16 fragment texture units. Per-vertex
+  attributes (normals, UVs, tangents, colors, material indices) share one
+  interleaved RGBA32F texture, positions keep their own for triangle tests, and
+  instance records follow the BVH in its texture. `webglSamplerBudget.test.ts`
+  keeps every trace pass at or below 14 referenced samplers, leaving two for new
+  features. Add a sampler only after checking that budget.
+- **Uniforms.** Large scenes can exceed `MAX_FRAGMENT_UNIFORM_VECTORS` (1024 on
+  common devices) and fail to render. The renderer does not yet fail soft there.
+- **Path length.** `bounces` and path events stop at 20 on WebGL, and Intel Macs use
+  a shorter event limit. WebGPU allows 50.
+- **Compilation.** ANGLE defers native compilation, so a first draw can block for
+  seconds, much longer than WebGPU. Trace programs request parallel compilation
+  and are polled before use. Per-program timings do not measure that program's
+  compile time.
+- **Timing.** Timer queries can report totals longer than the wall-clock time and
+  cannot drive scheduling or performance claims. Tiles are sized from wall-clock
+  feedback; see [tile scheduling](./tiling.md). Measure WebGL performance by wall
+  time until the HDR readback completes.
+- **WebGPU-only features.** Caustic estimators, display post-processing,
+  display-resolution AOVs and custom denoisers fail soft on WebGL. Caustic paths
+  fall back to path tracing, so the expected image is unchanged.
+
+## Open issues
+
+- **Background in some scenes.** On at least one scene, WebGL terminates many
+  paths at depth 0 or on a miss where WebGPU continues, and part of the background
+  renders black. Primary-miss and environment behavior should be aligned before
+  WebGL is used as a cross-backend reference for such scenes.
+- **Long single draws.** With dispersion, one fragment invocation traces all three
+  channel suffixes ([shared prefixes](./continuous-spectrum.md#shared-prefixes)).
+  Large renders with a single tile have lost the context, likely from a GPU
+  timeout. Options are to size tiles for three times the work or to fall back to
+  three draws on large images.
+- **Context loss.** Some driver failures lose the context and later reads return
+  zeros. Treat an all-black WebGL capture as a failed run, not a result.
+
+## Changing this code
+
+- Implement material, light and sampling changes in both WGSL and GLSL; see
+  `AGENTS.md`.
+- Run GPU comparisons headless, one context at a time. When a WebGL capture fails
+  with context loss, rerun it before drawing conclusions, and do not compare its
+  output.

package/docs/viewer.md

@@ -34,7 +34,17 @@ and frames the model.
 Reloading the current model restores your saved camera selection.
 
 Picking an object in the viewport reveals it in the scene tree and scrolls it
-into view. Material rows start collapsed; expand a mesh to see its materials.
+into view. Selection follows the rendered geometry, including
+[displacement on WebGPU](materials.md#displacement) and alpha-cutout holes;
+it becomes available once the scene is ready to render.
+Material rows start collapsed; expand a mesh to see its materials.
+
+The viewer caches prepared BVHs to speed up reopening unchanged models.
+Models still need to be loaded and decoded. The cache has a 4 GiB browser-storage
+budget; entries are removed as space is needed. Cached data is reused only when
+geometry, displacement and BVH settings match. Loading still works if storage
+is unavailable or full.
+Clear the site's browser storage to remove the cache.
 
 ## Sharing viewer settings
 

package/lib/Display.d.ts

@@ -36,11 +36,25 @@ export interface PostProcessContext {
     /** Engine device; may change after recovery. */ device: GPUDevice;
     /** Record commands here; the library finishes and submits it. */ encoder: GPUCommandEncoder;
     /** Read-only composed display image, top row first; no additional color conversion. */ input: GPUTexture;
-    /** Fully write this image. Same format and dimensions as input; supports render, storage and copy writes. */ output: GPUTexture;
-    /** Actual render width. */ width: number;
-    /** Actual render height. */ height: number;
+    /** Fully write this image. Same format as input; dimensions follow outputSize; supports render, storage and copy writes. */ output: GPUTexture;
+    /** Actual render width; pass dimensions are input.width and output.width. */ width: number;
+    /** Actual render height; pass dimensions are input.height and output.height. */ height: number;
     /** Selected complete render, including a selected fallback. */ render: Render;
 }
+/** Optional dimensions for a display pass. */
+export interface PostProcessOptions {
+    /** Output dimensions per invocation, bounded by maxTextureDimension2D. Default undefined preserves input size. Display is the current canvas size, including during export. */
+    outputSize?: (input: {
+        width: number;
+        height: number;
+    }, display: {
+        width: number;
+        height: number;
+    }) => {
+        width: number;
+        height: number;
+    };
+}
 /** Synchronous display pass. Images and encoder are borrowed only during the call; do not retain or destroy them. */
 export type PostProcess = (context: PostProcessContext) => void;
 /** Canvas presentation and shared display settings; obtained from engine.display. */
@@ -73,11 +87,11 @@ export default class Display {
     private readonly _postProcesses;
     private _warnedPostProcess;
     /** Registers a display pass in order and returns an idempotent removal function. Default no passes. WebGPU only; WebGL skips passes with one warning. Runs after composition on every present/toBlob, without tracing or invalidating denoising. A thrown error discards the whole chain, presents the original image and emits engine error. */
-    addPostProcess(pass: PostProcess): () => void;
+    addPostProcess(pass: PostProcess, options?: PostProcessOptions): () => void;
     private warnPostProcess;
     private compose;
     /** Presents a complete image or fallback. Keeps fallback visible until the first intermediate filter finishes. Does not trace. */
     present(render: Render): Render | undefined;
-    /** Encodes this render at its actual dimensions using these settings; leaves the display canvas unchanged. */
+    /** Encodes the display chain at its final dimensions (default render dimensions), cropping fixed renders before passes using these settings; leaves the display canvas unchanged. */
     toBlob(render: Render, options?: BlobOptions): Promise<Blob>;
 }

package/lib/Display.js

@@ -68,8 +68,8 @@ export default class Display {
     _postProcesses = [];
     _warnedPostProcess = false;
     /** Registers a display pass in order and returns an idempotent removal function. Default no passes. WebGPU only; WebGL skips passes with one warning. Runs after composition on every present/toBlob, without tracing or invalidating denoising. A thrown error discards the whole chain, presents the original image and emits engine error. */
-    addPostProcess(pass) {
-        const entry = { pass };
+    addPostProcess(pass, options = {}) {
+        const entry = { pass, options: { ...options } };
         this._postProcesses.push(entry);
         if (this.engine.backend === 'webgl')
             this.warnPostProcess();
@@ -82,7 +82,7 @@ export default class Display {
             console.warn('Display post-processing requires WebGPU; passes are ignored on WebGL.');
         }
     }
-    compose(render) {
+    compose(render, exporting = false) {
         if (render._engine !== this.engine)
             throw new Error('Render belongs to another engine.');
         const target = render._output;
@@ -100,9 +100,11 @@ export default class Display {
         if (this._postProcesses.length && this.engine.backend === 'webgl')
             this.warnPostProcess();
         try {
-            target.applyPostProcesses?.(this._postProcesses.map(entry => entry.pass), render);
+            target.applyPostProcesses?.(this._postProcesses.map(entry => entry.pass), render, this._postProcesses.map(entry => entry.options), exporting ? render._exportCrop : undefined);
         }
         catch (error) {
+            // Preserve the pre-chain export crop even when a callback or size fails.
+            target.applyPostProcesses?.([], render, [], exporting ? render._exportCrop : undefined);
             this.engine._notifyError(error);
         }
         return target;
@@ -122,12 +124,13 @@ export default class Display {
         this.engine._present(target);
         return selected;
     }
-    /** Encodes this render at its actual dimensions using these settings; leaves the display canvas unchanged. */
+    /** Encodes the display chain at its final dimensions (default render dimensions), cropping fixed renders before passes using these settings; leaves the display canvas unchanged. */
     async toBlob(render, options = {}) {
-        const target = this.compose(render);
+        const target = this.compose(render, true);
         if (!target)
             throw new Error('Render has no complete image.');
-        const image = render._cropOutput(await target.readPresentation());
+        const presentation = await target.readPresentation();
+        const image = this.engine.backend === 'webgpu' ? presentation : render._cropOutput(presentation);
         const canvas = createCanvas(image.width, image.height, 'convertToBlob' in this.canvas);
         const context = canvas.getContext('2d');
         if (!context)