@tinypoly/gpu-renderer 0.0.0-stage → 0.0.0

package/ARCHITECTURE.md

@@ -0,0 +1,334 @@
+# Architecture
+
+How `@tinypoly/gpu-renderer` works inside, and the decisions behind it. For installation and usage, see the
+[README](README.md).
+
+The renderer takes a serialized Three.js scene, uploads geometry, a BVH, materials, textures and lights to the GPU, and
+runs a path tracing compute shader that accumulates radiance into a float buffer. A small render pipeline presents that
+buffer, dividing by the sample count and applying exposure, tone mapping, vignette and grain. There is no worker pool and
+no `SharedArrayBuffer`: the state lives on the device.
+
+## Relationship with @tinypoly/cpu-renderer
+
+The two renderers share a contract instead of a code base. Everything that reads Three.js or defines the shape of the
+data comes from the CPU renderer, through a single module (`src/upstream.ts`), so a version bump has one place to audit:
+
+- `serializeScene`, `serializeCamera`, `sceneSignature` and the `Serialized*` types: the scene snapshot.
+- `USER_DATA_KEY` and the `userData.cpuRenderer` extensions. The key stays `cpuRenderer` in both renderers: it is
+  historical, and renaming it would break scenes that already carry it.
+- `RenderSettings`, `FrameSettings` and the tone mapping transforms.
+- The GPGPU pipeline descriptors a module publishes.
+
+What is rewritten in WGSL: material evaluation, the integrator, texture sampling and the environment. The CPU sources
+stay the algorithmic reference, line by line.
+
+## Modules
+
+- `device.ts`: adapter and device acquisition, requested limits, loss handling.
+- `camera.ts`: the camera's matrices. Every ray goes through the inverse of the camera's own projection.
+- `geometry.ts`, `bvh.ts`: flat triangle and attribute buffers, and the BVH built straight into 32 byte nodes. Packing
+  also builds what Three draws in screen space (points, lines, sprites, dashes) as triangles facing the camera, applies
+  displacement maps, and runs vertex shaders.
+- `structLayout.ts`, `frameLayout.ts`, `materialLayout.ts`: one description of each struct, from which both the WGSL
+  declaration and the TypeScript writer are generated, so their word offsets cannot drift apart.
+- `texturePack.ts`, `lights.ts`: the remaining storage buffer layouts. `lights.ts` holds the emissive triangles and
+  Three's analytic lights in one cumulative distribution, the triangles first and in triangle order, so the same buffer
+  answers both questions the integrator asks: pick a light by probability, and, given a triangle a bounce ray hit, how
+  likely direct sampling was to have found it.
+- `environment.ts`: the surrounding image and the distribution that lets a shadow ray aim at its bright parts.
+- `shaderProgram.ts`, `sceneAssets.ts`: the GLSL translation, the procedural sky and the compute bakes (see below).
+- `planarCapture.ts`, `volumetric.ts`: the CPU renderer's planar captures and volumetric lights.
+- `sceneUpload.ts`: the uploads, and the joining of buffers described below.
+- `accumulator.ts`, `pathTracePass.ts`, `presentPass.ts`, `dispatchScheduler.ts`: the frame loop.
+- `wgsl/*.wgsl.ts`: the shader source.
+
+## Decisions worth not relitigating
+
+**A megakernel, not a wavefront.** One compute invocation per pixel, the bounce loop inside the kernel, `8 x 8`
+workgroups so neighbouring pixels stay coherent. A wavefront pays off with many distinct materials and high register
+pressure; here there is a single evaluator behind flags, and the queue traffic (a ray state per pixel per bounce) costs
+most on exactly the weak hardware this has to serve. The WGSL is split into pure functions so that moving to a wavefront
+later rewrites the scheduler, not the BRDFs. The signal to revisit: a kernel past roughly 700 lines, or throughput
+falling off a cliff when a lobe is added.
+
+**Arrays of the same kind share a binding.** A WebGPU device only has to offer eight storage buffers per shader stage,
+and the kernel wants eleven arrays. Normals and the UV sets go in one buffer, the per-triangle material indices and the
+hierarchy's triangle order in another, and the texture table sits in front of the texels it points at, with the uniform
+saying where each second half begins. Positions, materials, nodes, lights and the accumulation buffer keep their own.
+Merging costs a scene some headroom against `maxStorageBufferBindingSize`, which is why positions stay separate: they are
+the largest array and the hottest one.
+
+**Textures in a storage buffer, sampled by hand.** Core WebGPU has no binding arrays, and `texture_2d_array` demands one
+size and one format for every layer, which the scene snapshot does not provide (arbitrary sizes, per texture wrap and UV
+matrix, authored mipmaps). Compute shaders have no implicit derivatives either, so the level of detail is computed by
+hand regardless and half of a hardware sampler's advantage disappears. A fast path can add `texture_2d_array` later, for
+scenes where every texture happens to be uniform.
+
+**WGSL lives in `src/wgsl/*.wgsl.ts`, as template literals.** The build is plain `tsc`, and `tsc` does not copy `.wgsl`
+files into `dist`. The Tinypoly rule of keeping shader source in its own file exists because of a build time obfuscation
+plugin that does not apply to a published library.
+
+**The hierarchy is built here, not imported.** The CPU renderer has a binned SAH builder, but it stores bounds as
+doubles for a scalar traversal, and re-packing that tree would still leave every minimum needing to be rounded down and
+every maximum up before a float32 shader may use it. Building from the same `Float32Array` the shader reads makes every
+corner exactly representable and the widening unnecessary. Revisit if the two builders start to drift.
+
+**Shaders: vertex stages interpreted, fragment stages translated by naga.** A Three shader is two different problems.
+
+- **A vertex shader decides where the triangles are**, so it has to run before the hierarchy is built, which happens on
+  the CPU. It runs there, once per vertex, on the CPU renderer's own GLSL interpreter (`CpuShader`), with the inputs the
+  CPU renderer gives it. Its `gl_Position` is taken back to world space through the camera, which is how displacement,
+  billboards and `gl_PointSize` come out exactly as drawn; its varyings are stored per triangle corner.
+- **A fragment shader runs per sample**, inside the kernel. `naga-wasm` (naga 30) translates it to WGSL after a rewrite
+  that turns a program into functions: every uniform, varying and built-in becomes a module scope global the kernel
+  fills in, every texture call becomes a function the kernel provides (reading the texture table by hand), and `discard`
+  sets a flag. Uniforms are loaded from the texture buffer by code generated from the types naga wrote, so arrays,
+  structs and matrices need no table of their own. What comes back is renamed into the kernel's namespace and called
+  through a `switch` on the material's program. naga is loaded only for a scene that has shaders.
+- **Derivatives are real.** A shader that takes `dFdx`, `dFdy` or `fwidth` runs three times per hit, for the pixel to the
+  right, the pixel above and the pixel itself; each call site stores what the neighbours computed there, and the third run
+  reads the difference. The neighbours' varyings come from the barycentrics of their camera rays on the hit triangle's
+  plane. It is a quad's work in sequence, correct wherever the three runs take the same path through the shader, which is
+  the assumption a GPU's own quads make.
+- **An `onBeforeCompile` hook** runs on the material's values before lighting (`diffuseColor`, `normal` in view space,
+  `roughnessFactor`, `metalnessFactor`, `totalEmissiveRadiance`), which is the part of Three's shader the CPU renderer's
+  snapshot captures. The path tracer then lights the result itself.
+
+The CPU renderer's tree-walking front end, considered in an earlier version of this decision, is not used: naga parses,
+type checks and restructures, which was the bulk of the work. A shader that naga refuses (a `switch` that falls through
+was the one known case, and is now rewritten) is reported with `console.warn` and its material renders as its colour,
+rather than failing the frame.
+
+**Adaptive sampling spends a fixed budget where the noise is.** A frame has the work of `settings.samples` passes over
+the whole image to spend. Every pixel keeps the sum of its squared luminance beside its radiance, which gives its
+variance; after 32 paths, a pixel whose standard error (over the square root of its luminance, roughly how visible the
+error is once encoded) is under half an 8 bit step stops, provided its 3 x 3 neighbourhood has too. The neighbourhood is
+what keeps a rare bright path honest: a pixel judged alone would stop where it happened not to have seen one yet, and
+that area would converge too dark. Each traced row sets a flag, read back after the pass, and the next pass dispatches
+only the rows that still have work, until the budget is spent or a pixel reaches four times its share. Stopping on the
+samples themselves is a slight bias, the usual price of adaptive sampling.
+
+**The denoiser is the spatial filter of SVGF, with diffuse and specular light apart.** The temporal half of SVGF, and of
+NVIDIA's NRD, has nothing to do here: the image does not move while it converges, and the accumulation buffer already
+is a perfect history. What carries over from NRD's RELAX and REBLUR is splitting the signal.
+
+- **Two signals.** Every path is split at its first scatter: what the diffuse lobe carried on (and what the camera sees
+  directly) is diffuse, what a specular lobe, the clearcoat or transmission carried on is specular. Direct light at that
+  vertex is split by evaluating the diffuse term alone. Each pixel keeps the diffuse radiance beside the total, and the
+  squared luminance of each signal, which gives each its own variance.
+- **Guides**, taken at the first surface the camera ray stops at: the diffuse albedo, the specular one (the GGX lobe's
+  directional albedo from Karis' fit, with the clearcoat, white through glass), the normal, the distance, the roughness,
+  and how far the specular continuation went before it hit something.
+- **Filtering.** Each signal is divided by its albedo, so the filter sees light and never blurs a texture. A pixel
+  brighter than all eight neighbours is clamped to the brightest of them (anti-firefly). Then up to five passes of a
+  5 x 5 a-trous wavelet, taps 1 to 16 pixels apart. Diffuse taps are weighed by the agreement of normals and depths and
+  by their luminance against the pixel's own variance, prefiltered over 3 x 3. Specular taps also by roughness, by
+  normals more sharply the smoother the surface, and within the footprint the lobe leaves on the screen: the lobe's angle
+  (alpha) times the distance to what it reflects, over that distance plus the surface's, in pixels. A mirror is left
+  alone, a rough reflection of something far is smoothed widely. The variance is filtered along, so each pass trusts the
+  last.
+- **Mixing back.** Weights are normalized, so a flat area keeps its mean exactly. Each signal is then mixed with what
+  was traced by how noisy it still is, by the error adaptive sampling measures, from where it counts as converged to four
+  times that: a converged pixel keeps exactly what was traced. `DenoiserSettings` scales the mix, the reach, the
+  luminance tolerance and the anti-firefly; changing it filters the finished accumulation again, without tracing.
+
+It runs in its own pipelines, outside the kernel's eight storage buffers, on the canvas at the end of every pass and on
+the image `render()` resolves with. The accumulation holds six vec4 per pixel for all of this, 96 bytes, and the filter
+five more buffers of 16: a 2000 x 1350 image takes some 460 MB on the device.
+
+## Compatibility
+
+This is a path tracer, **not Three.js/WebGL conformance, and not a match for the CPU renderer's image**. What follows is
+what the renderer reads today. Anything absent is ignored in silence unless it is marked as an error, so a host reading
+this table is the only way to know.
+
+### Geometry and cameras
+
+| Works | Notes |
+| --- | --- |
+| Triangle meshes, transformed to world space | Every triangle carries its own three vertices |
+| `InstancedMesh`, with `instanceColor` | The scene snapshot expands it to one mesh per instance |
+| `SkinnedMesh`, morph targets | The snapshot bakes the deformed positions |
+| Per-group materials, indexed or not, `drawRange` | |
+| Vertex normals, or a face normal when absent; `flatShading` | |
+| Vertex colours (`vertexColors`), three or four components | |
+| Two UV sets, `uv` and `uv1` | A texture asking for a higher channel falls back to `uv1` |
+| A mirroring transform | The winding is turned around, as Three flips its front face |
+| `Points` | A square of `size` pixels facing the camera, with `sizeAttenuation`, as `gl_PointCoord` maps it |
+| `Line`, `LineSegments`, `LineLoop`, `LineDashedMaterial` | One pixel wide, as WebGL draws every line; dashes are cut into pieces |
+| `Sprite` | Laid out around its `center`, with `rotation` and `sizeAttenuation` |
+| Any camera with a projection matrix | Perspective, orthographic, zoom, `setViewOffset`, film offset |
+
+Camera rays start on the near plane and stop at the far plane, which clip a surface as Three clips a fragment.
+Points, lines, sprites and vertex shaders face or depend on the camera, so a scene with them is packed again whenever the
+camera or the image size changes.
+
+`material.side` culls the faces Three culls, for the camera's own rays only: a mesh still casts shadows and holds light
+in from both sides, which is what a closed room drawn `BackSide` for a cutaway view needs. Per-mesh `castShadow` and
+`receiveShadow` are ignored: a traced shadow comes from the geometry that casts it.
+
+### Materials
+
+| Type | What happens |
+| --- | --- |
+| `MeshStandardMaterial` | Three r185's direct lighting: Lambert diffuse, GGX with its multiple scattering term |
+| `MeshPhysicalMaterial` | Adds transmission, dispersion, clearcoat, sheen, iridescence, anisotropy, specular colour and intensity |
+| `MeshLambertMaterial` | Lambert diffuse |
+| `MeshPhongMaterial` | Lambert diffuse and Three's Blinn-Phong highlight, sampled by its own lobe |
+| `MeshToonMaterial` | Three's ramp, from `gradientMap` or its two steps, in place of the cosine |
+| `MeshBasicMaterial`, `PointsMaterial`, `LineBasicMaterial`, `SpriteMaterial` | Unlit, which in a path tracer means the surface emits its own colour |
+| `MeshNormalMaterial`, `MeshDepthMaterial`, `MeshDistanceMaterial`, `MeshMatcapMaterial` | Unlit, computed as Three's shaders compute them |
+| `ShadowMaterial` | A shadow catcher: its colour where a shadow casting light is blocked, nothing elsewhere |
+| `ShaderMaterial`, `RawShaderMaterial` | The fragment shader runs, translated; its output is the colour the surface shows, unlit |
+| A built-in material patched with `onBeforeCompile` | The hooks run on the material's values before lighting |
+
+Maps read: `map`, `alphaMap`, `emissiveMap`, `roughnessMap`, `metalnessMap`, `normalMap` (tangent or object space),
+`bumpMap`, `displacementMap`, `lightMap`, `envMap`, `specularMap`, `specularColorMap`, `specularIntensityMap`,
+`transmissionMap`, `thicknessMap`, `clearcoatMap`, `clearcoatRoughnessMap`, `clearcoatNormalMap`, `sheenColorMap`,
+`sheenRoughnessMap`, `iridescenceMap`, `iridescenceThicknessMap`, `anisotropyMap`, `gradientMap`, `matcap`. Each one reads
+the channel Three's chunks read and honours the texture's own UV transform, wrap modes, filter and colour space.
+
+Coverage follows Three's chunks: `alphaTest` cuts, `alphaHash` keeps the share, and only a `transparent` material with
+normal blending lets the rest through; an opaque one is opaque whatever its opacity. Additive blending adds the surface
+to what is behind it, multiply and subtractive filter it. Material clipping planes (with `clipIntersection`),
+`wireframe` (one pixel wide edges) and `visible`/`colorWrite` are honoured.
+
+A **material's own `envMap`** is what the paths leaving it see instead of the scene's surroundings; on Basic, Lambert
+and Phong it blends over the colour through `combine` and `reflectivity`, mirrored or bent by `refractionRatio`. A
+**light map** adds its light to what the camera sees of the surface and is not traced further: the path traces that light
+itself, and counting the bake again would double it.
+
+A shader's output is taken as linear light, as in the CPU renderer: the tone mapping and colour space chunks are emptied,
+because the renderer applies both to the image. Its fog chunk is emptied too, because the integrator lays Three's fog over
+every material that accepts it. A fragment shader runs only where a path hits the surface, so a shader whose output
+depends on `gl_FragCoord` sees the camera's projection of the hit, which off screen can be anywhere.
+
+**Transmission** follows Three's split: `transmission`, times its map and less metalness, is the share of the diffuse
+layer that lets light through, and the specular lobe stays on top. A path picks that share by chance and then meets a
+dielectric of index `ior`, reflecting by the exact Fresnel term and refracting the rest, rough or smooth. The base colour
+tints light once, on the way in. `thickness` decides what the surface is:
+
+- **Zero (Three's default) is a thin wall**, a window: light crosses it without bending, and so do shadow rays, tinted
+  by the same amount. A room lit by the sun through its glazing works as it should.
+- **Above zero the mesh bounds a volume** that refracts, and `attenuationColor` over `attenuationDistance` absorbs along
+  the path inside it (Beer-Lambert). The mesh has to be closed with outward normals. A shadow ray cannot bend, so a volume
+  blocks it: **a glass ball under a directional, point or spot light casts a solid shadow**, with no caustic, because
+  those lights occupy no area a refracted path could find. Under an area light, emissive geometry or the environment
+  the caustic appears, slowly. **Dispersion** splits a path into one colour the first time it enters such a volume, which
+  then refracts with that colour's index, spread as Three spreads it.
+
+A refraction does not spend a bounce; a reflection inside the glass does.
+
+`aoMap` is ignored deliberately, not by omission. It bakes the occlusion this renderer traces, and applying both would
+darken the same shadow twice.
+
+Only the top mip level of a texture is read. A rasterizer needs the lower levels so minified detail does not alias; this
+renderer already draws many jittered samples through every pixel, which averages that detail properly. Levels would buy
+memory locality, not correctness. A bump map's slope is taken over one texel, as in the CPU renderer, where Three takes
+it over one pixel.
+
+### Lights
+
+| Works | Notes |
+| --- | --- |
+| `DirectionalLight` | Aimed at directly, with `shadows.softness` as its angular diameter |
+| `PointLight` | Three's own distance falloff and cutoff |
+| `SpotLight` | Cone and penumbra as Three computes them, and its projected `map` |
+| `RectAreaLight` | A real area light, sampled over its rectangle, so its penumbra is traced rather than approximated |
+| `AmbientLight`, `HemisphereLight` | See the divergence below |
+| Emissive geometry | Any triangle whose material emits, weighted by area and power |
+
+`light.castShadow` gates the occlusion ray, as does `settings.shadows.enabled`. A `RectAreaLight` always occludes,
+because Three has no shadow switch for one and an area light that cast none would look broken once traced. A toon
+surface lit from behind is not shadowed by its own mesh, as Three's shadow map leaves it.
+
+### The environment and the background
+
+A vertical gradient, an equirectangular `.hdr` image, or the scene's procedural sky (`userData.cpuRenderer.sky`), with a
+luminance distribution built over the image so a shadow ray can aim at a sun. `intensity` and `rotation` apply to the
+gradient and the image. A procedural sky is baked by the CPU renderer's interpreter, lights with its own `intensity`,
+ignores the rotation so its sun stays with its light, and paints the background without its intensity, with its
+`foregroundShader` evaluated per pixel over it.
+
+`settings.background` decides what the camera sees where nothing is in the way: the environment, a colour, or nothing,
+in which case the image's alpha is the coverage of every pixel and the canvas is configured premultiplied. The
+background shows through transmission, as Three's transmission shows it, and not in a reflection, which shows the
+environment.
+
+`scene.fog` (`Fog` and `FogExp2`) is laid over what the camera sees through the first surface, at that surface's view
+depth, for every material that accepts fog, and the background stays clear, as in Three. `settings.fog`, when enabled,
+covers every surface instead.
+
+### Settings
+
+Read: `samples`, `renderScale`, `exposure`, `toneMapping`, `vignette`, `grain`, `background`, `fog`, `depthOfField`
+(the CPU renderer's 35 mm lens, `focusDistance`, `aperture` as an f-number, `blades` for polygonal bokeh),
+`globalIllumination.bounces`, `globalIllumination.clamp`, `shadows.enabled`, `shadows.softness`.
+
+Ignored: `tileSize`, `ambientOcclusion`, and everything else under `globalIllumination` (`enabled`, `samples`,
+`intensity`, `cache`, `cacheSpacing`, `denoise`).
+
+### The CPU renderer's extensions, and the rest
+
+- **Light probes.** A `LightProbe`'s harmonics are radiance in Three's SH3 basis; they join the ambient surrounding,
+  which delivers exactly the irradiance Three's shader convolves from them. The snapshot does not carry them, so they are
+  read from the live scene `setScene` receives: a scene handed over already serialized has none.
+- **Volumetric lights** (`userData.cpuRenderer.volumetric` on a point or spot light) are marched along every camera ray
+  as the CPU renderer's `volumetricLight.js` marches them, up to the first surface, and added over the image the same way.
+- **Planar captures** (`planarCapture`) are rendered by this renderer, path traced from the CPU renderer's mirrored and
+  real cameras with its clip planes, into the textures the material samples. They follow the camera, so a scene with one
+  is captured again whenever it moves.
+- **Compute simulations** (`compute`) are baked on the CPU, by the CPU renderer's own pipeline.
+- **Instanced geometry drawn by a shader**, such as `Line2`, `LineSegments2` and `Wireframe`: the vertex shader runs over
+  the template once per instance, with the per-instance attributes at that instance.
+- **A `switch` whose cases fall through**, which WGSL cannot express, is rewritten for that shader only: one pass of a
+  loop, so `break` still leaves it, with an `if` per case. A `continue` inside such a case leaves the switch instead of
+  continuing the loop around it.
+- **Hooks after `<opaque_fragment>`** run on the radiance the path found on the camera's line of sight from that
+  surface on, before the fog, as Three runs them on the lit colour. For a hook that is not linear in `gl_FragColor` this
+  is applied per path rather than to the converged colour.
+
+### Where this deliberately diverges from Three
+
+- **`settings.samples` means paths per pixel here**, where the CPU renderer reads it as antialiasing samples and takes
+  its path count from `globalIllumination.samples`. One number does both jobs in a path tracer.
+- **An `AmbientLight` or a `HemisphereLight` becomes an equally bright surrounding.** Three adds them straight to a
+  surface's diffuse term, which no path can carry; light that arrives from every direction is light from outside the
+  scene. The irradiance matches Three exactly wherever the sky is open, and **contributes nothing inside a closed room**,
+  which is the difference a host has to know about. It is not painted in the background, as in Three.
+- **Transparency is stochastic.** A surface with an opacity below one lets that share of rays straight through, which is
+  what makes a cutout cast a cutout shadow, and what makes the result converge rather than composite.
+- **Unlit surfaces emit.** A basic material, a shader material, a sprite: whatever colour Three would draw, the surface
+  radiates, so it also lights its surroundings (found by bounce rays, not aimed at).
+- Global illumination is always on. There is no flag for it: tracing paths is what this renderer does.
+- **Glass refracts** where Three's transmission samples a blurred copy of the opaque scene behind it. A volume bends what
+  is behind it and reflects its surroundings properly; a thin wall is exact. Neither is what Three draws.
+
+## Testing
+
+The CI gate needs no GPU: scene packing (points, lines, sprites, dashes, displacement and winding included), BVH
+packing, buffer layouts and alignment, the scheduler's feedback loop, and the upstream symbols imported from the CPU
+renderer. `kernel.test.ts` validates the whole kernel with naga, with translated shaders of every kind in it, so a WGSL
+mistake fails in CI rather than on a device. The hierarchy is checked against
+brute force over every triangle, with a traversal in the test file that mirrors the WGSL one step for step, so a packing
+mistake fails here instead of on a device where nothing can be printed.
+
+GPU suites are named `*.gpu.test.ts` and skip themselves when no adapter is available. They exist to catch WGSL that does
+not compile, which is the most common and most tedious error to find in a browser.
+
+Headless browsers do not judge images here. The software path for WebGPU differs from real drivers in floating point
+results, optional features and limits, which are the three dimensions a path tracer diverges in.
+
+What does judge the integrator is `pnpm verify`, which needs a real GPU and so stays out of CI. It drives headless Chrome
+over `scripts/verify.html` and prints a reading against an expectation for each check. Every scene in it has an answer
+known on paper rather than a stored reference image: a unit albedo Lambert surface facing a light of irradiance `pi/4`
+leaves a radiance of exactly `0.25`, whichever kind of light delivered it, so the same number checks the directional
+falloff, the inverse square law, the spot cone, the rectangle's projected area, the ambient conversion, the sRGB decode
+of a texture and the Fresnel split of the specular lobe. A wrong density or a misread texel compiles perfectly and simply
+produces the wrong picture; these numbers say which part is wrong.
+
+`pnpm verify --page other.html` runs another page under `scripts/` instead, for chasing one check without running all
+of them.
+
+It also reports how far neighbouring pixels sit apart at a low sample count, which is what a broken estimator and a badly
+weighted light both show up as, and it is the measurement to trust over any single image.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danilo Gadelha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# @tinypoly/gpu-renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@tinypoly/gpu-renderer)](https://www.npmjs.com/package/@tinypoly/gpu-renderer)
+[![npm downloads](https://img.shields.io/npm/dm/@tinypoly/gpu-renderer)](https://www.npmjs.com/package/@tinypoly/gpu-renderer)
+[![CI](https://github.com/tinypoly/gpu-renderer/actions/workflows/ci.yml/badge.svg)](https://github.com/tinypoly/gpu-renderer/actions/workflows/ci.yml)
+[![types](https://img.shields.io/npm/types/@tinypoly/gpu-renderer)](https://www.npmjs.com/package/@tinypoly/gpu-renderer)
+[![license](https://img.shields.io/npm/l/@tinypoly/gpu-renderer)](LICENSE)
+
+A WebGPU path tracer for [Three.js](https://threejs.org) scenes. It takes an ordinary `THREE.Scene` and traces it in WGSL compute shaders, accumulating paths until the image converges, and refines a canvas in place while it does.
+
+It is the GPU sibling of [@tinypoly/cpu-renderer](https://github.com/tinypoly/cpu-renderer), which powers the render mode of the [Tinypoly](https://tinypoly.com) editor: the same API, the same scene snapshot and the same settings, so a host picks one at startup and writes the rest once.
+
+**[Live example](https://tinypoly.github.io/gpu-renderer/)**
+
+- Unidirectional path tracing with multiple importance sampling: every light is aimed at with a shadow ray and weighed against the bounce that might find it, so a small bright lamp or a sun in an HDR converges in tens of samples.
+- Physically based shading as Three r185 lights it: Standard and Physical materials (transmission, dispersion, clearcoat, sheen, iridescence, anisotropy), Lambert, Phong, Toon, Basic, Matcap, Normal, Depth and `ShadowMaterial`, with all of their maps.
+- Real glass: thin walls that light crosses, and closed volumes that refract and absorb.
+- Perspective and orthographic cameras, any projection Three builds; meshes, lines (`Line`, `LineSegments`, `LineLoop`), dashed lines, fat lines (`Line2`), sprites and `PointsMaterial`.
+- Your custom `ShaderMaterial` GLSL, `RawShaderMaterial` and `onBeforeCompile` hooks: fragment shaders are translated to WGSL by [naga](https://github.com/gfx-rs/wgpu/tree/trunk/naga) and run in the kernel, with real derivatives; vertex shaders run on the CPU renderer's interpreter.
+- HDR, gradient or procedural sky environments, light probes, depth of field with polygonal bokeh, fog, volumetric lights, vignette and grain, and ACES, AgX or Neutral tone mapping.
+- Adaptive sampling: pixels whose noise is gone stop taking paths, and the work they leave goes to the dark, glossy and out of focus areas that still need it.
+- A variance-guided denoiser (the spatial filter of SVGF, with diffuse and specular light filtered apart as NVIDIA's RELAX does): each signal is separated from its albedo, filtered by an edge-avoiding wavelet that stops at normals, depths and roughness and trusts each pixel as far as its own variance says, and multiplied back, so textures stay sharp, a sharp reflection stays sharp and flat areas keep their exact mean.
+- Progressive output: the canvas refines sample by sample, and the render can be paused, resumed and cancelled.
+- No worker pool and no `SharedArrayBuffer`: the scene lives on the device, so the page needs no cross-origin isolation.
+
+## Install
+
+```sh
+npm install @tinypoly/gpu-renderer three
+```
+
+`three` is a peer dependency (0.185 or newer). `@tinypoly/cpu-renderer` comes along: the scene snapshot, the settings and the tone mapping are shared with it rather than written twice. The browser needs WebGPU.
+
+## Usage
+
+```ts
+import * as THREE from "three";
+import { GpuRenderer, attachCanvas, requestWebGpuSupport } from "@tinypoly/gpu-renderer";
+
+const { supported, reason } = await requestWebGpuSupport();
+if (!supported) throw new Error(reason); // the host decides what to fall back to: the CPU renderer, for one
+
+const scene = new THREE.Scene();
+const sphere = new THREE.Mesh(new THREE.SphereGeometry(1, 48, 24), new THREE.MeshPhysicalMaterial({ color: "tomato" }));
+scene.add(sphere);
+
+const camera = new THREE.PerspectiveCamera(40, 1, 0.1, 100);
+camera.position.set(0, 1, 5);
+camera.lookAt(0, 0, 0);
+
+const canvas = document.querySelector("canvas")!;
+
+const renderer = new GpuRenderer({
+  width: canvas.clientWidth,
+  height: canvas.clientHeight,
+  pixelRatio: window.devicePixelRatio,
+  scene,
+  camera,
+  settings: { samples: 256 }, // paths per pixel
+  environment: { kind: "gradient", topColor: "#9cb8d8", bottomColor: "#2b2a28" },
+});
+
+attachCanvas(renderer, canvas); // sizes the canvas and refines it in place while the image converges
+renderer.on("sample", ({ samples, target }) => console.log(`${samples} / ${target}`));
+const { width, height, data } = await renderer.render(); // RGBA bytes of the finished image
+```
+
+`width` and `height` are pixels; the render size multiplies them by `pixelRatio` and `settings.renderScale`. Every mesh takes part in shadows: a traced shadow comes from the geometry that casts it, so `castShadow` and `receiveShadow` on a mesh are not read.
+
+Without a canvas, take the image when it is done:
+
+```ts
+renderer.on("start", ({ width, height }) => { /* the render size */ });
+renderer.on("pixels", ({ x, y, width, height, data }) => { /* the whole image, once, when the last sample lands */ });
+```
+
+Setters record the inputs; `render()` starts a frame with the current ones:
+
+```ts
+camera.position.x += 1;                  // the camera is read at every render()
+renderer.setSettings({ samples: 1024, globalIllumination: { bounces: 8 } });
+const image = await renderer.render();
+```
+
+## API
+
+### `new GpuRenderer(options)`
+
+Every option has a setter of the same name.
+
+| Option | Type | |
+| --- | --- | --- |
+| `scene` | `THREE.Scene` or the result of `serializeScene` | A Three scene is serialized in the background. Defaults to an empty scene. |
+| `camera` | `THREE.Camera` or `CameraState` | A Three camera is read at every `render()`. Any projection works: perspective, orthographic, zoom and view offsets. Defaults to a perspective camera at (5, 5, 5) looking at the origin. |
+| `settings` | `RenderSettingsInput` | Merged over `DEFAULT_RENDER_SETTINGS`, group by group. See [Settings](#settings). |
+| `environment` | `RenderEnvironment` | See [Environment](#environment). Defaults to `DEFAULT_RENDER_ENVIRONMENT`, a gradient. |
+| `width`, `height` | `number` | Required. Image size in CSS pixels. |
+| `pixelRatio` | `number` | Defaults to 1. Pass `window.devicePixelRatio` for a sharp image on a high-density screen. |
+| `denoiser` | `Partial<DenoiserSettings>` | How the denoiser filters. Merged over `DEFAULT_DENOISER`. See [Denoiser](#denoiser). |
+
+### Methods
+
+| Method | |
+| --- | --- |
+| `render()` | Starts a frame with the current inputs and discards the one in progress. Resolves with the finished image, `{ width, height, data }`: `data` is RGBA bytes, straight sRGB, `width * height * 4` long. Rejects with an `AbortError` (see `isAbortError`) when a later `render()`, `cancel()` or `dispose()` replaces the frame, and with the error when the frame fails, a lost device included. |
+| `setScene(scene)` | A Three scene is serialized in the background; `render()` waits for it. |
+| `setCamera(camera)` | A Three camera is read as it is at every `render()`, so moving it or changing its aspect only needs a new frame. A `CameraState` from `serializeCamera` stays fixed. |
+| `setSettings(settings)` | Merges the given fields into the current settings, group by group: `{ fog: { enabled: true } }` keeps the other fog fields. |
+| `setEnvironment(environment)` | Replaces the environment. A change of intensity or rotation alone does not load the image again. |
+| `setSize(width, height, pixelRatio?)` | Image size in CSS pixels for the next frame; the pixel ratio stays unless given. |
+| `setPixelRatio(pixelRatio)` | |
+| `setDenoiser(denoiser)` | Merges the given fields into the denoiser's settings. A finished image is filtered again at once, without tracing anything: `image` and the canvas take the result and `pixels` fires. |
+| `pause()`, `resume()` | Stops or continues the frame between two dispatches. |
+| `cancel()` | Stops the frame in flight and keeps the device for the next one. `render()` rejects with an `AbortError` and `image` keeps what it held. A paused frame is cancelled too, and the next one starts unpaused. |
+| `dispose()` | Releases the device. |
+| `settings` | The settings the next frame renders with. |
+| `denoiser` | The denoiser's settings. |
+| `rendering`, `paused` | Whether a frame is in flight and whether it is paused. |
+| `image` | The last finished image, in the shape `render()` resolves with, or an empty one of the render size while a frame traces. `null` before the first frame starts. Each frame allocates a new buffer, so the image one `render()` resolved with stays as it is. |
+| `renderWidth`, `renderHeight` | The size the next frame renders at: CSS pixels times `pixelRatio` and `settings.renderScale`. |
+
+### Events
+
+`renderer.on(event, listener)` returns the function that removes the listener; `once` and `off` exist too. The payloads are the CPU renderer's; what differs is when they fire, because no pixel is finished before the last sample.
+
+| Event | Payload | |
+| --- | --- | --- |
+| `start` | `{ width, height }` | The scene is on the device and tracing starts. `image` has the render size and is empty. |
+| `sample` | `{ samples, target }` | One more path per pixel over the whole image. Only this renderer has it. |
+| `pixels` | `{ x, y, width, height, data }` | The finished image, **once**, as a single region at (0, 0). `image` already holds it. |
+| `progress` | `{ completed, total, phase }` | Rows traced out of `total`, over every sample. `phase` is `"prepare"` while the scene uploads and `"shade"` while it traces. |
+| `bucket` | `{ worker, bucket, width, height }` | The band of rows on the device, always as worker 0, or `null` when it is idle. The renderer sizes its dispatches to keep the page responsive. |
+| `complete` | | The image is finished. `render()` resolves with it right after. |
+| `error` | `Error` | The frame failed. `render()` rejects with the same error. |
+
+### `attachCanvas(renderer, canvas)`
+
+Draws the output on an `HTMLCanvasElement` through a WebGPU context: the canvas takes the render size and is refined in place after every dispatch. A pixel no sample has reached yet stays see-through, so a page can show a preview under the canvas until the image covers it. The canvas must not already hold another context. Returns the function that detaches it.
+
+A WebGPU canvas does not keep what it presented: to save the image, use the pixels `render()` resolves with, or `image`.
+
+### WebGPU support
+
+| Function | |
+| --- | --- |
+| `isWebGpuAvailable()` | The cheap synchronous check: whether `navigator.gpu` exists. It does not prove an adapter does. |
+| `requestWebGpuSupport()` | Asks for an adapter, which is the only honest answer, because a browser can expose `navigator.gpu` and still hand back nothing. Resolves with `{ supported, reason }`. |
+
+The renderer never falls back on its own. Choosing another renderer when WebGPU is missing is the host's decision, and the CPU renderer takes the same calls.
+
+### Settings
+
+`RenderSettings`, grouped by feature, the CPU renderer's own. Defaults are `DEFAULT_RENDER_SETTINGS`; `mergeSettings(base, input)` applies a partial `RenderSettingsInput` the way `setSettings` does. A path tracer reads some of them differently:
+
+| Field | Default | |
+| --- | --- | --- |
+| `renderScale` | `1` | Multiplier on the image size. |
+| `samples` | `4` | **Paths per pixel**, on average: one number does the antialiasing and the global illumination in a path tracer, and a few hundred is a clean image. Above 32, a pixel that has converged stops early and the noisiest ones take up to four times as many. |
+| `toneMapping` | `"aces"` | `"aces"`, `"agx"`, `"neutral"` or `"linear"`. |
+| `exposure` | `1` | |
+| `background.mode` | `"environment"` | `"environment"`, `"color"` or `"transparent"`, which makes the image's alpha the coverage of every pixel. |
+| `background.color` | `"#1a1a1a"` | Used by `mode: "color"`. |
+| `shadows.enabled` | `true` | Whether Three's lights are occlusion tested. Emissive geometry always is. |
+| `shadows.softness` | `1` | Angular diameter of the lights in degrees. `0` gives hard shadows. |
+| `globalIllumination.bounces` | `3` | How far a path goes. Glass wants four or more. |
+| `globalIllumination.clamp` | `0` | Maximum luminance one indirect contribution may add, which trades a little bias for fewer fireflies. `0` disables clamping. |
+| `depthOfField.enabled` | `false` | |
+| `depthOfField.focusDistance` | `10` | World units. |
+| `depthOfField.aperture` | `2.8` | f-number. |
+| `depthOfField.blades` | `0` | Polygon sides of the bokeh. `0` is circular. |
+| `fog.enabled` | `false` | Linear fog over every surface. Without it, `scene.fog` applies. |
+| `fog.color` | `"#b8c4d0"` | |
+| `fog.near`, `fog.far` | `10`, `60` | View depth. |
+| `vignette` | `0` | `0` to `1`. |
+| `grain` | `0` | `0` to `1`. |
+
+`globalIllumination.denoise` (default `true`) turns the denoiser on: on the canvas at the end of every pass, and on the image `render()` resolves with. Switching it alone filters the finished image again without tracing.
+
+### Denoiser
+
+A variance-guided wavelet filter, the spatial half of SVGF, with the diffuse and the specular light filtered apart, as NVIDIA's RELAX and REBLUR do. Every path is split at its first scatter by the lobe it took; each signal is divided by its own albedo (the diffuse colour, the GGX lobe's directional albedo), filtered by passes that stop at normals and depths, and multiplied back, so textures stay sharp. The specular filter also stops at roughness, and reaches only as far as the footprint the lobe leaves on the screen, from the roughness and the distance to what it reflects: a mirror is left alone, a rough reflection of something far is smoothed widely. Each pixel is trusted as far as its own variance says. `DenoiserSettings`, defaults in `DEFAULT_DENOISER`:
+
+| Field | Default | |
+| --- | --- | --- |
+| `strength` | `1` | How much of the filtered image replaces the traced one, from `0` to `1`. |
+| `passes` | `3` | Wavelet passes, `1` to `5`: how far the filter reaches, 2, 6, 14, 30 or 62 pixels. |
+| `edge` | `2` | How large a luminance difference still counts as noise, in standard deviations of the pixel's own noise. Lower keeps more detail and removes less noise. |
+| `onlyNoisy` | `true` | Leaves the pixels that have converged as they were traced, and filters only where noise is still visible. |
+| `antiFirefly` | `true` | Before filtering, clamps a pixel brighter than every one of its eight neighbours to the brightest of them, in each signal. |
+
+A denoiser trades noise for detail. What it smooths most is what its guides cannot see: the relief of a lacquer, an out of focus area. With `onlyNoisy` it leaves alone whatever has already converged, so more samples always mean less filtering.
+
+```ts
+renderer.setDenoiser({ strength: 0.6, edge: 1 }); // gentler: filters the finished image again, no tracing
+```
+
+Global illumination is always on, because tracing paths is what this renderer does: `globalIllumination.enabled`, `samples`, `intensity`, `cache` and `cacheSpacing`, `ambientOcclusion` and `tileSize` are the CPU renderer's and are not read.
+
+### Environment
+
+`RenderEnvironment`. Lights the scene and paints the background when `background.mode` is `"environment"`. An HDR image gets a luminance distribution, so a shadow ray can aim at its sun.
+
+```ts
+{ kind: "hdri", url: "studio.hdr" }                                            // equirectangular .hdr
+{ kind: "gradient", topColor: "#9cb8d8", bottomColor: "#2b2a28", exponent: 2 } // exponent defaults to 2
+{ kind: "hdri", url: "studio.hdr", intensity: 0.8, rotation: 90 }              // intensity 1 and rotation 0 by default
+```
+
+### Object options
+
+The renderer reads the CPU renderer's optional settings from `userData.cpuRenderer` on Three objects; the key keeps that name, so a scene renders the same in both. A plain scene needs none of them.
+
+| Where | Field | |
+| --- | --- | --- |
+| Any object | `exclude` | Leaves the object and its children out of the render. |
+| Light | `volumetric` | Scatters the light in the air: `true`, or a medium `{ density, anisotropy, spread }`. |
+| Scene | `sky` | A `ProceduralSky`: a shader that replaces the environment. |
+| Material | `time` | Value of the shader's `time` uniform. |
+| Material | `planarCapture` | Renders planar reflection and refraction textures for a flat surface, path traced from the mirrored camera. The surface's local +Y is its normal. |
+| Material | `compute` | A `MaterialCompute`: fragment passes baked on the CPU into the material's uniforms. |
+| Material | `uniforms` | The live uniforms of a material patched in `onBeforeCompile`. |
+| Material | `prepare` | Called with the scene before it is serialized. |
+
+```ts
+light.userData.cpuRenderer = { volumetric: { density: 0.05 } };
+```
+
+### Helpers
+
+| Function | |
+| --- | --- |
+| `serializeScene(scene)` | Async. The snapshot `setScene` builds from a Three scene, to reuse across renderers, the CPU one included. |
+| `serializeCamera(camera)` | A fixed `CameraState` snapshot of a Three camera, including zoom and view offsets. |
+| `sceneSignature(scene)` | A string that changes whenever something the renderer reads changes. Compare it before re-serializing an interactive scene. |
+| `isAbortError(error)` | Whether a `render()` rejection means the frame was replaced or cancelled rather than failed. |
+| `packGeometry`, `buildBvh`, `packLights`, `packTextures`, `sceneByteLength` | The scene packing, published because the sizes it produces are what a host checks against a device's limits before uploading. |
+
+## Bundlers
+
+The renderer loads naga's WebAssembly the first time a scene has a shader, from `new URL("naga_bg.wasm", import.meta.url)` next to the `naga-wasm` module, which Vite, webpack 5, Rspack and Parcel resolve. With **Vite**, keep it out of dependency pre-bundling, or the dev server moves the module away from its binary:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  optimizeDeps: { exclude: ["naga-wasm"] },
+});
+```
+
+## Limits
+
+This is a path tracer, not Three.js or WebGL conformance, and not a match for the CPU renderer's image: shadows, indirect light, reflections and transmission come out differently, usually better, never identical. Where it deliberately disagrees with Three (ambient lights as surroundings, stochastic transparency, unlit surfaces that emit, refracting glass) and what it reads, [ARCHITECTURE.md](ARCHITECTURE.md) lists in full. A scene has to fit the device's largest storage binding, and it is not available in Node, which has no WebGPU.
+
+## Development
+
+`pnpm dev` opens the example gallery, the same scenes as the CPU renderer's, traced here. `pnpm test` runs the CI gate, which needs no GPU; `pnpm verify` renders scenes with answers known on paper on a real GPU in headless Chrome; `pnpm capture:scenes` renders the gallery pictures with the example running. `pnpm verify --page divergence.html` measures what the megakernel loses to divergence: the same grid of spheres with one material at a time and with all of them mixed.
+
+## License
+
+[MIT](LICENSE)