vizcore 1.1.0 → 1.2.0

data/frontend/src/renderer/engine.js

@@ -3,6 +3,9 @@ import { ShaderManager } from "./shader-manager.js";
 import { applyShaderParamOverrides } from "../shader-param-controls.js";
 import { applyShapeEditorOverrides } from "../shape-editor-controls.js";
 
+export const RENDERER_CAPABILITIES_EVENT = "vizcore:renderer-capabilities";
+export const RENDERER_SAFE_MODE_EVENT = "vizcore:renderer-safe-mode";
+
 export class Engine {
   constructor(canvas) {
     this.canvas = canvas;
@@ -14,17 +17,44 @@ export class Engine {
     this.currentRotationSpeed = 0.5;
     this.mediaElement = null;
     this.lastMediaTime = null;
+    this.resizeHandler = null;
+    this.rendererCapabilities = null;
+    this.safeModeState = {
+      active: false,
+      slowFrames: 0,
+      fastFrames: 0,
+    };
     this.visualSettings = {
       visualGain: 1,
       bassBoost: 1,
       smoothing: 0,
       beatHoldMs: 180,
       wobbleAmount: 1,
+      maxDevicePixelRatio: 2,
+      safeMode: true,
+      safeModeFrameMs: 34,
+      safeModeScale: 0.75,
     };
     this.visualAudioState = null;
     this.liveControls = {
-      blackout: false,
-      freeze: false,
+      blackout: { enabled: false, color: [0, 0, 0, 1] },
+      freeze: { enabled: false },
+    };
+    this.liveControlRuntime = {
+      blackout: {
+        opacity: 0,
+        targetOpacity: 0,
+        transitionFrom: 0,
+        transitionStartedAt: 0,
+        transitionDuration: 0,
+        color: [0, 0, 0, 1],
+      },
+      freeze: {
+        enabled: false,
+        targetEnabled: false,
+        transitionStartedAt: 0,
+        transitionDuration: 0,
+      },
     };
     this.runtimeGlobals = {};
     this.shaderParamOverrides = {};
@@ -34,6 +64,7 @@ export class Engine {
       audio: {
         amplitude: 0,
         bands: { sub: 0, low: 0, mid: 0, high: 0 },
+        band_peaks: { sub: 0, low: 0, mid: 0, high: 0 },
         fft: [],
         onset: 0,
         onsets: { sub: 0, low: 0, mid: 0, high: 0 },
@@ -41,6 +72,14 @@ export class Engine {
         beat: false,
         beat_pulse: 0,
         beat_count: 0,
+        beat_phase: 0,
+        beat_2: false,
+        beat_4: false,
+        beat_8: false,
+        beat_triplet: false,
+        bar_phase: 0,
+        bar_count: 0,
+        phrase_count: 0,
         bpm: 0
       },
       scene: {
@@ -58,12 +97,18 @@ export class Engine {
 
     this.shaderManager = new ShaderManager(this.gl);
     this.layerManager = new LayerManager(this.gl, this.shaderManager);
+    this.rendererCapabilities = collectRendererCapabilities(this.gl, {
+      devicePixelRatio: currentDevicePixelRatio(),
+      effectiveDevicePixelRatio: this.effectiveDevicePixelRatio(),
+    });
+    dispatchRendererEvent(RENDERER_CAPABILITIES_EVENT, this.rendererCapabilities);
 
     this.gl.enable(this.gl.DEPTH_TEST);
     this.gl.enable(this.gl.BLEND);
     this.gl.blendFunc(this.gl.SRC_ALPHA, this.gl.ONE_MINUS_SRC_ALPHA);
     this.resize();
-    window.addEventListener("resize", () => this.resize());
+    this.resizeHandler = () => this.resize();
+    window.addEventListener("resize", this.resizeHandler);
   }
 
   setAudioFrame(frame) {
@@ -83,13 +128,108 @@ export class Engine {
       ...this.visualSettings,
       ...settings,
     };
+    if (this.gl) {
+      this.resize();
+    }
   }
 
   setLiveControls(controls = {}) {
+    const now = performance.now();
     this.liveControls = {
-      blackout: !!controls?.blackout,
-      freeze: !!controls?.freeze,
+      blackout: normalizeLiveControlState(controls?.blackout),
+      freeze: normalizeLiveControlState(controls?.freeze),
     };
+    this.applyBlackoutRuntime(this.liveControls.blackout, now);
+    this.applyFreezeRuntime(this.liveControls.freeze, now);
+  }
+
+  applyBlackoutRuntime(control, now) {
+    const targetOpacity = control.enabled ? 1 : 0;
+    const color = normalizeLiveControlColor(control.color);
+    if (color) {
+      this.liveControlRuntime.blackout.color = color;
+    }
+
+    if (targetOpacity === this.liveControlRuntime.blackout.targetOpacity) {
+      this.liveControlRuntime.blackout.transitionDuration = 0;
+      this.liveControlRuntime.blackout.opacity = targetOpacity;
+      return;
+    }
+
+    const transitionDuration = control.enabled
+      ? finiteFloat(control.fade)
+      : finiteFloat(control.release);
+    if (!transitionDuration) {
+      this.liveControlRuntime.blackout.opacity = targetOpacity;
+      this.liveControlRuntime.blackout.targetOpacity = targetOpacity;
+      this.liveControlRuntime.blackout.transitionDuration = 0;
+      return;
+    }
+
+    this.liveControlRuntime.blackout.targetOpacity = targetOpacity;
+    this.liveControlRuntime.blackout.transitionFrom = this.liveControlRuntime.blackout.opacity;
+    this.liveControlRuntime.blackout.transitionStartedAt = now;
+    this.liveControlRuntime.blackout.transitionDuration = transitionDuration;
+  }
+
+  applyFreezeRuntime(control, now) {
+    const targetEnabled = !!control.enabled;
+    if (targetEnabled === this.liveControlRuntime.freeze.targetEnabled) {
+      return;
+    }
+
+    const transitionDuration = targetEnabled
+      ? finiteFloat(control.fade)
+      : finiteFloat(control.release);
+    if (!transitionDuration) {
+      this.liveControlRuntime.freeze.enabled = targetEnabled;
+      this.liveControlRuntime.freeze.targetEnabled = targetEnabled;
+      this.liveControlRuntime.freeze.transitionDuration = 0;
+      return;
+    }
+
+    this.liveControlRuntime.freeze.targetEnabled = targetEnabled;
+    this.liveControlRuntime.freeze.transitionStartedAt = now;
+    this.liveControlRuntime.freeze.transitionDuration = transitionDuration;
+  }
+
+  updateLiveControlRuntime(time) {
+    this.updateBlackoutRuntime(time);
+    this.updateFreezeRuntime(time);
+  }
+
+  updateBlackoutRuntime(time) {
+    const blackout = this.liveControlRuntime.blackout;
+    const duration = blackout.transitionDuration;
+    if (!duration || duration <= 0) {
+      return;
+    }
+
+    const elapsed = time - blackout.transitionStartedAt;
+    if (elapsed >= duration) {
+      blackout.opacity = blackout.targetOpacity;
+      blackout.transitionDuration = 0;
+      return;
+    }
+
+    const progress = clamp(elapsed / duration, 0, 1);
+    blackout.opacity = blackout.transitionFrom + (blackout.targetOpacity - blackout.transitionFrom) * progress;
+  }
+
+  updateFreezeRuntime(time) {
+    const freeze = this.liveControlRuntime.freeze;
+    const duration = freeze.transitionDuration;
+    if (!duration || duration <= 0) {
+      return;
+    }
+
+    const elapsed = time - freeze.transitionStartedAt;
+    if (elapsed < duration) {
+      return;
+    }
+
+    freeze.enabled = freeze.targetEnabled;
+    freeze.transitionDuration = 0;
   }
 
   setRuntimeGlobals(globals = {}) {
@@ -110,8 +250,9 @@ export class Engine {
   }
 
   resize() {
-    const width = Math.floor(this.canvas.clientWidth * window.devicePixelRatio);
-    const height = Math.floor(this.canvas.clientHeight * window.devicePixelRatio);
+    const dpr = this.effectiveDevicePixelRatio();
+    const width = Math.max(1, Math.floor(this.canvas.clientWidth * dpr));
+    const height = Math.max(1, Math.floor(this.canvas.clientHeight * dpr));
     if (this.canvas.width === width && this.canvas.height === height) {
       return;
     }
@@ -120,6 +261,15 @@ export class Engine {
     this.gl.viewport(0, 0, width, height);
   }
 
+  effectiveDevicePixelRatio() {
+    return resolveEffectiveDevicePixelRatio({
+      devicePixelRatio: currentDevicePixelRatio(),
+      maxDevicePixelRatio: this.visualSettings.maxDevicePixelRatio,
+      safeModeActive: this.safeModeState.active,
+      safeModeScale: this.visualSettings.safeModeScale,
+    });
+  }
+
   render(time) {
     let deltaSeconds = (time - this.lastTime) / 1000;
     this.lastTime = time;
@@ -142,14 +292,21 @@ export class Engine {
       this.lastMediaTime = null;
     }
 
-    if (this.liveControls.blackout) {
-      this.gl.clearColor(0, 0, 0, 1);
+    this.updateSafeMode(deltaSeconds * 1000);
+    this.updateLiveControlRuntime(time);
+
+    const blackout = this.liveControlRuntime.blackout;
+    const blackoutColor = blackout.color || [0, 0, 0, 1];
+    const [blackoutRed, blackoutGreen, blackoutBlue, blackoutAlpha = 1] = blackoutColor;
+    const effectiveBlackoutAlpha = clamp(blackout.opacity * blackoutAlpha, 0, 1);
+    if (effectiveBlackoutAlpha >= 1) {
+      this.gl.clearColor(blackoutRed, blackoutGreen, blackoutBlue, 1);
       this.gl.clear(this.gl.COLOR_BUFFER_BIT | this.gl.DEPTH_BUFFER_BIT);
       requestAnimationFrame((nextTime) => this.render(nextTime));
       return;
     }
 
-    if (this.liveControls.freeze) {
+    if (this.liveControlRuntime.freeze.enabled) {
       requestAnimationFrame((nextTime) => this.render(nextTime));
       return;
     }
@@ -179,6 +336,16 @@ export class Engine {
     );
     this.gl.clear(this.gl.COLOR_BUFFER_BIT | this.gl.DEPTH_BUFFER_BIT);
 
+    if (effectiveBlackoutAlpha > 0) {
+      this.gl.clearColor(
+        blackoutRed,
+        blackoutGreen,
+        blackoutBlue,
+        effectiveBlackoutAlpha
+      );
+      this.gl.clear(this.gl.COLOR_BUFFER_BIT | this.gl.DEPTH_BUFFER_BIT);
+    }
+
     this.layerManager.renderScene({
       layers,
       audio,
@@ -191,8 +358,115 @@ export class Engine {
 
     requestAnimationFrame((nextTime) => this.render(nextTime));
   }
+
+  updateSafeMode(frameMs) {
+    const nextState = nextSafeModeState({
+      state: this.safeModeState,
+      frameMs,
+      enabled: this.visualSettings.safeMode,
+      thresholdMs: this.visualSettings.safeModeFrameMs,
+    });
+    if (nextState.active === this.safeModeState.active) {
+      this.safeModeState = nextState;
+      return;
+    }
+
+    this.safeModeState = nextState;
+    this.resize();
+    dispatchRendererEvent(RENDERER_SAFE_MODE_EVENT, {
+      active: nextState.active,
+      effectiveDevicePixelRatio: this.effectiveDevicePixelRatio(),
+    });
+  }
+
+  dispose() {
+    if (this.resizeHandler && typeof window !== "undefined") {
+      window.removeEventListener("resize", this.resizeHandler);
+      this.resizeHandler = null;
+    }
+    this.layerManager?.dispose?.();
+    this.shaderManager?.dispose?.();
+  }
 }
 
+const normalizeLiveControlState = (state) => {
+  if (state === null || state === undefined || typeof state === "boolean") {
+    return { enabled: !!state };
+  }
+
+  return {
+    enabled: state.value !== undefined ? !!state.value : !!state.enabled,
+    fade: finiteFloat(state.fade),
+    release: finiteFloat(state.release),
+    color: normalizeLiveControlColor(state.color),
+  };
+};
+
+const finiteFloat = (value) => {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+};
+
+const normalizeLiveControlColor = (value) => {
+  if (value == null) {
+    return null;
+  }
+
+  if (Array.isArray(value)) {
+    const channels = Array.from(value)
+      .slice(0, 4)
+      .map((channel) => Number(channel));
+    if (channels.length < 3 || channels.length > 4 || channels.some((channel) => !Number.isFinite(channel))) {
+      return null;
+    }
+
+    const rgbValues = channels.slice(0, 3);
+    const alpha = channels[3];
+    const rgb = rgbValues.every((channel) => channel >= 0 && channel <= 1)
+      ? rgbValues.map((channel) => clamp(channel, 0, 1))
+      : rgbValues.map((channel) => clamp(channel / 255, 0, 1));
+    const normalizedAlpha = alpha == null ? null : (alpha > 1 ? clamp(alpha / 255, 0, 1) : clamp(alpha, 0, 1));
+
+    return channels.length === 3 ? rgb : [...rgb, normalizedAlpha];
+  }
+
+  const color = parseHexColor(String(value || ""));
+  if (!Array.isArray(color)) {
+    return null;
+  }
+
+  if (color.length === 4) {
+    return color.map((channel) => clamp(channel, 0, 1));
+  }
+
+  if (color.length === 3) {
+    return color.map((channel) => clamp(channel, 0, 1));
+  }
+
+  return null;
+};
+
+const parseHexColor = (value) => {
+  const raw = String(value || "").trim();
+  const match = raw.match(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/);
+  if (!match) {
+    return null;
+  }
+
+  const rawHex = match[1];
+  const hex = rawHex.length === 3 || rawHex.length === 4
+    ? rawHex.split("").map((entry) => `${entry}${entry}`).join("")
+    : rawHex;
+
+  const channels = [];
+  for (let index = 0; index < hex.length; index += 2) {
+    const value = Number.parseInt(hex.slice(index, index + 2), 16);
+    channels.push(value / 255);
+  }
+
+  return channels;
+};
+
 const resolveRotationSpeed = (layers, amplitude) => {
   const layerWithSpeed = Array.isArray(layers)
     ? layers.find((layer) => Number.isFinite(Number(layer?.params?.rotation_speed)))
@@ -286,4 +560,111 @@ const isSilentAudio = (audio) => {
     && Number(drums.hihat || 0) <= 0;
 };
 
+export const resolveEffectiveDevicePixelRatio = ({
+  devicePixelRatio,
+  maxDevicePixelRatio = 2,
+  safeModeActive = false,
+  safeModeScale = 0.75,
+} = {}) => {
+  const rawDpr = Number(devicePixelRatio);
+  const maxDpr = clamp(Number(maxDevicePixelRatio || 2), 0.5, 4);
+  const base = clamp(Number.isFinite(rawDpr) ? rawDpr : 1, 0.5, maxDpr);
+  if (!safeModeActive) {
+    return roundDpr(base);
+  }
+
+  const scale = clamp(Number(safeModeScale || 0.75), 0.25, 1);
+  return roundDpr(clamp(base * scale, 0.5, maxDpr));
+};
+
+export const nextSafeModeState = ({
+  state,
+  frameMs,
+  enabled = true,
+  thresholdMs = 34,
+} = {}) => {
+  const current = state || {};
+  if (!enabled) {
+    return { active: false, slowFrames: 0, fastFrames: 0 };
+  }
+
+  const value = Number(frameMs);
+  const threshold = clamp(Number(thresholdMs || 34), 16, 250);
+  if (!Number.isFinite(value) || value <= 0) {
+    return { ...current };
+  }
+
+  const slowFrames = value > threshold ? Number(current.slowFrames || 0) + 1 : 0;
+  const fastFrames = value < threshold * 0.75 ? Number(current.fastFrames || 0) + 1 : 0;
+  const active = current.active ? fastFrames < 120 : slowFrames >= 12;
+  return {
+    active,
+    slowFrames: active ? 0 : slowFrames,
+    fastFrames: active ? fastFrames : 0,
+  };
+};
+
+export const collectRendererCapabilities = (gl, {
+  devicePixelRatio = currentDevicePixelRatio(),
+  effectiveDevicePixelRatio = devicePixelRatio,
+} = {}) => {
+  const maxViewportDims = safeGetParameter(gl, gl?.MAX_VIEWPORT_DIMS) || [];
+  return {
+    webgl2: true,
+    devicePixelRatio: roundDpr(devicePixelRatio),
+    effectiveDevicePixelRatio: roundDpr(effectiveDevicePixelRatio),
+    maxTextureSize: Number(safeGetParameter(gl, gl?.MAX_TEXTURE_SIZE) || 0),
+    maxDrawBuffers: Number(safeGetParameter(gl, gl?.MAX_DRAW_BUFFERS) || 0),
+    maxRenderbufferSize: Number(safeGetParameter(gl, gl?.MAX_RENDERBUFFER_SIZE) || 0),
+    maxViewportDims: Array.from(maxViewportDims).map((value) => Number(value || 0)),
+    floatColorBuffer: !!safeGetExtension(gl, "EXT_color_buffer_float"),
+    textureFloat: !!safeGetExtension(gl, "OES_texture_float"),
+  };
+};
+
+const currentDevicePixelRatio = () => {
+  if (typeof window === "undefined") {
+    return 1;
+  }
+  return Number(window.devicePixelRatio || 1);
+};
+
+const safeGetParameter = (gl, parameter) => {
+  if (!gl || parameter === undefined || typeof gl.getParameter !== "function") {
+    return null;
+  }
+
+  try {
+    return gl.getParameter(parameter);
+  } catch {
+    return null;
+  }
+};
+
+const safeGetExtension = (gl, name) => {
+  if (!gl || typeof gl.getExtension !== "function") {
+    return null;
+  }
+
+  try {
+    return gl.getExtension(name);
+  } catch {
+    return null;
+  }
+};
+
+const dispatchRendererEvent = (type, detail) => {
+  if (typeof window === "undefined" || typeof window.dispatchEvent !== "function") {
+    return;
+  }
+
+  if (typeof CustomEvent !== "function") {
+    return;
+  }
+
+  window.dispatchEvent(new CustomEvent(type, { detail }));
+};
+
+const roundDpr = (value) => Math.round(Number(value || 1) * 100) / 100;
+
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);