@wave3d/core 0.8.0 → 0.10.0

package/dist/renderer/WaveRenderer.d.ts

@@ -1,8 +1,11 @@
-import { CameraFit, StudioConfig, WaveConfig } from "../config/model.js";
+import { BlendMode, CameraFit, StudioConfig, WaveConfig } from "../config/model.js";
 import { WaveGeometry } from "./WaveGeometry.js";
-import { ParticleField } from "./particleField.js";
+import { ParticleFrame } from "./particleField.js";
+import { TiltStatus } from "./tilt.js";
 import { InteractionController } from "./interaction.js";
 import * as THREE from "three";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { ShaderPass } from "three/addons/postprocessing/ShaderPass.js";
 //#region src/renderer/WaveRenderer.d.ts
 /** Reference frame (world units) the orthographic camera fills at cameraZoom 1. The wave is
  *  framed by mapping this FRAME_W × FRAME_H rectangle (centred on cameraTarget) onto the canvas,
@@ -61,15 +64,50 @@ declare class WavePalette {
   private clearVideo;
   dispose(): void;
 }
+/**
+ * The uniform surface both backends expose. The GLSL path holds `THREE.IUniform`s; the TSL path
+ * holds TSL uniform nodes and array wrappers. Both are written the same way — `u.uFoo.value = x`,
+ * `u.uColors.value[i].set(...)` — which is what lets the ~116 config-sync writes in `refresh()`
+ * stay backend-agnostic.
+ */
+type WaveUniforms = Record<string, {
+  value: unknown;
+}>;
+/** A wave material, whichever backend built it. */
+type WaveMaterial = THREE.Material & {
+  uniforms: WaveUniforms;
+};
+/**
+ * A wave's particle field, whichever backend built it.
+ *
+ * The TSL field is a `THREE.Sprite` where the GLSL one is a `THREE.Points` (WebGPU has no point
+ * size), so the scene node is reached through `object` rather than either concrete type.
+ */
+interface WaveParticleField {
+  readonly object: THREE.Object3D;
+  sync(cfg: NonNullable<WaveConfig["particles"]>, loopSeconds: number): void;
+  frame(f: ParticleFrame, pixelRatio: number): void;
+  configure(shape: {
+    defines?: Record<string, string>;
+    uniforms?: Record<string, {
+      value: unknown;
+    }>;
+    matrixWorld: THREE.Matrix4;
+    speed: number;
+    seed: number;
+  }): void;
+  setTime(t: number): void;
+  dispose(): void;
+}
 type Wave = {
   mesh: THREE.Mesh;
-  material: THREE.ShaderMaterial;
+  material: WaveMaterial;
   geometry: WaveGeometry;
   /** This wave's own 2D palette texture + optional video. */
   palette: WavePalette;
   /** This wave's own particle / dust field — created when its `particles.count` first goes >0,
    *  disposed at 0 / absent (the WavePalette lifecycle pattern). Undefined = no dust for this wave. */
-  particleField?: ParticleField;
+  particleField?: WaveParticleField;
 };
 /** Convert an sRGB hex string to a linear-space RGB vector (three's ColorManagement does the
  *  sRGB→linear conversion on parse). Exported for the studio subclass's live light-uniform push. */
