rayzee 7.30.1 → 7.31.0

package/README.md

@@ -545,6 +545,8 @@ engine.denoisingManager.setAutoExposureParams({ keyValue: 0.18 })
 // OIDN & Upscaler
 engine.denoisingManager.setOIDNEnabled(true)
 engine.denoisingManager.setOIDNQuality('high')
+engine.denoisingManager.setStrategy('oidn')              // OIDN owns the live view; see below
+engine.denoisingManager.continuousDenoiseInterval = 250   // cap refreshes at 4/sec (default 8 = uncapped)
 engine.denoisingManager.setUpscalerEnabled(true)
 engine.denoisingManager.setUpscalerScaleFactor(2)
 engine.denoisingManager.setUpscalerQuality('high')
@@ -735,7 +737,7 @@ engine.addEventListener(EngineEvents.RENDER_COMPLETE, (e) => {
 | `RENDER_COMPLETE` | Rendering has converged |
 | `RENDER_RESET` | Accumulation buffer is reset |
 | `FRAME` | Fires once per `animate()` tick — hook external instrumentation (stats panels, telemetry) here |
-| `DENOISING_START` / `DENOISING_END` | Denoiser runs |
+| `DENOISING_START` / `DENOISING_END` | Denoiser runs. `event.continuous` is `true` for a cadence denoise of the still-accumulating image, `false` for the one that ends a render |
 | `UPSCALING_START` / `UPSCALING_PROGRESS` / `UPSCALING_END` | AI upscaler runs |
 | `LOADING_UPDATE` / `LOADING_RESET` | Asset loading progress |
 | `STATS_UPDATE` | Performance stats updated |
@@ -849,7 +851,10 @@ import { setBindingAudit, getBindingAuditFindings, clearBindingAuditFindings } f
 
 ### Enabling OIDN (Intel Open Image Denoise)
 
-OIDN provides high-quality AI denoising for final renders. It runs automatically after the render converges (reaches `maxSamples`).
+OIDN provides high-quality AI denoising. It runs automatically once the render converges (reaches
+`maxSamples`), and — in `'interactive'` mode — also on a cadence while the image is still
+accumulating, so a preview shows a clean picture as it refines instead of only at the end. See
+[Continuous denoising](#continuous-denoising).
 
 1. **Install the package**
 
@@ -883,6 +888,112 @@ OIDN provides high-quality AI denoising for final renders. It runs automatically
 | `'balance'` | 1.8 MB | accumulated | General use |
 | `'high'` | 7.3 MB | accumulated | Final renders — used by `configureForMode('production')` |
 
+#### When the denoiser runs
+
+Two independent decisions, because they answer different questions — *what cleans the view while the
+render works*, and *does the finished image get a proper pass*:
+
+```js
+engine.denoisingManager.setStrategy('oidn');    // 'none' | 'edgeaware' | 'asvgf' | 'nrd' | 'oidn'
+engine.denoisingManager.setOIDNEnabled(false);  // a full OIDN pass on the finished image
+```
+
+Exactly one denoiser owns the live view, which is why OIDN is an entry in that list rather than a
+parallel switch — two of them would mean paying for a per-frame denoise whose result the OIDN
+overlay immediately covers. But choosing OIDN there says nothing about the finished image, and
+switching the final pass on says nothing about the live view. All six combinations are reachable:
+
+| `setStrategy` | `setOIDNEnabled` | Camera moving | Still, accumulating | Finished |
+|---|---|---|---|---|
+| `'none'` | `false` | raw | raw | raw |
+| `'none'` | `true` | raw | raw | OIDN |
+| `'asvgf'` | `false` | ASVGF | ASVGF | ASVGF's last frame |
+| `'asvgf'` | `true` | ASVGF | ASVGF | OIDN |
+| `'oidn'` | `false` | raw | OIDN, refreshing | one last refresh |
+| `'oidn'` | `true` | raw | OIDN, refreshing | OIDN, full quality |
+
+`denoiser.enabled` is the union of the two — "OIDN is in use at all", which is what the aux G-buffer
+wiring needs — so read the two decisions back from `denoisingManager.denoiserStrategy` and
+`denoisingManager.finalDenoise`, not from it.
+
+With OIDN on the live view and the final pass off, the render still closes with one more refresh: the
+cadence's last tick lands short of the end, and the picture should match the render that finished. On
+a 150-sample render that gap measured **11 samples at 512²** and **1 at 1024²** — larger where the
+renderer is fast, because more samples land between refreshes. It uses whatever model the refreshes
+were already on: no reload for an image the user never asked to be denoised at full quality.
+
+In the app that is `Real-Time Denoiser` (None / EdgeAware / ASVGF / NRD / **OIDN (AI)**) and the
+`Final Denoise (OIDN)` switch. Deterministic mode pins the live refreshes off, since which frame a
+wall-clock cadence lands on is not reproducible.
+
+Leaving the live view raw is not just "denoising off" — it is the only way to see the true noise
+level, which is how you judge whether a render has actually settled. That is row one and row two.
+
+#### Quality while it runs vs. quality when it finishes
+
+`oidnQuality` is **the quality of the finished image**. The refreshes along the way use the cheapest
+model that reads the same kind of aux buffer, and the chosen model is put back for the last denoise:
+
+| `oidnQuality` | refreshes use | finished image |
+|---|---|---|
+| `fast` | `fast` | `fast` |
+| `fast-clean` / `balance` / `high` | `fast-clean` | as chosen |
+
+Two constraints shape that table, and neither is optional:
+
+- **The aux kind must not change mid-render.** `setCleanAuxNormal()` throws away the accumulated
+  albedo/normal, so a refresh model that disagreed with the final one would leave the final denoise
+  reading an aux buffer one sample deep. That is why the cheap model is `fast-clean` and not `fast`.
+- **Switching models reloads the weights, ~1 s.** So it happens at most once per render, and only
+  once a denoise has actually measured too slow to be a live view (`> 120 ms`). A tier a machine can
+  afford is kept — at 512² that is every tier. The verdict survives a camera move, because the
+  device does not get faster between them; it is re-taken when the tier or the resolution changes.
+
+#### What paces the refreshes
+
+Two knobs with two different jobs, and the gap between refreshes is whichever is larger:
+
+- **The cost floor protects the renderer.** The gap is at least twice what the last denoise actually
+  cost, so denoising never takes more than about half the wall clock, at any resolution, on any GPU.
+  This is not configurable, and it is what binds at the default.
+- **`continuousDenoiseInterval` caps the refresh rate in absolute terms**, for a host that wants
+  fewer updates than the renderer could afford — a laptop on battery, or a viewport where 30 updates
+  a second is distracting. The default (8 ms) is below any real denoise cost, so it never binds:
+  refreshes run as often as the cost floor allows. Raising it gives a flat `1000 / interval` cap.
+
+Measured, `fast` model:
+
+| `continuousDenoiseInterval` | 8 | 50 | 100 | 200 | 400 |
+|---|---|---|---|---|---|
+| 512² (denoise 12 ms) | 35/sec | 18/sec | 9.6/sec | 4.9/sec | 2.6/sec |
+| 1024² (denoise 50 ms) | 9/sec | 9/sec | 9/sec | 4.9/sec | 2.6/sec |
+
+The two columns converge once the interval is the larger of the two — below that the cost floor is
+holding 1024² down to 9/sec regardless of what the interval says.
+
+A fixed millisecond interval cannot do this job: the same `fast` model measures 14 ms at 512², 48 ms
+at 1024² and ~800 ms at 2048². Measured where the GPU is saturated (1536²), the multiplier is the
+whole trade — 1x gives 1.6 refreshes/sec at 62 % of the sample rate, 2x gives 0.8/sec at 89 %, 3x
+gives 0.6/sec at 97 %.
+
+This replaced a sample-growth gate (refresh only once the sample count had grown 1.4x), which was
+written when a denoise cost 100-330 ms. Once the output pack moved to the GPU and a denoise got
+cheap, that gate only cost refreshes: removing it took 512² from 2 to 31 refreshes/sec and 1024²
+from 2 to 8.9, both at an unchanged sample rate, while 1536² and 2048² did not move at all because
+the cost floor already bound there. Refreshing faster is also *smoother*, not shimmerier — less
+changes underneath between refreshes.
+
+Nothing runs while the camera is moving; the raw frame shows during navigation.
+
+Cadence runs are tagged so a host can tell them apart from the denoise that ends a render:
+
+```js
+engine.addEventListener(EngineEvents.DENOISING_END, e => {
+  if (e.continuous) return;   // a background refresh, not the final image
+  saveResult();
+});
+```
+
 `'fast'` and `'fast-clean'` are the same network size and cost the same to run; they differ only in
 which auxiliary guide their weights expect. That makes the ordering **not** a simple quality ladder:
 at 1 spp the accumulated guide has one sample, so `'fast-clean'` is fed something it was not trained