@plasius/gpu-renderer 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -23,25 +23,14 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
-## [0.2.5] - 2026-06-14
-
-- **Added**
-  - (placeholder)
-
-- **Changed**
-  - (placeholder)
-
-- **Fixed**
-  - (placeholder)
-
-- **Security**
-  - (placeholder)
-
-## [0.2.4] - 2026-06-11
+## [0.2.6] - 2026-06-14
 
 - **Added**
   - Added `updateCamera(...)` support for wavefront renderers so validation
     views can animate camera movement without rebuilding mesh buffers.
+  - Added `gpuWorkerJobs` diagnostics to wavefront frame stats so callers can
+    inspect completed compute-dispatch jobs per frame, per second, and per
+    command submission alongside the existing GPU parallelism figures.
   - Added `gpuParallelism` diagnostics to wavefront frame stats and snapshots so
     consumers can inspect adapter compute limits, direct workgroups,
     indirect-dispatch estimates, and whether a frame exposes multi-workgroup GPU
@@ -52,17 +41,72 @@ All notable changes to this project will be documented in this file.
   - Added default-on `deferredPathResolve` support for wavefront tracing so
     surface traversal records material responses and terminal source radiance
     before the output pass resolves the path backward into pixel accumulation.
+  - Added design and ADR coverage for shadow-tested direct light and bounded
+    bounce attenuation in deferred wavefront path resolution.
+  - Added display-quality material-response support for sheen, clearcoat, and
+    decoded base-colour, metallic-roughness, normal, and occlusion maps in the
+    wavefront mesh path.
+  - Added GPU hit-time material atlas sampling for display-quality wavefront
+    tracing so exact hit UVs now drive base-colour, metallic-roughness, normal,
+    occlusion, and emissive texture evaluation on the GPU instead of relying on
+    CPU-baked triangle averages.
+  - Added ADR and design coverage for generic glTF material transport so
+    specular colour, sheen colour, transmission, clearcoat, and IOR can travel
+    through the shared wavefront shading path instead of being inferred from
+    demo-specific material names.
+  - Added ADR and design coverage for environment-driven glossy surface
+    response so specular, sheen, and clearcoat shading can use reflection-
+    aligned environment radiance instead of leaning primarily on a sun-only
+    highlight proxy.
+  - Added ADR and design coverage for prefiltered HDRI, BRDF LUT, and MIS-based
+    environment lighting in the wavefront display-quality path.
+  - Added adaptive `renderFrame(...)` sampling controls so callers can cap a
+    frame with `frameTimeBudgetMs`, guarantee a `minimumSamplesPerPixel`, and
+    inspect actual `renderedSamplesPerPixel` separately from the configured SPP
+    ceiling.
+  - Added `createWavefrontAdaptiveSamplingLevels(...)` so consumers can hand
+    wavefront SPP adaptation to `@plasius/gpu-performance` without duplicating
+    renderer-specific ladder construction in app or demo code.
 
 - **Changed**
+  - Changed internal wavefront frame batching and dispatch-diagnostics plumbing
+    to live in a dedicated runtime helper module so scheduling concerns stay
+    separated from shader and pipeline assembly.
   - Changed wavefront frame dispatch to split large tile/sample workloads into
     bounded command submissions instead of encoding an entire high-resolution
     frame into one command buffer.
-  - Changed display-quality wavefront tracing to require one additional
-    path-vertex storage buffer, raising the trace-stage storage-buffer request
-    from 9 to 10.
+  - Changed display-quality wavefront tracing to pack HDRI importance-sampling
+    PDFs and CDFs into one GPU texture so the MIS path stays compatible with
+    adapters that expose only the existing 10 trace-stage storage buffers.
   - Changed wavefront terminal/direct environment estimates to consume
     `environmentLighting.sunlitBaseline` as a time-of-day daylight floor instead
     of relying only on restrained ambient colour.
+  - Changed deferred wavefront surface resolution to allow explicit
+    shadow-tested direct lighting before terminal continuation resolution and to
+    remap extremely dark bounce responses to a small scene-brightness floor.
+  - Changed wavefront denoise to adapt its kernel strength to SPP and to skip
+    the intermediate full-screen scratch pass for 4+ SPP frames, reducing blur
+    and denoise cost on cleaner renders.
+  - Changed async wavefront frame rendering to wait for submitted GPU work and
+    to batch higher-SPP workloads more defensibly, while raising the SPP ceiling
+    from 64 to 256 for higher-end GPUs.
+  - Changed awaited high-SPP wavefront rendering to fence submitted GPU work
+    once per `renderFrame(...)` call instead of after every intermediate command
+    submission.
+  - Changed wavefront scene, mesh, triangle, material, and hit records to carry
+    generic glTF-style specular colour, sheen colour, and transmission inputs
+    in addition to the existing roughness, metallic, clearcoat, and IOR data.
+  - Changed direct and terminal wavefront surface environment shading to sample
+    reflection-aligned environment radiance for glossy materials before adding
+    narrower sun highlights, improving leather, chrome, and polished-surface
+    response without model-specific rules.
+  - Changed wavefront environment-lighting setup to prepare roughness-aware HDRI
+    resources, a BRDF integration LUT, and HDRI importance-sampling tables for
+    display-quality renders.
+  - Changed wavefront continuation sampling to emit BSDF PDFs for diffuse,
+    conductor, clearcoat, and transmission paths so environment misses and
+    explicit HDRI samples can use MIS instead of the older light-guidance
+    heuristics.
 
 - **Fixed**
   - Fixed low-sample wavefront renders so non-emissive surface hits receive a
