@plasius/gpu-renderer 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -23,11 +23,10 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
-## [0.1.13] - 2026-06-01
+## [0.1.15] - 2026-06-04
 
 - **Added**
-  - Added wavefront path-tracing queue/buffer contracts and bounce-schedule
-    metadata beneath `createRayTracingRenderPlan(...)`.
+  - (placeholder)
 
 - **Changed**
   - (placeholder)
@@ -38,6 +37,84 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
+## [0.1.14] - 2026-06-04
+
+- **Added**
+  - Added wavefront path-tracing queue/buffer contracts and bounce-schedule
+    metadata beneath `createRayTracingRenderPlan(...)`.
+  - Added a tiled WebGPU wavefront compute renderer with scene-object buffers,
+    GPU ray queues, hit records, material continuation, emissive/environment
+    termination, ambient residual expiry, denoise resolve, and presentation.
+  - Added triangle mesh normalization, GPU-source mesh packing, triangle/BVH
+    buffer contracts, and display-quality guards requiring mesh BVH input.
+  - Added GPU mesh-source buffer packing and GPU build-pass entry points for
+    triangle assembly, GPU Morton leaf sorting, sorted leaf materialization,
+    and deterministic, level-concurrent BVH node construction.
+  - Added public BVH sort-stage and build-level scheduling metadata for worker/queue
+    integration.
+  - Expanded GPU hit records with primitive id, material reference, medium
+    reference, barycentric coordinates, and UV coordinates.
+  - Added mesh BVH tests for flat normals, smooth normals, stable triangle
+    identity, leaf splitting, and GPU record layout stability.
+  - Added public scene-object packing/config helpers for Product Studio and
+    other package consumers.
+  - Updated the browser demo to mount the wavefront compute renderer directly
+    and consume a `@plasius/gpu-lighting` environment preset.
+  - Added `samplesPerPixel` support for GPU wavefront renders so quality
+    presets can accumulate multiple primary-ray samples without increasing
+    tile-queue buffer size.
+  - Added a two-stage full-frame GPU denoise pass that filters linear
+    `rgba16float` radiance through a scratch texture after all tiles complete,
+    then tone-maps into the final `rgba8unorm` output while avoiding tile-local
+    denoise artifacts.
+  - Added GPU emissive-triangle continuation guidance stored in the BVH buffer
+    tail so active diffuse rays sample finite mesh light geometry more often
+    without adding a ninth trace storage buffer or separate direct-light/shadow
+    accumulation path.
+  - Added WebGPU environment-light portal records so rooms and studio interiors
+    can guide and gate sky/HDRI contribution through openings such as windows.
+
+- **Changed**
+  - Wavefront environment misses now evaluate a direction-aware sky/key-light
+    environment payload instead of only using a flat environment colour.
+  - Wavefront environment misses now respect `environmentPortalMode`; in
+    `guide-and-gate` mode, misses outside configured portals fall back to the
+    ambient residual instead of receiving full sky radiance.
+  - Display-quality wavefront configuration now uses GPU-built mesh
+    acceleration; CPU-built mesh acceleration is treated as debug-only.
+  - Replaced the one-thread BVH internal-node build kernel with bottom-up
+    level dispatches so parent nodes at the same depth build concurrently on
+    the GPU.
+  - Reordered mesh BVH leaves on the GPU by Morton-style centroid keys before
+    internal node construction, avoiding author/index-order BVH layout as the
+    display-quality baseline.
+  - Removed the direct `@plasius/gpu-shared` dependency from the renderer to
+    keep shared demo adapters dependent on the renderer rather than the reverse.
+  - Wavefront surface resolution now removes the separate direct key-light
+    accumulation term, clamps high-energy path samples in linear radiance, and
+    applies a bounded estimator weight to guided emissive hits while relying on
+    active emissive/environment path hits plus ambient residual expiry for
+    preview output.
+  - Wavefront primary-ray jitter and bounce sampling now use mixed
+    pixel/sample/bounce/frame seeds to reduce row-correlated low-sample noise.
+  - Wavefront frames now reuse a static GPU-built mesh BVH after the first
+    acceleration build and batch tile/sample tracing, tile output, optional
+    denoise, and presentation into one frame command submission.
+
+- **Fixed**
+  - Fixed primary-ray jitter seeding to use absolute screen pixel ids instead
+    of tile-local pixel ids, preventing repeated sampling patterns across
+    tiles.
+  - Fixed environment portal WGSL reserved-word usage and now request the
+    required 9-storage-buffer trace limit from capable WebGPU adapters before
+    creating the mesh-BVH trace pipeline.
+  - Fixed the WebGPU hit-buffer stride to match the WGSL `HitRecord` layout
+    and added a continuation-queue capacity guard, preventing tile-row
+    corruption in mesh BVH wavefront renders.
+
+- **Security**
+  - (placeholder)
+
 ## [0.1.12] - 2026-05-13
 
 - **Added**