@@ -81,11 +119,17 @@ declare function hexToLinearVec3(hex: string, target: THREE.Vector3): THREE.Vect
  */
 declare class WaveRenderer {
   readonly renderer: THREE.WebGLRenderer;
+  /**
+   * Whether this renderer can draw yet. The WebGL backend is ready the moment it is constructed;
+   * the WebGPU subclass has to `await renderer.init()` first, and `renderOnce()` throws before that.
+   * The base class is always ready, so the WebGL path is unaffected.
+   */
+  protected ready: boolean;
   protected readonly scene: THREE.Scene<THREE.Object3DEventMap>;
   protected readonly camera: THREE.OrthographicCamera;
   protected readonly group: THREE.Group<THREE.Object3DEventMap>;
-  private readonly composer;
-  private readonly postPass;
+  protected composer: EffectComposer;
+  protected postPass: ShaderPass;
   /** Optional bloom pass — created lazily when bloomStrength first goes >0, removed at 0. */
   private bloomPass?;
   private ditherPass?;
@@ -118,8 +162,17 @@ declare class WaveRenderer {
   private readonly clipSphere;
   private readonly clipTmpA;
   private readonly clipTmpB;
-  /** Created by syncInteraction() when interaction turns on, disposed when it turns off. */
+  /** Created by loadInteraction() once the runtime chunk lands, disposed when interaction turns off.
+   *  Stays undefined for the frames between the config turning it on and the chunk arriving. */
   protected interaction?: InteractionController;
+  /** The chunk itself, kept for the applier tables. Set and cleared with `interaction`. */
+  private interactionModule?;
+  /** A fetch already in flight, so a per-frame refresh can't start a second one. */
+  private interactionLoading;
+  /** setInteractionInput() calls made while the chunk was in flight, replayed once it lands. */
+  private stagedInputs?;
+  /** Set by dispose(), so an in-flight chunk can't attach listeners to a dead renderer. */
+  private disposed;
   /** Extra ortho-zoom MULTIPLIER from a cameraZoom binding (1 = none); applied in applyZoom().
    *  Protected so the studio's writeCameraToConfig() can divide it back out (keep it out of config). */
   protected interactionZoom: number;
@@ -150,6 +203,17 @@ declare class WaveRenderer {
    *  this unset and continue to resize responsively with their container and device DPR. */
   private outputSize?;
   constructor(container: HTMLElement, config: StudioConfig, options?: WaveRendererOptions);
+  /**
+   * Build the backing three renderer. Overridden by the WebGPU subclass; called from the
+   * constructor, so it must not depend on subclass FIELDS (prototype methods are available during
+   * `super()`, field initialisers are not).
+   */
+  protected createRenderer(): THREE.WebGLRenderer;
+  /**
+   * Await any asynchronous backend startup. A no-op on WebGL; the WebGPU subclass overrides it to
+   * `await renderer.init()` and then draw the first frame. Safe to call more than once.
+   */
+  init(): Promise<void>;
   private get segments();
   private makeUniforms;
   /** Vertex-shader #defines for a wave: TWIST_MOTION (per-wave animated twist wobble) and
@@ -157,6 +221,19 @@ declare class WaveRenderer {
    *  object compiles the default (linear-time) program. */
   private waveDefines;
   private addWave;
+  /**
+   * Build the material for one wave. The GLSL backend compiles a ShaderMaterial with `#define`
+   * variants; the WebGPU subclass builds a TSL node graph instead. Both expose the same `uniforms`
+   * surface, so everything downstream in `refresh()` is shared.
+   */
+  protected createWaveMaterial(sc: WaveConfig | undefined): WaveMaterial;
+  /**
+   * Re-select this wave's shader variant when its config changes shape (theme, twist motion, helix,
+   * …). Returns true if the material needs recompiling. The GLSL backend swaps `defines` and the
+   * fragment source; the WebGPU subclass rebuilds the node graph, since a TSL variant is a
+   * different graph rather than a different define set.
+   */
+  protected applyWaveVariant(wave: Wave, sc: WaveConfig): boolean;
   /**
    * Apply config.blendMode to a material. "squared" (the default) is the hero blend:
    * CustomBlending with AddEquation, src = SrcColorFactor, dst = ZeroFactor, so the
@@ -166,7 +243,7 @@ declare class WaveRenderer {
    * fragment shaders premultiply their output when Three injects PREMULTIPLIED_ALPHA.
    * Returns true if material state changed (caller flags needsUpdate).
    */
-  private applyBlendMode;
+  protected applyBlendMode(material: WaveMaterial, mode: BlendMode): boolean;
   private disposeWaves;
   /**
    * Reconcile the wave pool to `waveCount` WITHOUT tearing everything down:
@@ -185,6 +262,22 @@ declare class WaveRenderer {
   /** Rebuild geometry + waves (call when waveCount or quality changes). */
   rebuild(): void;
   private applyBackground;
+  /**
+   * Build a wave's particle field. The GLSL backend returns a `THREE.Points` field; the TSL backend
+   * returns an instanced-sprite one wired to this wave's own uniform registry.
+   */
+  protected createParticleField(_wave: Wave, _sc: WaveConfig, onReady: () => void): WaveParticleField;
+  /**
+   * Largest texture edge the backend will accept, used to cap the background canvas. WebGL reports
+   * it on `capabilities`; WebGPU has no such object, so the subclass reads the device limit.
+   */
+  protected maxTextureSize(): number;
+  /**
+   * Called whenever the scene background changes. A no-op on WebGL, where `EffectComposer`'s
+   * RenderPass reads the scene afresh each frame; the WebGPU subclass rebuilds its post chain,
+   * because a `pass()` node captures the background state at the point its render context is built.
+   */
+  protected onBackgroundChanged(): void;
   private applyColorBackground;
   private applyGradientBackground;
   /** Image mode: a live video, a user-loaded image, or a built-in map. `matte` shows while an
@@ -265,6 +358,12 @@ declare class WaveRenderer {
   /** Advance the per-frame time uniforms (geometry itself is static). Time model:
    *  time = elapsed·introTimeRamp + timeOffset — the ramp eases the animation in on load. */
   private updateTime;
+  /** Draw the composed frame. WebGL runs the EffectComposer; WebGPU runs a node post chain. */
+  protected renderComposed(): void;
+  /** Resize the post chain's render targets. */
+  protected resizePost(w: number, h: number, dpr: number): void;
+  /** Release the post chain's GPU resources. */
+  protected disposePost(): void;
   /** Render exactly one frame at the current time. */
   renderOnce(): void;
   /** Insert / sync / remove EACH wave's particle field — mirrors applyBloom's lazy lifecycle, per wave.
@@ -285,6 +384,20 @@ declare class WaveRenderer {
   /** Create/dispose the interaction controller as config toggles interaction on/off. Called from
    *  refresh(); the compiled define set (POINTER_FX etc.) is handled separately by waveDefines(). */
   private syncInteraction;
+  /**
+   * Fetch the interactivity runtime and attach it. Deliberately a DYNAMIC import: the controller,
+   * its listeners, the applier tables and the tilt sensor are ~3.8 KB gzipped that a scene with no
+   * `interaction` block never runs, and a static import would put all of it in every bundle. The
+   * cost is that interaction goes live a chunk-fetch after the first frame instead of on it —
+   * invisible in practice, since there is nothing to react to until a reader moves.
+   *
+   * A failed fetch is not fatal: the wave renders exactly as an inert one does, which is the same
+   * thing that happens on a config with no interaction at all.
+   */
+  private loadInteraction;
+  /** Hook for subclasses that hold state the controller must be told about once it exists (the
+   *  studio's scroll preview). No-op in the base renderer. */
+  protected onInteractionReady(): void;
   /** Per-frame interaction write: dynamic pointer-field uniforms + bindings. No-op without a
    *  controller. While capturing it writes the REST state instead (pointer field zeroed, every bound
    *  param at its authored base) — merely skipping the write would freeze whatever live hover/scroll
@@ -304,8 +417,27 @@ declare class WaveRenderer {
   /** Evaluate bindings via the applier tables: value = mix(from ?? base, to, smoothedSource). Scene
    *  bindings drive scene params; each wave's bindings drive that wave's uniforms. */
   private applyBindings;
-  /** Feed a `custom:<name>` interaction input (developer API). No-op when interaction is off. */
+  /** Feed a `custom:<name>` interaction input (developer API). No-op when interaction is off.
+   *  Values fed before the interaction chunk lands are STAGED (last one per name wins) and replayed
+   *  when it does — otherwise a one-shot input sent right after `onReady` would vanish into the
+   *  fetch window. */
   setInteractionInput(name: string, value: number): void;
+  /**
+   * Explicitly ask for the device-orientation sensor. OPTIONAL, and on iOS it opens a modal
+   * permission dialog — so this belongs to a page where tilt is the point, not to a decorative
+   * background, which should simply go without tilt there. Nothing calls this for you.
+   *
+   * CALL IT FROM A USER GESTURE: iOS 13+ only grants the sensor from inside a tap handler, and
+   * awaiting anything before it (a fetch, a timeout) spends the gesture. Resolves true once
+   * readings can flow — false when
+   * the platform has no sensor, the scene declares no `interaction.tilt`, or the reader refused.
+   * Where no permission is required the sensor is already live and this resolves true.
+   */
+  enableTilt(): Promise<boolean>;
+  /** Where the tilt sensor stands. `"prompt"` is exactly when a tap-to-enable affordance helps. */
+  tiltStatus(): TiltStatus;
+  /** Take the next orientation reading as the neutral pose — for when the reader has changed grip. */
+  recenterTilt(): void;
   /** Re-evaluate play/pause after `config.paused` changes. */
   refreshPlayback(): void;
   /** Jump the camera to the config's authored framing (cameraPosition / cameraTarget /
@@ -357,5 +489,5 @@ declare class WaveRenderer {
   dispose(): void;
 }
 //#endregion
-export { FRAME_H, FRAME_W, WaveRenderer, WaveRendererOptions, frameZoom, hexToLinearVec3 };
+export { FRAME_H, FRAME_W, WaveMaterial, WaveParticleField, WaveRenderer, WaveRendererOptions, WaveUniforms, frameZoom, hexToLinearVec3 };
 //# sourceMappingURL=WaveRenderer.d.ts.map