@@ -70,6 +114,12 @@ All notable changes to this project will be documented in this file.
   - Reduced deterministic environment fill on direct surface hits so ambient
     rescue lighting no longer washes dark materials toward the full scene
     ambient colour.
+  - Fixed wavefront output-probe readback so higher-SPP validation renders wait
+    for submitted GPU work before mapping the staging buffer, avoiding
+    `GPUBuffer.mapAsync(...)` lifetime failures during probe capture.
+  - Fixed display-quality environment misses so non-delta BSDF paths now apply
+    MIS weighting against the HDRI direction PDF instead of overcounting raw
+    sky radiance on termination.
 
 - **Security**
   - (placeholder)
@@ -363,5 +413,4 @@ All notable changes to this project will be documented in this file.
 [0.1.12]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.12
 [0.1.14]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.1.14
 [0.2.1]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.1
-[0.2.4]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.4
-[0.2.5]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.5
+[0.2.6]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.6

package/README.md

@@ -113,7 +113,10 @@ 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.
+their WGSL layouts. Frame submission batching and dispatch diagnostics are kept
+in dedicated runtime helpers so performance-facing integrations can consume
+stable frame stats without inheriting the renderer's shader and pipeline
+assembly internals.
 
 ```js
 import {
@@ -168,7 +171,8 @@ debugRenderer.renderOnce();
 ```
 
 Scene objects currently support analytic `sphere` and axis-aligned `box`
-records with colour, emission, roughness, metallic, opacity, and IOR fields.
+records with colour, emission, roughness, metallic, opacity, IOR, clearcoat,
+sheen colour, specular colour, and transmission 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
@@ -185,6 +189,18 @@ 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.
+When mesh inputs also carry UVs plus decoded base-colour,
+metallic-roughness, normal, occlusion, or emissive maps, the display-quality
+path now packs them into GPU texture atlases and samples them at the resolved
+hit UV inside the wavefront trace pass. Generic glTF-style material factors
+such as clearcoat, sheen colour, specular colour, transmission, and IOR are
+also preserved through the GPU records so demo validation does not need
+model-name overrides. CPU-side texture work is limited to load-time decode and
+atlas packing; per-hit shading stays on the GPU. Direct and terminal glossy
+response now also samples reflection-aligned environment radiance so leather,
+chrome, and other polished authored materials can read from the active
+environment map or procedural sky instead of relying mostly on a sun-direction
+proxy.
 
 `samplesPerPixel` controls how many GPU primary-ray samples are accumulated per
 screen pixel within a single render. This multiplies dispatch work but does not
@@ -207,9 +223,12 @@ better material PDFs are hardened. By default, `deferredPathResolve` records
 per-bounce material responses in a tile-bounded path buffer and records the
 terminal emissive/HDRI/environment source in the final path slot. The output
 pass then resolves that recorded path backward and adds the weighted sample to
-the pixel accumulation, so surface traversal no longer injects broad visible
-ambient/direct environment light before a terminal source is known. Set
-`deferredPathResolve: false` only for legacy forward-accumulation comparison.
+the pixel accumulation, so unresolved continuation light is still deferred until
+a terminal source is known. Surface resolution may still add a small
+shadow-tested direct-light term immediately when it has an explicit source and
+visibility result, which keeps true occlusion shadows possible without falling
+back to broad per-bounce ambient fill. Set `deferredPathResolve: false` only
+for legacy forward-accumulation comparison.
 When an `environmentMap` is provided, the wavefront trace shader samples it as
 an equirectangular radiance source for environment misses and uses the same
 mapped radiance for terminal residuals before falling back to static ambient.
@@ -217,14 +236,28 @@ The procedural horizon/zenith/sun model remains the fallback for callers that
 have not supplied an HDRI/radiance texture. `environmentLighting.sunlitBaseline`
 adds a time-of-day daylight floor to terminal and direct environment estimates,
 so bright presets retain colour at the last collision without returning to a
-whitewashed global ambient term.
+whitewashed global ambient term. Extremely dark recorded bounce responses are
+also remapped to a small scene-brightness-driven luminance floor so bright
+low-sample scenes do not produce isolated black speckles when a valid terminal
+source was already found.
 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 bounded command submissions controlled
 by `maxFramePassesPerSubmission` to keep 4K/high-spp command buffers from
 becoming oversized. `updateCamera(...)` can update the per-frame camera uniforms
-between renders without rebuilding mesh buffers. Frame stats and snapshots expose
+without rebuilding scene buffers. `renderFrame(...)` also accepts an optional
+`frameTimeBudgetMs` plus `minimumSamplesPerPixel`: when present, configured
+`samplesPerPixel` becomes a ceiling instead of a hard requirement, the renderer
+guarantees at least the minimum full-screen pass, and frame stats report both
+configured `samplesPerPixel` and actual `renderedSamplesPerPixel` so realtime
+callers can budget motion frames without overstating delivered quality.
+For consumers that want to hand wavefront SPP adaptation to
+`@plasius/gpu-performance`, `createWavefrontAdaptiveSamplingLevels(...)` exposes
+a bounded low-to-high ladder of per-frame `samplesPerPixel`,
+`frameTimeBudgetMs`, and `minimumSamplesPerPixel` configs that stay aligned
+with the renderer's supported adaptive-sampling surface. Frame stats and
+snapshots expose
 `gpuParallelism` diagnostics with adapter compute limits, configured workgroup
 size, direct compute dispatches, known workgroups/invocations, indirect dispatch
 counts, and upper-bound indirect work estimates. WebGPU does not expose physical