@wave3d/core 0.4.1 → 0.5.0

package/dist/renderer/WaveRenderer.js

@@ -13,15 +13,46 @@ import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js"
 //#region src/renderer/WaveRenderer.ts
 const BASE_SEGMENTS = 220;
 /** Reference frame (world units) the orthographic camera fills at cameraZoom 1. The wave is
-*  framed by COVERING this FRAME_W × FRAME_H rectangle (centred on cameraTarget) into the canvas
-*  — scaled to fill both dimensions, cropping the aspect overflow — so a given cameraZoom /
-*  cameraTarget frames the wave the SAME at any canvas size or aspect (only the cropped margin
-*  differs). FRAME_H = FRAME_W / (16/9) makes the reference a 16:9 rectangle; for canvases wider
-*  than that the width binds, narrower ones zoom in to fill instead of
-*  showing empty bands. This is what makes a saved preset reproduce on anyone's screen. */
+*  framed by mapping this FRAME_W × FRAME_H rectangle (centred on cameraTarget) onto the canvas,
+*  so a given cameraZoom / cameraTarget frames the wave the SAME at any canvas size or aspect
+*  (only the margin differs). FRAME_H = FRAME_W / (16/9) makes the reference a 16:9 rectangle.
+*  This is what makes a saved preset reproduce on anyone's screen. See {@link frameZoom} for how
+*  a canvas of a different aspect is reconciled against it. */
 const FRAME_W = 1333;
 const FRAME_H = 750;
 /**
+* The responsive base zoom: how many device pixels one world unit occupies so the FRAME_W × FRAME_H
+* reference lands on a `dw × dh` (device px) canvas under `fit`, then clamped so at least
+* `minVisibleWidth` of the frame's width survives.
+*
+* Shared by the renderer (which applies it) and the studio (which inverts it to persist a
+* scroll-zoom back into config.cameraZoom) — one implementation, so the two cannot drift.
+*
+* The clamp is a pure zoom CEILING layered on top of the fit, which is what lets both knobs
+* coexist: it can only widen the view, never tighten it, so it is inert for `contain`/`width`
+* (already at or below that zoom) and bites exactly where the crop hurts — `cover`/`height` on a
+* canvas narrower than 16:9. `minVisibleWidth` 0 disables it and restores pure-fit behaviour.
+*/
+function frameZoom(dw, dh, fit, minVisibleWidth = 0) {
+	const byWidth = dw / FRAME_W;
+	const byHeight = dh / 750;
+	let zoom;
+	switch (fit) {
+		case "contain":
+			zoom = Math.min(byWidth, byHeight);
+			break;
+		case "width":
+			zoom = byWidth;
+			break;
+		case "height":
+			zoom = byHeight;
+			break;
+		default: zoom = Math.max(byWidth, byHeight);
+	}
+	if (minVisibleWidth > 0) zoom = Math.min(zoom, dw / (FRAME_W * minVisibleWidth));
+	return zoom;
+}
+/**
 * Per-wave 2D palette texture (+ optional looping video). One instance per wave, so each
 * wave carries its own palette. Guarded by a signature so it only rebuilds when that wave's
 * palette actually changes (not every refresh).
@@ -201,6 +232,11 @@ var WaveRenderer = class {
 	resizeObserver;
 	intersectionObserver;
 	motionQuery;
+	/** Re-armed at the live devicePixelRatio on every change — see watchDpr(). */
+	dprQuery;
+	/** Pending coalesced resize (0 = none), and the metrics the last resize() actually applied. */
+	resizeRaf = 0;
+	lastResize;
 	capturing = false;
 	/** Fixed backing-buffer dimensions used by the studio's visible export frame. Embeds leave
 	*  this unset and continue to resize responsively with their container and device DPR. */
@@ -256,6 +292,7 @@ var WaveRenderer = class {
 		this.intersectionObserver.observe(container);
 		this.resizeObserver = new ResizeObserver(this.onResize);
 		this.resizeObserver.observe(container);
+		this.watchDpr();
 		this.applyBackground();
 		this.buildWaves();
 		this.resize();
@@ -1093,9 +1130,57 @@ var WaveRenderer = class {
 			this.halftoneCmykPass = void 0;
 		}
 	}
+	/** Coalesce observer-driven resizes to one per frame, and drop any that don't move a device pixel.
+	*
+	*  resize() is expensive — composer.setSize reallocates every pass's render target, and
+	*  applyBackground() rebuilds a container-sized canvas + texture for gradient/image backgrounds.
+	*  The old 1:1 `observe → resize()` paid that for observations that changed nothing: the observer
+	*  reports fractional content-box sizes, so sub-pixel layout shifts (and anything that rounds to
+	*  the same backing buffer) triggered a full reallocation, as did every observation while an
+	*  export frame is pinned and the container is not what drives the buffer at all.
+	*
+	*  Genuine per-frame changes — a mobile URL bar collapsing animates the container height — still
+	*  resize every frame. That work is necessary; the canvas would otherwise stretch. What is
+	*  removed is the redundant work, not the real work.
+	*
+	*  Only this path is throttled. `resize()` itself stays synchronous and unconditional — context
+	*  restore and setOutputSize must re-apply immediately, and on a fresh GPU context the metrics
+	*  are unchanged but the resources are not. */
 	onResize = () => {
+		if (this.resizeRaf) return;
+		this.resizeRaf = requestAnimationFrame(() => {
+			this.resizeRaf = 0;
+			const next = this.viewportMetrics();
+			const last = this.lastResize;
+			if (last && next.w === last.w && next.h === last.h && next.dpr === last.dpr) return;
+			this.resize();
+		});
+	};
+	/** Re-arm the DPR watch and re-render at the new device-pixel ratio.
+	*
+	*  ResizeObserver watches the CSS box only, so browser zoom or dragging the window to a monitor
+	*  with a different DPR changes devicePixelRatio without changing the box — the backing buffer
+	*  stayed at the old resolution and the wave went soft until something else forced a resize. */
+	onDprChange = () => {
+		this.watchDpr();
 		this.resize();
 	};