@@ -209,4 +286,5 @@ All notable changes to this project will be documented in this file.
 [0.1.10]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.10
 [0.1.11]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.11
 [0.1.12]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.12
-[0.1.13]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.13
+[0.1.14]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.14
+[0.1.15]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.15

package/README.md

@@ -106,6 +106,117 @@ performance packages. It now also exposes the renderer-owned wavefront queue
 model, versioned ray/hit/surface/material/medium/accumulation contracts, and
 the termination policy for emissive/environment path completion.
 
+## WebGPU Wavefront Compute Renderer
+
+The package also exposes an executable WebGPU wavefront renderer for active-ray
+debug validation scenes. It is compute-driven, tiled, and breadth-first by
+bounce depth, so queue buffers are bounded by tile size instead of presentation
+resolution. Renderer-owned GPU record sizes are part of the public compute
+limits so ray, hit, triangle, BVH, and accumulation buffers stay aligned with
+their WGSL layouts.
+
+```js
+import {
+  createWavefrontPathTracingComputeRenderer,
+} from "@plasius/gpu-renderer";
+
+const renderer = await createWavefrontPathTracingComputeRenderer({
+  canvas: document.querySelector("#product-render"),
+  width: 1280,
+  height: 720,
+  maxDepth: 6,
+  samplesPerPixel: 8,
+  displayQuality: true,
+  meshes: [
+    {
+      id: 1,
+      positions: [-1, -1, 0, 1, -1, 0, 0, 1, 0],
+      indices: [0, 1, 2],
+      normals: [0, 0, 1, 0, 0, 1, 0, 0, 1],
+      emission: [8, 7, 5, 1],
+    },
+  ],
+});
+
+renderer.renderOnce();
+```
+
+Analytic scene objects remain available for debug fixtures:
+
+```js
+const debugRenderer = await createWavefrontPathTracingComputeRenderer({
+  canvas: document.querySelector("#debug-render"),
+  width: 1280,
+  height: 720,
+  maxDepth: 6,
+  sceneObjects: [
+    {
+      type: "sphere",
+      center: [0, 1.8, -0.5],
+      radius: 0.35,
+      emission: [8, 7, 5, 1],
+      materialKind: "emissive",
+    },
+  ],
+});
+
+debugRenderer.renderOnce();
+```
+
+Scene objects currently support analytic `sphere` and axis-aligned `box`
+records with colour, emission, roughness, metallic, opacity, and IOR fields.
+These records are debug fixtures only. Product Studio visual rendering requires
+the mesh BVH path described in
+`docs/adrs/adr-0007-triangle-mesh-wavefront-path-tracing.md`. This is a
+project-wide display-quality baseline for path-traced rendering, not a
+Product-Studio-only requirement.
+
+Mesh inputs are normalized into triangle records, packed into GPU buffers, and
+uploaded as source buffers for GPU triangle assembly and GPU BVH construction.
+Vertex normals are preserved for smooth shading; when normals are absent the
+triangle geometric normal is used. The display-quality path uses
+`accelerationBuildMode: "gpu"` and rejects CPU-built acceleration. The
+`createWavefrontMeshAcceleration(...)` helper remains available only for debug
+fixtures and deterministic layout tests. GPU BVH construction now uses
+Morton-style centroid keys to sort leaf references before sorted leaves and
+level-concurrent internal nodes are materialized. The current mesh path is the
+GPU runtime baseline under active hardening.
+
+`samplesPerPixel` controls how many GPU primary-ray samples are accumulated per
+screen pixel within a single render. This multiplies dispatch work but does not
+increase the tile queue memory footprint, so 720p/1080p/4K targets remain
+bounded by `tileSize`. When `denoise` is enabled the renderer writes raw
+linear radiance to an `rgba16float` texture first, then runs a two-stage
+full-frame GPU denoise through an `rgba16float` scratch texture before final
+tone mapping into the presented `rgba8unorm` output. Filtering in linear
+radiance space lets the denoise pass cross tile boundaries without compressing
+energy/detail before the final resolve. The renderer also stores compact
+emissive-triangle metadata in the existing BVH buffer tail and uses it to guide
+diffuse continuation rays toward finite mesh light geometry without adding a
+ninth trace storage buffer. This is not a separate shadow/direct-light pass: the
+active ray still has to hit emissive geometry or miss into the environment
+before radiance is accumulated. Guided emissive hits carry a bounded estimator
+weight so finite light guidance does not over-expose low-sample renders before
+full material PDFs/MIS are implemented. High-energy samples are clamped in
+linear radiance space to keep low-sample preview output stable while production
+sampling, temporal accumulation, and better material PDFs are hardened.
+For static mesh scenes, the GPU acceleration build is submitted once and then
+reused by subsequent frames. Per-frame tracing writes one dynamic uniform slot
+per tile/sample or post-process pass and batches tile tracing, tile output,
+optional denoise, and presentation into a single command submission. WebGPU
+still preserves ordering between dependent bounce passes, but the renderer no
+longer forces one CPU queue submission per tile/sample.
+Environment-light portals can additionally guide and gate sky/HDRI contribution
+through rectangular openings such as windows. `environmentPortalMode: "guide"`
+biases diffuse continuation rays toward configured openings, while
+`"guide-and-gate"` requires an environment miss to pass through a portal before
+it receives sky radiance; misses outside a portal fall back to the ambient
+residual. This keeps interior rooms from treating the whole sky as visible from
+every bounce.
+Texture sampling, dynamic TLAS updates, higher-grade LBVH/SAH construction,
+runtime execution behind the `@plasius/gpu-worker` lock-free queue, and broader
+material lookup remain follow-up work.
+
 ## XR integration
 
 ```js
@@ -129,6 +240,17 @@ renderer.bindXrManager(xr, {
 - `getRendererWorkerProfile(name?)`
 - `getRendererWorkerManifest(name?)`
 - `createRayTracingRenderPlan(options)`
+- `createWavefrontPathTracingComputeRenderer(options)`
+- `createWavefrontPathTracingComputeConfig(options)`
+- `normalizeWavefrontMesh(input)`
+- `createWavefrontGpuMeshSource(meshes)`
+- `createWavefrontBvhSortStages(itemCount)`
+- `createWavefrontBvhBuildLevels(triangleCount)`
+- `createWavefrontMeshAcceleration(meshes)`
+- `normalizeWavefrontSceneObject(input)`
+- `packWavefrontSceneObjects(sceneObjects, capacity?)`
+- `packWavefrontTriangles(triangles, capacity?)`
+- `packWavefrontBvhNodes(nodes, capacity?)`
 - `bindRendererToXrManager(renderer, xrManager, options)`
 - `defaultRendererClearColor`
 - `rendererDebugOwner`
@@ -149,8 +271,11 @@ npm run demo
 
 Then open `http://localhost:8000/gpu-renderer/demo/`.
 
-The demo now reports explicit canvas state so it is clear whether the renderer
-is mounted, idle, running, or blocked by secure-context / WebGPU support.
+The demo now mounts the mesh BVH WebGPU wavefront renderer directly and passes a
+`@plasius/gpu-lighting` environment preset into the render. It reports the
+active wavefront depth, tile count, triangle/BVH counts, lighting preset, probe
+luminance, and hot buffer memory so it is clear whether the renderer is tracing
+mesh paths rather than only showing planning metadata.
 
 ## Development Checks