rayzee 7.23.2 → 7.24.0

package/README.md

@@ -31,7 +31,9 @@ A real-time WebGPU path tracing engine built on Three.js. Framework-agnostic —
   - [engine.interactionManager](#engineinteractionmanager)
   - [engine.transformManager](#enginetransformmanager)
   - [Output Methods](#output-methods)
+  - [Render Resolution Reserve](#render-resolution-reserve)
   - [Memory Monitoring](#memory-monitoring)
+  - [Logging](#logging)
   - [Deterministic & Headless Rendering](#deterministic--headless-rendering)
   - [Events](#events)
   - [Advanced: Custom Pipeline Stages](#advanced-custom-pipeline-stages)
@@ -135,7 +137,7 @@ A single HTML file — no Node.js, no build step. Uses [ES module import maps](h
       "three/tsl": "https://cdn.jsdelivr.net/npm/three@0.185.0/build/three.tsl.js",
       "three/webgpu": "https://cdn.jsdelivr.net/npm/three@0.185.0/build/three.webgpu.js",
       "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.185.0/examples/jsm/",
-      "oidn-web": "https://cdn.jsdelivr.net/npm/oidn-web@0.3.5/dist/oidn.js",
+      "oidn-web": "https://cdn.jsdelivr.net/npm/oidn-web@0.4.0/dist/oidn.js",
       "rayzee": "https://cdn.jsdelivr.net/npm/rayzee/dist/rayzee.es.js"
     }
   }
@@ -594,6 +596,36 @@ URL.revokeObjectURL(url);
 
 ---
 
+### Render Resolution Reserve
+
+Every compute `StorageTexture` and aux buffer is pre-allocated at one square dimension — the *reserve* — and `setCanvasSize()` refuses anything larger. The default is 2048, so 4K output needs the reserve raised first.
+
+```js
+engine.setReservedRenderResolution(4096)          // raise to 4K (longest edge)
+engine.setReservedRenderResolution(2048, { allowLower: true })   // lower, paying a rebuild, to reclaim VRAM
+engine.getReservedRenderResolution()              // the reserve actually in force
+```
+
+The request is **device-capped**: a 4096 reserve pins roughly 1.5 GB of MRT textures, so it is only granted on GPUs reporting ≥ 8 GB and a ≥ 1 GB `maxStorageBufferBindingSize`; weaker devices clamp to 2048. `MAX_RESERVABLE_RENDER_SIZE` (4096) is the ceiling on any request.
+
+Raises are monotonic unless you pass `allowLower` — UI-driven callers ask for whatever the current view needs, and honouring every decrease made the reserve oscillate across preview↔render switches, paying a full kernel rebuild each time.
+
+Callable at any point in the lifecycle:
+
+- **Before `init()`** — recorded and applied during `init()`, after the device exists but before the stages are constructed, so they allocate at the raised size directly. The device gate cannot run without a device, so the return value here is the *request*, not the verdict.
+- **After `init()`** — applied immediately, re-initialising the reserved GPU storage in place.
+
+Either way the verdict arrives as a `reserved_render_size_changed` event (a plain string type, not an `EngineEvents` constant):
+
+```js
+engine.addEventListener('reserved_render_size_changed', e => console.log('reserve:', e.size));
+engine.setReservedRenderResolution(4096);
+await engine.init();
+console.log(engine.getReservedRenderResolution());   // 4096, or 2048 if the device declined
+```
+
+---
+
 ### Memory Monitoring
 
 Track GPU (VRAM) usage across the whole pipeline. Sizes are measured from live GPU resources (buffer `byteLength` + texture dimensions × format), so they are exact, not estimated.
@@ -612,6 +644,27 @@ The React app surfaces this as a `Memory: … | Peak: …` readout in the on-can
 
 ---
 
+### Logging
+
+Leveled, namespaced console output, shared with the engine's Web Workers. The default level is `info`, which hides per-mesh and per-texture detail; drop to `debug` to see it.
+
+```js
+import { Logger, createLogger, fmt, LOG_LEVELS } from 'rayzee';
+
+Logger.setLevel('debug');       // 'silent' | 'error' | 'warn' | 'info' | 'debug'
+Logger.getLevel();
+Logger.isEnabled('debug');      // gate expensive message construction
+Logger.only('bvh', 'gpu');      // restrict debug to these namespaces (implies setLevel('debug'))
+Logger.only();                  // clear the namespace filter
+Logger.refresh();               // re-read the level from globals/localStorage
+```
+
+The chosen level persists in `localStorage` under `rayzeeLogLevel` (namespace filter: `rayzeeLogNamespaces`), so it survives a reload. The engine does not install a global itself — expose one from your host if you want console access without an import; the demo app does `globalThis.rayzee = { log: Logger, ... }`, which is what makes `rayzee.log.setLevel('debug')` work there.
+
+`createLogger(namespace)` returns a channel with `error` / `warn` / `info` / `debug` plus `summary(headline, details)`, which prints one `info` line with the detail lines folded into a collapsed group. `fmt` holds the formatting helpers those summaries use — `n`, `ms`, `mb`, `px`, `count`, `list`. `LOG_LEVELS` is the name→severity map.
+
+---
+
 ### Deterministic & Headless Rendering
 
 For offline rendering, regression testing, and benchmarking — drive accumulation yourself instead of the rAF loop, and get bit-reproducible output.
@@ -645,6 +698,19 @@ WebGPU timestamp queries are the only true GPU metric here — `pipeline.getStat
 
 `getKernelGPUTimings()` attributes each compute pass of the last resolved frame back to a wavefront kernel name. Durations are **summed per kernel across the frame**, so `extend` reports its whole per-frame cost over every bounce iteration, not one bounce. `unattributed` collects passes belonging to no registered kernel (other stages, denoisers), so `sum(kernels) + unattributed` reconciles with `total`.
 
+Neither method can see the OIDN denoise — `oidn-web` submits on its own command encoders, outside
+the stages three.js times. It carries its own profiler instead:
+
+```js
+engine.profileNextDenoise();                          // arms one capture; per-denoise, not sticky
+const { profile, runtime } = await engine.getDenoiseProfile();
+```
+
+`profile` is the per-layer GPU timing of that denoise; `runtime` reports the selected engine and
+precision, the model, kernel capabilities, tile state and resource counts — which is the way to
+confirm FP16 actually engaged on a given GPU rather than inferring it from the device's feature
+list. Both need `timestamp-query`, and `getDenoiseProfile()` returns `null` when OIDN is not set up.
+
 ---
 
 ### Events
@@ -724,8 +790,12 @@ import {
   MEMORY_CONSTANTS,
   PRODUCTION_RENDER_CONFIG,
   INTERACTIVE_RENDER_CONFIG,
+  MAX_RESERVABLE_RENDER_SIZE,
 } from 'rayzee';
 
+// Leveled/namespaced logging, shared with the workers
+import { Logger, createLogger, fmt, LOG_LEVELS } from 'rayzee';
+
 // Asset URL / cache namespace overrides
 import { configureAssets, getAssetConfig } from 'rayzee';
 
@@ -767,7 +837,7 @@ import { setBindingAudit, getBindingAuditFindings, clearBindingAuditFindings } f
 
 | Package | Purpose | Install needed? |
 |---|---|---|
-| `oidn-web` | Intel Open Image Denoise for high-quality final renders | Yes — `npm install oidn-web` |
+| `oidn-web` | Intel Open Image Denoise for high-quality final renders | Yes — `npm install oidn-web` (**>=0.4.0**) |
 | `onnxruntime-web` | AI-powered upscaling | No — loaded from CDN at runtime |
 
 > **Note:** `onnxruntime-web` is also listed in `package.json` under `optionalDependencies` for bundler compatibility, but the engine's own runtime path always fetches it from a CDN (see `ortRuntimeUrl` / `ortWasmPaths` in [Configuring Assets](#configuring-assets-cdn-urls--cache-namespace)) rather than importing the installed package — installing it locally has no effect unless you also override those URLs to point at your own copy.
@@ -787,7 +857,7 @@ OIDN provides high-quality AI denoising for final renders. It runs automatically
    ```js
    // After engine.init() completes
    engine.denoisingManager.setOIDNEnabled(true);
-   engine.denoisingManager.setOIDNQuality('balance'); // 'fast' | 'balance' | 'high'
+   engine.denoisingManager.setOIDNQuality('balance'); // 'fast' | 'fast-clean' | 'balance' | 'high'
    ```
 
 3. **Listen for progress** (optional)
@@ -801,11 +871,27 @@ OIDN provides high-quality AI denoising for final renders. It runs automatically
    });
    ```
 
-| Quality | Model size | Speed | Best for |
+| Quality | Weights | Aux guide | Best for |
 |---|---|---|---|
-| `'fast'` | ~20 MB | Fastest | Quick previews |
-| `'balance'` | ~50 MB | Moderate | General use (default) |
-| `'high'` | ~100 MB | Slowest | Final quality renders |
+| `'fast'` | 0.6 MB | point-sampled | Low sample counts — the default |
+| `'fast-clean'` | 0.6 MB | accumulated | Converged frames, at `'fast'`'s cost |
+| `'balance'` | 1.8 MB | accumulated | General use |
+| `'high'` | 7.3 MB | accumulated | Final renders — used by `configureForMode('production')` |
+
+`'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
+for and measures materially worse than `'fast'` (on a transmission-heavy scene, more than double the
+RMSE). Once the guide converges it wins by a few percent — but `'high'` beats it there anyway. Pick
+`'fast'` for previews and `'high'` for output; `'fast-clean'` is for the narrow case of denoising a
+converged frame on a budget.
+
+Denoise cost scales with frame area, and the tile tracks the frame so that a frame fitting inside one
+tile pays no overlap padding — at 1024x1024 that is roughly 1.8x faster than tiling it. A cap
+(default 1024) bounds the one-time activation allocation, so larger frames tile and stay
+memory-bounded. Raise or lower it with
+`engine.denoisingManager.denoiser.updateConfiguration({ tileSize: 2048 })`; the effective tile is
+`min( max( width, height ), tileSize )`.
 
 > **Note:** The neural network model is downloaded on first use. Subsequent runs use the browser cache. OIDN also works with `configureForMode('production')`, which enables it automatically alongside high-quality render settings.
 
@@ -851,21 +937,14 @@ Then load it via a script tag or import map instead:
 <script type="importmap">
 {
   "imports": {
-    "oidn-web": "https://cdn.jsdelivr.net/npm/oidn-web@0.3.5/dist/oidn.js"
+    "oidn-web": "https://cdn.jsdelivr.net/npm/oidn-web@0.4.0/dist/oidn.js"
   }
 }
 </script>
 ```
 
-**OIDN: `TypeError: t.alea is not a function` or `Argument 'x' passed to 'conv2d' must be a Tensor ... got 'L'`**
-You're loading `oidn-web` via `jsdelivr.net/npm/oidn-web/+esm` or `esm.sh/oidn-web`. Don't — use the **self-bundled** `/dist/oidn.js` path instead:
-
-```diff
-- "oidn-web": "https://cdn.jsdelivr.net/npm/oidn-web@0.3.5/+esm"
-+ "oidn-web": "https://cdn.jsdelivr.net/npm/oidn-web@0.3.5/dist/oidn.js"
-```
-
-Why: `oidn-web` transitively depends on `@tensorflow/tfjs-core`, which does `import * as t from "seedrandom"` and calls `t.alea(...)`. jsDelivr's `/+esm` CJS→ESM shim of `seedrandom` emits only `export default` (no named exports), so `t.alea` is undefined. Swapping to `esm.sh` trades that for a different issue: deep-path imports produce multiple tfjs-core instances, so a Tensor made in one module fails `instanceof` checks in another (`got 'L'`). The `/dist/oidn.js` file in the npm package is a single pre-bundled ESM with all of tfjs inlined — no external imports, one tfjs instance, same exports. Use it.
+**OIDN from a CDN**
+Load the self-bundled `/dist/oidn.js` path rather than `/+esm` or `esm.sh` — it is a single pre-bundled ESM with no external imports, and it is the path this engine is tested against.
 
 **Black screen / "WebGPU not supported"**
 Your browser may not support WebGPU. Use Chrome 113+, Edge 113+, Safari 18+, or Firefox 141+. Ensure you're on HTTPS or localhost.