+	/** A `(resolution: Xdppx)` query only fires when we LEAVE the current ratio, so it is re-armed at
+	*  the new one on every change. */
+	watchDpr() {
+		this.dprQuery?.removeEventListener("change", this.onDprChange);
+		this.dprQuery = window.matchMedia(`(resolution: ${window.devicePixelRatio || 1}dppx)`);
+		this.dprQuery.addEventListener("change", this.onDprChange);
+	}
+	/** The backing-buffer metrics resize() will apply: the export frame when one is pinned, else the
+	*  container box at the (clamped) device-pixel ratio. */
+	viewportMetrics() {
+		return {
+			w: this.outputSize?.width ?? Math.max(1, this.container.clientWidth),
+			h: this.outputSize?.height ?? Math.max(1, this.container.clientHeight),
+			dpr: this.outputSize ? 1 : Math.min(window.devicePixelRatio || 1, this.config.dprMax)
+		};
+	}
 	onContextLost = (e) => {
 		e.preventDefault();
 		cancelAnimationFrame(this.rafId);
@@ -1111,9 +1196,12 @@ var WaveRenderer = class {
 		this.updateRunning();
 	};
 	resize() {
-		const w = this.outputSize?.width ?? Math.max(1, this.container.clientWidth);
-		const h = this.outputSize?.height ?? Math.max(1, this.container.clientHeight);
-		const dpr = this.outputSize ? 1 : Math.min(window.devicePixelRatio || 1, this.config.dprMax);
+		const { w, h, dpr } = this.viewportMetrics();
+		this.lastResize = {
+			w,
+			h,
+			dpr
+		};
 		this.renderer.setPixelRatio(dpr);
 		this.renderer.setSize(w, h, !this.outputSize);
 		if (this.outputSize) {
@@ -1387,16 +1475,20 @@ var WaveRenderer = class {
 	onAfterRenderFrame() {}
 	/** Hook ④: called at the end of resize(), before the trailing renderOnce(). */
 	onAfterResize() {}
-	/** Responsive ortho zoom: COVER the FRAME_W × FRAME_H reference frame onto the canvas so the
-	*  wave frames the same at any size/aspect/dpr (only the cropped margin differs), times the
-	*  user's cameraZoom. `max(...)` = cover (fill both axes, crop overflow); `min(...)` would be
-	*  contain (fit with letterbox bands). Cover keeps the wave filling the frame on every screen. */
+	/** Responsive ortho zoom: map the FRAME_W × FRAME_H reference frame onto the canvas (per
+	*  config.cameraFit / cameraMinVisibleWidth — see {@link frameZoom}) so the wave frames the same
+	*  at any size/aspect/dpr, times the user's cameraZoom. */
 	applyZoom() {
 		const dw = this.camera.right - this.camera.left;
 		const dh = this.camera.top - this.camera.bottom;
-		this.camera.zoom = Math.max(dw / FRAME_W, dh / 750) * (this.config.cameraZoom ?? 1) * this.interactionZoom;
+		this.camera.zoom = this.baseFrameZoom(dw, dh) * (this.config.cameraZoom ?? 1) * this.interactionZoom;
 		this.camera.updateProjectionMatrix();
 	}
+	/** The responsive base zoom for the current config's framing policy, before the cameraZoom
+	*  multiplier. Subclasses invert this to recover cameraZoom from a live camera. */
+	baseFrameZoom(dw, dh) {
+		return frameZoom(dw, dh, this.config.cameraFit ?? "cover", this.config.cameraMinVisibleWidth ?? 0);
+	}
 	/** Fit the orthographic near/far planes to the scene before every render, so no part of a wave
 	*  is ever clipped as the camera orbits / dollies / pans (or when waves are added or scaled).
 	*
@@ -1509,12 +1601,14 @@ var WaveRenderer = class {
 	}
 	dispose() {
 		cancelAnimationFrame(this.rafId);
+		cancelAnimationFrame(this.resizeRaf);
 		this.running = false;
 		this.interaction?.dispose();
 		this.interaction = void 0;
 		this.resizeObserver.disconnect();
 		this.intersectionObserver.disconnect();
 		this.motionQuery.removeEventListener("change", this.onMotionChange);
+		this.dprQuery?.removeEventListener("change", this.onDprChange);
 		document.removeEventListener("visibilitychange", this.onVisibilityChange);
 		this.renderer.domElement.removeEventListener("webglcontextlost", this.onContextLost);
 		this.renderer.domElement.removeEventListener("webglcontextrestored", this.onContextRestored);
@@ -1538,6 +1632,6 @@ var WaveRenderer = class {
 	}
 };
 //#endregion
-export { FRAME_H, FRAME_W, WaveRenderer, hexToLinearVec3 };
+export { FRAME_H, FRAME_W, WaveRenderer, frameZoom, hexToLinearVec3 };
 
 //# sourceMappingURL=WaveRenderer.js.map