rayzee 7.18.0 → 7.19.1

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 );
+
+	}
+
+}

package/src/managers/helpers/overlaySurface.js

@@ -0,0 +1,53 @@
+/**
+ * Shared plumbing for the overlay canvases stacked over the main WebGPU canvas
+ * (the 3D scene layer and the 2D HUD). Both must agree on positioning and on
+ * how an on-screen box maps to device pixels, so both come from here.
+ */
+
+/** Beyond 2× the extra pixels are invisible but the cost is not. */
+export const MAX_VIEW_DPR = 2;
+
+/**
+ * Creates a transparent, click-through canvas that covers its container.
+ * @param {boolean} [hidden=false] - Start parked (`display:none`)
+ * @returns {HTMLCanvasElement}
+ */
+export function createOverlayCanvas( hidden = false ) {
+
+	const canvas = document.createElement( 'canvas' );
+	canvas.style.cssText = 'position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;'
+		+ ( hidden ? 'display:none;' : '' );
+	return canvas;
+
+}
+
+/**
+ * Device-pixel size of an element as it actually appears on screen. Uses the
+ * bounding rect (not clientWidth) so the viewport's CSS zoom is included.
+ *
+ * @param {HTMLElement} element
+ * @param {number} [maxDim=Infinity] - Per-axis ceiling; the box is scaled down uniformly to fit
+ * @returns {{ width: number, height: number }|null} null when the element has no layout box
+ */
+export function viewPixelSize( element, maxDim = Infinity ) {
+
+	const rect = element?.getBoundingClientRect();
+	if ( ! rect || rect.width === 0 || rect.height === 0 ) return null;
+
+	const dpr = Math.min( window.devicePixelRatio || 1, MAX_VIEW_DPR );
+	let width = Math.round( rect.width * dpr );
+	let height = Math.round( rect.height * dpr );
+
+	// Uniform scale — a per-axis clamp would skew the aspect and slide the
+	// helpers out of alignment with the rendered image underneath.
+	const clamp = maxDim / Math.max( width, height );
+	if ( clamp < 1 ) {
+
+		width = Math.max( 1, Math.round( width * clamp ) );
+		height = Math.max( 1, Math.round( height * clamp ) );
+
+	}
+
+	return { width, height };
+
+}