rayzee 7.17.0 → 7.19.0

package/src/managers/OverlayManager.js

@@ -1,21 +1,34 @@
 import { TileHelper } from './helpers/TileHelper.js';
 import { OutlineHelper } from './helpers/OutlineHelper.js';
+import { ViewOverlayRenderer } from './helpers/ViewOverlayRenderer.js';
+import { createOverlayCanvas, viewPixelSize } from './helpers/overlaySurface.js';
+import { createLogger } from '../utils/Logger.js';
+
+const log = createLogger( 'overlay' );
+
+/** Whether a helper wants to draw into the given layer this frame. */
+const drawsOn = ( helper, layer ) => helper.visible && helper.layer === layer && helper.render;
 
 /**
  * OverlayManager — Unified overlay system for visual helpers.
  *
- * Two rendering layers:
- *   1. **HelperScene** — A Three.js Scene rendered on top of the WebGPU backbuffer
- *      (light gizmos, bounding boxes, outlines). Renders at display resolution.
+ * Two rendering layers, both sized to the **view** (what the user sees on
+ * screen) rather than to the path tracer's render resolution:
+ *   1. **Scene layer** — Three.js content (light gizmos, transform gizmo,
+ *      selection outline) drawn by {@link ViewOverlayRenderer} into its own
+ *      transparent canvas stacked over the main one.
  *   2. **HUDCanvas** — A 2D `<canvas>` element overlaid via CSS for screen-space
- *      elements (AF points, debug labels). Completely separate
- *      from the WebGPU canvas, so it is never captured in saved images.
+ *      elements (denoise/upscale tile progress).
+ *
+ * Neither layer touches the main canvas, so helpers can never be captured in a
+ * saved image.
  *
  * Helpers are registered by name and implement a simple interface:
  *   { update?(), render?(ctx, w, h), show(), hide(), dispose(), visible, layer }
  *
  * @example
- *   const overlay = new OverlayManager( renderer, camera );
+ *   const overlay = new OverlayManager( camera );
+ *   await overlay.initViewRenderer( { device, sizeSource: canvas } );
  *   overlay.register( 'outline', new OutlineHelper() );
  *   overlay.show( 'outline' );
  *   // in animate():
@@ -24,25 +37,51 @@ import { OutlineHelper } from './helpers/OutlineHelper.js';
 export class OverlayManager {
 
 	/**
-	 * @param {import('three/webgpu').WebGPURenderer} renderer
 	 * @param {import('three').PerspectiveCamera} camera
 	 */
-	constructor( renderer, camera ) {
+	constructor( camera ) {
 
-		this.renderer = renderer;
 		this.camera = camera;
 
 		/** @type {Map<string, Object>} */
 		this._helpers = new Map();
 
 		// ── HUD Canvas (2D overlay) ──
-		this._hudCanvas = document.createElement( 'canvas' );
-		this._hudCanvas.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;';
+		this._hudCanvas = createOverlayCanvas();
 		this._hudCtx = this._hudCanvas.getContext( '2d' );
 
 		// ── HelperScene reference (set via setHelperScene) ──
 		this._helperScene = null;
 
+		/** @type {ViewOverlayRenderer|null} */
+		this._viewOverlay = null;
+
+	}
+
+	/**
+	 * Creates the view-resolution surface the scene layer draws into. On failure
+	 * the scene layer stays off rather than degrading onto the main backbuffer —
+	 * drawing there would bake helpers into saved images.
+	 *
+	 * @param {Object} config
+	 * @param {GPUDevice} config.device - Shared with the main renderer
+	 * @param {HTMLElement} config.sizeSource - Element whose on-screen box defines the size
+	 */
+	async initViewRenderer( { device, sizeSource } ) {
+
+		if ( ! device || ! sizeSource ) return;
+
+		try {
+
+			this._viewOverlay = await new ViewOverlayRenderer().init( { device, sizeSource } );
+
+		} catch ( err ) {
+
+			log.error( 'overlay surface unavailable — light gizmos, transform gizmo and outlines are disabled', err );
+			this._viewOverlay = null;
+
+		}
+
 	}
 
 	/**
@@ -67,14 +106,19 @@ export class OverlayManager {
 	}
 
 	/**
-	 * Mounts the HUD canvas into the given container. Idempotent — safe to call
-	 * multiple times; re-mounts only when the parent differs.
+	 * Mounts the overlay canvases into the given container. Idempotent — safe to
+	 * call multiple times; re-mounts only when the parent differs. The 3D surface
+	 * goes in first so the HUD stacks above it.
 	 * @param {HTMLElement} container
 	 */
 	mount( container ) {
 
-		if ( ! container || this._hudCanvas.parentElement === container ) return;
-		container.appendChild( this._hudCanvas );
+		if ( ! container ) return;
+
+		const viewCanvas = this._viewOverlay?.canvas;
+		if ( viewCanvas && viewCanvas.parentElement !== container ) container.appendChild( viewCanvas );
+
+		if ( this._hudCanvas.parentElement !== container ) container.appendChild( this._hudCanvas );
 
 	}
 
@@ -116,7 +160,7 @@ export class OverlayManager {
 		this._wireDenoiserTileEvents( tileHelper, denoisingManager );
 
 		// ── Outline helper ──
-		const outlineHelper = new OutlineHelper( this.renderer, meshScene, this.camera );
+		const outlineHelper = new OutlineHelper( meshScene, this.camera );
 		this.register( 'outline', outlineHelper );
 
 	}
@@ -170,7 +214,7 @@ export class OverlayManager {
 
 		if ( this._helpers.has( name ) ) {
 
-			console.warn( `OverlayManager: helper "${name}" already registered — replacing.` );
+			log.warn( `helper "${name}" already registered — replacing.` );
 			this._helpers.get( name ).dispose?.();
 
 		}
@@ -259,42 +303,54 @@ export class OverlayManager {
 	 */
 	render() {
 
-		// 1. Render 3D HelperScene overlay (light gizmos, etc.)
-		if ( this._helperScene ) {
+		const overlay = this._viewOverlay;
 
-			this._helperScene.render( this.renderer, this.camera );
+		if ( overlay ) {
 
-		}
-
-		// 2. Render scene-layer helpers (outline, etc.)
-		for ( const helper of this._helpers.values() ) {
+			const hasSceneOverlay = this._hasVisibleSceneOverlay();
 
-			if ( helper.visible && helper.layer === 'scene' && helper.render ) {
+			if ( hasSceneOverlay || overlay.isVisible ) {
 
-				helper.render( this.renderer, this.camera );
+				overlay.syncSize();
+				// Doubles as the wipe of last frame's content when parking.
+				overlay.begin();
+				if ( hasSceneOverlay ) this._renderSceneLayer( overlay.renderer );
+				overlay.setVisible( hasSceneOverlay );
 
 			}
 
 		}
 
-		// 3. Draw HUD canvas (2D helpers)
 		this.refreshHUD();
 
 	}
 
-	/**
-	 * Forwards display dimensions to helpers that need resize.
-	 * @param {number} width - Display width in pixels
-	 * @param {number} height - Display height in pixels
-	 */
-	setSize( width, height ) {
+	/** Draws the helper scene + every visible scene-layer helper. */
+	_renderSceneLayer( renderer ) {
+
+		this._helperScene?.render( renderer, this.camera );
+
+		for ( const helper of this._helpers.values() ) {
+
+			if ( drawsOn( helper, 'scene' ) ) helper.render( renderer, this.camera );
+
+		}
+
+	}
+
+	/** Whether anything at all wants to draw into the scene layer this frame. */
+	_hasVisibleSceneOverlay() {
+
+		if ( this._helperScene?.isDrawing ) return true;
 
 		for ( const helper of this._helpers.values() ) {
 
-			helper.setSize?.( width, height );
+			if ( drawsOn( helper, 'scene' ) ) return true;
 
 		}
 
+		return false;
+
 	}
 
 	/**
@@ -310,7 +366,7 @@ export class OverlayManager {
 		let hasVisibleHUD = false;
 		for ( const helper of this._helpers.values() ) {
 
-			if ( helper.visible && helper.layer === 'hud' && helper.render ) {
+			if ( drawsOn( helper, 'hud' ) ) {
 
 				hasVisibleHUD = true;
 				break;
@@ -326,30 +382,28 @@ export class OverlayManager {
 
 		}
 
-		const dpr = window.devicePixelRatio || 1;
+		// Helpers draw in CSS-pixel coordinates of the unscaled layout box; the
+		// backing store is sized off the on-screen box, so nothing is drawn below
+		// view resolution.
 		const displayW = canvas.clientWidth;
 		const displayH = canvas.clientHeight;
-		const pixelW = Math.round( displayW * dpr );
-		const pixelH = Math.round( displayH * dpr );
+		const size = displayW > 0 && displayH > 0 ? viewPixelSize( canvas ) : null;
+		if ( ! size ) return;
 
-		if ( canvas.width !== pixelW || canvas.height !== pixelH ) {
+		if ( canvas.width !== size.width || canvas.height !== size.height ) {
 
-			canvas.width = pixelW;
-			canvas.height = pixelH;
+			canvas.width = size.width;
+			canvas.height = size.height;
 
 		}
 
-		ctx.clearRect( 0, 0, pixelW, pixelH );
+		ctx.clearRect( 0, 0, size.width, size.height );
 		ctx.save();
-		ctx.scale( dpr, dpr );
+		ctx.scale( size.width / displayW, size.height / displayH );
 
 		for ( const helper of this._helpers.values() ) {
 
-			if ( helper.visible && helper.layer === 'hud' && helper.render ) {
-
-				helper.render( ctx, displayW, displayH );
-
-			}
+			if ( drawsOn( helper, 'hud' ) ) helper.render( ctx, displayW, displayH );
 
 		}
 
@@ -372,6 +426,9 @@ export class OverlayManager {
 
 		this._helpers.clear();
 
+		this._viewOverlay?.dispose();
+		this._viewOverlay = null;
+
 		if ( this._hudCanvas.parentElement ) {
 
 			this._hudCanvas.parentElement.removeChild( this._hudCanvas );

package/src/managers/UniformManager.js

@@ -164,13 +164,13 @@ export class UniformManager {
 		u( 'maxSamples', DEFAULT_STATE.maxSamples, 'int' );
 		u( 'transmissiveBounces', DEFAULT_STATE.transmissiveBounces, 'int' );
 		u( 'maxSubsurfaceSteps', DEFAULT_STATE.maxSubsurfaceSteps, 'int' );
+		u( 'maxTransparentBounces', DEFAULT_STATE.maxTransparentBounces, 'int' );
 		u( 'visMode', DEFAULT_STATE.debugMode, 'int' );
 		u( 'debugVisScale', DEFAULT_STATE.debugVisScale, 'float' );
 
 		// Tier-1 convergence early-stop (FinalWrite reads these; live-toggled, no shader rebuild)
 		ub( 'useAdaptiveSampling', DEFAULT_STATE.useAdaptiveSampling );
 		u( 'noiseThreshold', DEFAULT_STATE.noiseThreshold, 'float' );
-		u( 'darkNoiseFloor', DEFAULT_STATE.darkNoiseFloor, 'float' );
 		u( 'adaptiveMinSamples', DEFAULT_STATE.adaptiveMinSamples, 'int' );
 		// CPU-only (read in PathTracer._isConvergedComplete, not bound to any kernel); registered here for
 		// the settings/configureForMode plumbing + the _defineUniformGetters accessor.

package/src/managers/helpers/OutlineHelper.js

@@ -1,49 +1,43 @@
 import { outline } from 'three/addons/tsl/display/OutlineNode.js';
 import { MeshBasicNodeMaterial, QuadMesh } from 'three/webgpu';
-import { AdditiveBlending, Color } from 'three';
+import { AddEquation, Color, CustomBlending, OneFactor } from 'three';
 import { uniform, vec4 } from 'three/tsl';
 
 /**
  * OutlineHelper — Renders selection outlines as a post-pipeline overlay.
  *
  * Uses Three.js OutlineNode internally but renders to a separate fullscreen
- * quad with additive blending, composited on top of the Display output.
- * Renders at **display resolution** (not render resolution), so outlines
- * stay sharp regardless of path tracer resolution scaling.
+ * quad, composited on top of the path traced image. Drawn by OverlayManager's
+ * scene layer, which runs at **view resolution** — so outlines stay a crisp
+ * screen-space width regardless of the path tracer's render resolution.
+ *
+ * The quad is additive, but writes coverage into alpha (rather than a constant
+ * 1.0) so it composites correctly onto the transparent overlay surface instead
+ * of turning the whole frame opaque.
  *
  * Layer: 'scene' (rendered by OverlayManager's 3D pass, not HUD canvas).
  *
  * @example
- *   const outlineHelper = new OutlineHelper( renderer, meshScene, camera );
+ *   const outlineHelper = new OutlineHelper( meshScene, camera );
  *   overlayManager.register( 'outline', outlineHelper );
  *   outlineHelper.setSelectedObjects( [ mesh ] );
  */
 export class OutlineHelper {
 
-	constructor( renderer, scene, camera ) {
+	constructor( scene, camera ) {
 
 		this.layer = 'scene';
-		this.visible = true;
+		this._enabled = true;
 
-		// Outline node (handles its own multi-pass rendering via updateBefore)
+		// Outline node (handles its own multi-pass rendering via updateBefore).
+		// It sizes its render targets from the drawing buffer of whatever renderer
+		// draws it — the view overlay surface — so no size override is needed.
 		this._outlineNode = outline( scene, camera, {
 			selectedObjects: [],
 			edgeThickness: uniform( 1.0 ),
 			edgeGlow: uniform( 0.0 ),
 		} );
 
-		// OutlineNode calls its own setSize() internally during updateBefore()
-		// with the renderer's current render target size. Override to force
-		// display resolution so outlines stay sharp at any render scale.
-		this._displayWidth = 1;
-		this._displayHeight = 1;
-		const origSetSize = this._outlineNode.setSize.bind( this._outlineNode );
-		this._outlineNode.setSize = () => {
-
-			origSetSize( this._displayWidth, this._displayHeight );
-
-		};
-
 		// Build the outline color from visible + hidden edges
 		const edgeStrength = uniform( 3.0 );
 		const visibleEdgeColor = uniform( new Color( 0xffffff ) );
@@ -53,10 +47,21 @@ export class OutlineHelper {
 			.add( hiddenEdge.mul( hiddenEdgeColor ) )
 			.mul( edgeStrength );
 
-		// Fullscreen quad with additive blending — composites outline on top
+		const coverage = outlineColorNode.r.max( outlineColorNode.g ).max( outlineColorNode.b ).clamp( 0.0, 1.0 );
+
+		// Fullscreen quad, premultiplied-additive: dst.rgb += src.rgb, dst.a += src.a.
+		// Spelled out rather than AdditiveBlending + premultipliedAlpha, because the
+		// latter also makes NodeMaterial multiply rgb by alpha — squaring a soft edge.
 		this._material = new MeshBasicNodeMaterial();
-		this._material.colorNode = vec4( outlineColorNode, 1.0 );
-		this._material.blending = AdditiveBlending;
+		this._material.colorNode = vec4( outlineColorNode, coverage );
+		this._material.transparent = true;
+		this._material.blending = CustomBlending;
+		this._material.blendEquation = AddEquation;
+		this._material.blendSrc = OneFactor;
+		this._material.blendDst = OneFactor;
+		this._material.blendEquationAlpha = AddEquation;
+		this._material.blendSrcAlpha = OneFactor;
+		this._material.blendDstAlpha = OneFactor;
 		this._material.toneMapped = false;
 		this._material.depthTest = false;
 		this._material.depthWrite = false;
@@ -75,13 +80,23 @@ export class OutlineHelper {
 
 	}
 
+	/**
+	 * Nothing selected means nothing to draw — reported here so the overlay
+	 * surface can stay parked instead of clearing every frame.
+	 */
+	get visible() {
+
+		return this._enabled && this._outlineNode.selectedObjects.length > 0;
+
+	}
+
 	/**
 	 * Renders the outline overlay onto the current backbuffer.
 	 * Called by OverlayManager after Display has rendered.
 	 */
 	render( renderer ) {
 
-		if ( this._outlineNode.selectedObjects.length === 0 ) return;
+		if ( ! this.visible ) return;
 
 		const prevAutoClear = renderer.autoClear;
 		renderer.autoClear = false;
@@ -91,34 +106,21 @@ export class OutlineHelper {
 
 	}
 
-	/**
-	 * Updates internal render target sizes.
-	 * @param {number} width - Display width in pixels
-	 * @param {number} height - Display height in pixels
-	 */
-	setSize( width, height ) {
-
-		this._displayWidth = width;
-		this._displayHeight = height;
-		this._outlineNode.setSize( width, height );
-
-	}
-
 	show() {
 
-		this.visible = true;
+		this._enabled = true;
 
 	}
 
 	hide() {
 
-		this.visible = false;
+		this._enabled = false;
 
 	}
 
 	dispose() {
 
-		this.visible = false;
+		this._enabled = false;
 		this._outlineNode?.dispose();
 		this._material?.dispose();
 		// QuadMesh extends Mesh — no dispose method on the mesh itself;

package/src/managers/helpers/TransformGizmoHelper.js

@@ -0,0 +1,61 @@
+/**
+ * TransformGizmoHelper — adapts {@link TransformManager} to the OverlayManager
+ * helper interface so the translate/rotate/scale gizmo draws on the same
+ * view-resolution surface as the light gizmos and the selection outline.
+ *
+ * An adapter rather than the interface on TransformManager itself: the manager
+ * is public engine API with its own lifecycle (PathTracerApp owns dispose), and
+ * the overlay must not dispose it a second time.
+ *
+ * Layer: 'scene'.
+ *
+ * @example
+ *   overlayManager.register( 'transform', new TransformGizmoHelper( app.transformManager ) );
+ */
+export class TransformGizmoHelper {
+
+	/**
+	 * @param {import('../TransformManager.js').TransformManager} transformManager
+	 */
+	constructor( transformManager ) {
+
+		this.layer = 'scene';
+		this._transformManager = transformManager;
+		this._enabled = true;
+
+	}
+
+	/** Nothing to draw unless the gizmo is attached to something. */
+	get visible() {
+
+		return this._enabled && this._transformManager.attachedObject !== null;
+
+	}
+
+	render( renderer ) {
+
+		this._transformManager.render( renderer );
+
+	}
+
+	show() {
+
+		this._enabled = true;
+
+	}
+
+	hide() {
+
+		this._enabled = false;
+
+	}
+
+	dispose() {
+
+		// Only stops drawing — TransformManager is owned by the app, which
+		// disposes it separately.
+		this._enabled = false;
+
+	}
+
+}

package/src/managers/helpers/ViewOverlayRenderer.js

@@ -0,0 +1,140 @@
+import { WebGPURenderer } from 'three/webgpu';
+import { SRGBColorSpace } from 'three';
+import { disposeRenderer } from '../../Processor/utils.js';
+import { createOverlayCanvas, viewPixelSize, MAX_VIEW_DPR } from './overlaySurface.js';
+
+/** Device-pixel ceiling per axis — guards against huge surfaces at high viewport zoom. */
+const MAX_OVERLAY_DIM = 4096;
+
+/**
+ * ViewOverlayRenderer — a transparent canvas sized to what the user actually
+ * sees, driven by its own WebGPURenderer.
+ *
+ * The main canvas' backing store is the *render* resolution (512 in preview,
+ * up to 4K for a final render), and CSS stretches it to fit the viewport. Any
+ * helper drawn into that backbuffer inherits the render resolution and is then
+ * rescaled by the browser — soft gizmos at low render scale, wasted pixels at
+ * high. This surface instead matches the on-screen size (bounding rect × DPR,
+ * so the viewport zoom is included), so gizmos and outlines stay crisp and
+ * screen-space-correct at any render resolution.
+ *
+ * The renderer shares the main renderer's `GPUDevice`, so this costs a
+ * swapchain, not a second WebGPU context. Helpers rendered here are also
+ * physically absent from the main canvas, so they can never leak into a saved
+ * image.
+ *
+ * @example
+ *   const overlay = new ViewOverlayRenderer();
+ *   await overlay.init( { device: renderer.backend.device, sizeSource: canvas } );
+ *   container.appendChild( overlay.canvas );
+ *   // per frame:
+ *   overlay.syncSize();
+ *   overlay.begin();
+ *   helperScene.render( overlay.renderer, camera );
+ */
+export class ViewOverlayRenderer {
+
+	constructor() {
+
+		// Starts parked: three allocates the output-pass framebuffer (~30 MiB at
+		// 1600²) on the first clear, so a session that never shows a helper never
+		// pays for it.
+		this.canvas = createOverlayCanvas( true );
+		this._visible = false;
+
+		/** @type {import('three/webgpu').WebGPURenderer|null} */
+		this.renderer = null;
+
+		this._sizeSource = null;
+
+	}
+
+	/**
+	 * Creates the renderer on the shared device.
+	 *
+	 * @param {Object} config
+	 * @param {GPUDevice} config.device - Device to share with the main renderer
+	 * @param {HTMLElement} config.sizeSource - Element whose on-screen box defines the overlay size
+	 * @returns {Promise<ViewOverlayRenderer>}
+	 */
+	async init( { device, sizeSource } ) {
+
+		this._sizeSource = sizeSource;
+
+		// A second backend claims the device's single uncaptured-error slot during
+		// init(). Hand it back so the owner's handler keeps receiving errors.
+		const deviceErrorHandler = device.onuncapturederror;
+
+		// At DPR ≥ 2 the browser's downscale already supersamples the edges, so MSAA
+		// would only add a multisampled attachment for no visible gain. Below that
+		// there is nothing to hide jaggies, so pay for it.
+		const renderer = new WebGPURenderer( {
+			canvas: this.canvas,
+			device,
+			alpha: true,
+			antialias: ( window.devicePixelRatio || 1 ) < MAX_VIEW_DPR,
+		} );
+
+		await renderer.init();
+		device.onuncapturederror = deviceErrorHandler;
+
+		renderer.outputColorSpace = SRGBColorSpace;
+		renderer.setPixelRatio( 1.0 );
+		renderer.setClearColor( 0x000000, 0 );
+		// Every frame starts with an explicit clear() in begin(); helpers then
+		// stack on top of each other without wiping what came before.
+		renderer.autoClear = false;
+
+		this.renderer = renderer;
+		this.syncSize();
+
+		return this;
+
+	}
+
+	get isVisible() {
+
+		return this._visible;
+
+	}
+
+	/** Matches the backing store to the size source's on-screen box. */
+	syncSize() {
+
+		if ( ! this.renderer ) return;
+
+		const size = viewPixelSize( this._sizeSource, MAX_OVERLAY_DIM );
+		if ( ! size || ( size.width === this.canvas.width && size.height === this.canvas.height ) ) return;
+
+		this.renderer.setSize( size.width, size.height, false );
+
+	}
+
+	/** Clears the surface to fully transparent. Call once before drawing helpers. */
+	begin() {
+
+		if ( ! this.renderer ) return;
+
+		this.renderer.setRenderTarget( null );
+		this.renderer.clear();
+
+	}
+
+	setVisible( visible ) {
+
+		if ( this._visible === visible ) return;
+
+		this._visible = visible;
+		this.canvas.style.display = visible ? '' : 'none';
+
+	}
+
+	dispose() {
+
+		disposeRenderer( this.renderer );
+		this.renderer = null;
+		this.canvas.parentElement?.removeChild( this.canvas );
+
+	}
+
+}