@opsydyn/effect-three 0.0.0-stage → 0.2.0

package/src/kernel/cameraMotion.ts

@@ -0,0 +1,202 @@
+/**
+ * How the rendered camera reaches its description: at once, or damped round its target;
+ * and how it turns round its target by itself (`autoRotate`).
+ *
+ * Behavioural reference: three.js `examples/jsm/controls/OrbitControls.js` at 0.186.1,
+ * `update` with `enableDamping`: each update closes `dampingFactor` of the remaining
+ * rotation and pan. Here the remaining way to the described pose closes by that fraction
+ * every sixtieth of a second of scene time, so the motion is the same at any frame rate,
+ * and the camera travels round the target (azimuth the short way) rather than through it.
+ * `autoRotate` is `update` with `autoRotate`: `rotateLeft` by `2π / 60 * autoRotateSpeed`
+ * a second, only while no gesture is in progress (`state === NONE`).
+ *
+ * @module
+ */
+import { OrthographicCamera, type PerspectiveCamera, Spherical, Vector3 } from 'three';
+
+import type { Camera, Vec3 } from './description.ts';
+
+type Pose = { readonly target: Vector3; readonly spherical: Spherical; zoom: number };
+
+const createPose = (): Pose => ({ target: new Vector3(), spherical: new Spherical(), zoom: 1 });
+
+const offset = new Vector3();
+const position = new Vector3();
+
+const readPose = (pose: Pose, description: Camera): void => {
+  pose.target.fromArray(description.lookAt);
+  offset.fromArray(description.position).sub(pose.target);
+  pose.spherical.setFromVector3(offset);
+  pose.zoom = description._tag === 'Orthographic' ? description.zoom : 1;
+};
+
+const copyPose = (to: Pose, from: Pose): void => {
+  to.target.copy(from.target);
+  to.spherical.copy(from.spherical);
+  to.zoom = from.zoom;
+};
+
+/** The signed angle from `from` to `to`, the short way round: within ±π. */
+const turn = (from: number, to: number): number => {
+  const difference = (to - from) % (2 * Math.PI);
+  if (difference > Math.PI) return difference - 2 * Math.PI;
+  if (difference < -Math.PI) return difference + 2 * Math.PI;
+  return difference;
+};
+
+/** Close enough to the aim that the rest is invisible: snap and stop. */
+const settled = (current: Pose, goal: Pose): boolean => {
+  const scale = Math.max(1, goal.spherical.radius);
+  return (
+    current.target.distanceTo(goal.target) < 1e-5 * scale &&
+    Math.abs(current.spherical.radius - goal.spherical.radius) < 1e-5 * scale &&
+    Math.abs(turn(current.spherical.theta, goal.spherical.theta)) < 1e-6 &&
+    Math.abs(current.spherical.phi - goal.spherical.phi) < 1e-6 &&
+    Math.abs(current.zoom - goal.zoom) < 1e-6 * goal.zoom
+  );
+};
+
+function writeZoom(camera: PerspectiveCamera | OrthographicCamera, zoom: number): void {
+  if (!(camera instanceof OrthographicCamera) || camera.zoom === zoom) return;
+  camera.zoom = zoom;
+  camera.updateProjectionMatrix();
+}
+
+/** Writes a pose to a host camera. */
+const write = (camera: PerspectiveCamera | OrthographicCamera, pose: Pose): void => {
+  position.setFromSpherical(pose.spherical).add(pose.target);
+  camera.position.copy(position);
+  camera.lookAt(pose.target);
+  writeZoom(camera, pose.zoom);
+};
+
+export type CameraMotion = {
+  /**
+   * Aims at a described pose at scene time `now`. It is shown at once when `jump` is
+   * true, the camera has no damping, or nothing was shown before; otherwise `step`
+   * travels there. A new position, `lookAt` or zoom ends any turning (`autoRotate`).
+   */
+  readonly aim: (
+    camera: PerspectiveCamera | OrthographicCamera,
+    description: Camera,
+    now: number,
+    jump: boolean,
+  ) => void;
+  /**
+   * Turns (`autoRotate`) and travels toward the aim up to scene time `now`. Returns
+   * whether it is still moving.
+   */
+  readonly step: (camera: PerspectiveCamera | OrthographicCamera, now: number) => boolean;
+  /** Lands on the aim at once. */
+  readonly settle: (camera: PerspectiveCamera | OrthographicCamera) => void;
+  readonly moving: () => boolean;
+  /** Stops turning while `held` (a gesture is pressed), as `OrbitControls` turns only idle. */
+  readonly hold: (held: boolean) => void;
+  /** Where turning has taken the camera, when it has turned since its description. */
+  readonly turned: () => Vec3 | undefined;
+};
+
+/** Radians a turning camera turns per second per unit of `autoRotate` (three's `2π / 60`). */
+const turnRate = (2 * Math.PI) / 60;
+
+/** Creates the motion of one camera. Allocation-free once created. */
+export const createCameraMotion = (): CameraMotion => {
+  const current = createPose();
+  // Where the description puts the camera, and where it is going: that, turned by `spun`.
+  const described = createPose();
+  const goal = createPose();
+  // The described position, written exactly on landing rather than through angles.
+  const goalPosition = new Vector3();
+  const lookAt = new Vector3();
+  let shown = false;
+  let easing = false;
+  let damping = 0;
+  let spin = 0;
+  let spun = 0;
+  let held = false;
+  let last = 0;
+
+  const turning = (): boolean => spin !== 0 && !held;
+
+  const aimGoal = (): void => {
+    copyPose(goal, described);
+    goal.spherical.theta += spun;
+  };
+
+  const land = (camera: PerspectiveCamera | OrthographicCamera): void => {
+    copyPose(current, goal);
+    easing = false;
+    if (spun !== 0) {
+      write(camera, goal);
+      return;
+    }
+    camera.position.copy(goalPosition);
+    camera.lookAt(goal.target);
+    writeZoom(camera, goal.zoom);
+  };
+
+  const settle: CameraMotion['settle'] = (camera) => {
+    if (shown) land(camera);
+  };
+
+  /** Whether `description` puts the camera somewhere other than the last description did. */
+  const moved = (description: Camera): boolean =>
+    !shown ||
+    !goalPosition.equals(position.fromArray(description.position)) ||
+    !described.target.equals(lookAt.fromArray(description.lookAt)) ||
+    described.zoom !== (description._tag === 'Orthographic' ? description.zoom : 1);
+
+  /** One step of easing toward the goal, `seconds` after the last. */
+  const ease = (camera: PerspectiveCamera | OrthographicCamera, seconds: number): void => {
+    const remaining = (1 - damping) ** (seconds * 60);
+    const k = 1 - remaining;
+    current.target.lerp(goal.target, k);
+    current.spherical.radius += (goal.spherical.radius - current.spherical.radius) * k;
+    current.spherical.phi += (goal.spherical.phi - current.spherical.phi) * k;
+    current.spherical.theta += turn(current.spherical.theta, goal.spherical.theta) * k;
+    current.zoom += (goal.zoom - current.zoom) * k;
+    if (remaining < 1e-4 || settled(current, goal)) land(camera);
+    else write(camera, current);
+  };
+
+  return {
+    aim: (camera, description, now, jump) => {
+      if (moved(description)) spun = 0;
+      readPose(described, description);
+      goalPosition.fromArray(description.position);
+      damping = description.damping;
+      spin = description.autoRotate;
+      last = now;
+      aimGoal();
+      if (jump || damping === 0 || !shown) {
+        shown = true;
+        land(camera);
+        return;
+      }
+      easing = !settled(current, goal);
+    },
+    step: (camera, now) => {
+      const seconds = Math.max(0, now - last);
+      last = now;
+      if (turning() && seconds > 0) {
+        // Clockwise seen from above for a positive speed, as `rotateLeft` turns.
+        spun -= turnRate * spin * seconds;
+        aimGoal();
+        easing = damping !== 0;
+        if (!easing) land(camera);
+      }
+      if (easing) ease(camera, seconds);
+      return easing || turning();
+    },
+    settle,
+    moving: () => easing || turning(),
+    hold: (next) => {
+      held = next;
+    },
+    turned: () => {
+      if (spun === 0) return undefined;
+      position.setFromSpherical(goal.spherical).add(goal.target);
+      return [position.x, position.y, position.z];
+    },
+  };
+};

package/src/kernel/clock.ts

@@ -0,0 +1,35 @@
+/**
+ * Scene time. Behaviours read elapsed seconds from here; pausing animation (for example
+ * under `prefers-reduced-motion`) freezes scene time while frames keep rendering, and
+ * resuming continues from the frozen value rather than jumping ahead.
+ *
+ * @module
+ */
+
+export type SceneClock = {
+  /** Scene seconds elapsed while animating. */
+  readonly elapsedSeconds: () => number;
+  /** Freezes (`false`) or resumes (`true`) scene time. Idempotent. */
+  readonly setAnimating: (animating: boolean) => void;
+  readonly animating: () => boolean;
+};
+
+/** Creates a scene clock over a monotonic source of seconds. */
+export const createSceneClock = (nowSeconds: () => number): SceneClock => {
+  const start = nowSeconds();
+  let frozenAt: number | undefined;
+  let paused = 0;
+  const elapsedSeconds = (): number => (frozenAt ?? nowSeconds()) - start - paused;
+  return {
+    elapsedSeconds,
+    setAnimating: (animating) => {
+      if (animating && frozenAt !== undefined) {
+        paused += nowSeconds() - frozenAt;
+        frozenAt = undefined;
+      } else if (!animating && frozenAt === undefined) {
+        frozenAt = nowSeconds();
+      }
+    },
+    animating: () => frozenAt === undefined,
+  };
+};

package/src/kernel/contactShadowPasses.ts

@@ -0,0 +1,207 @@
+/**
+ * Contact shadows, drawn by the frame loop with the scene's renderer: the passes, shared
+ * by every render kit, which supplies the materials (`ShadowMaterials`).
+ *
+ * Behavioural reference: Drei `src/core/ContactShadows.tsx` at `bf6f4ad`, itself after
+ * three.js's `webgl_shadow_contact` example by mrdoob (both MIT). As there, every drawn
+ * frame:
+ *
+ * 1. renders the scene from below with an orthographic camera into a texture, through a
+ *    depth material that turns nearness to the ground into shadow (alpha `1 − depth`,
+ *    colour `color · depth · 2`), with the background off and the shadow plane hidden;
+ * 2. blurs it horizontally and vertically (`blur / 256`), twice with `smooth` (the second
+ *    at 0.4 of the blur);
+ * 3. shows it on a transparent plane facing up.
+ *
+ * One difference: the blur passes draw a quad with their own camera, so they fill the
+ * texture wherever the shadows are placed. (Drei draws its quad at the world origin with
+ * the shadow camera, which leaves the blur empty when the shadows sit above `y = 0`.)
+ *
+ * @module
+ */
+import {
+  Color,
+  type Material,
+  Mesh,
+  MeshBasicMaterial,
+  OrthographicCamera,
+  PlaneGeometry,
+  Scene,
+  type Texture,
+  Vector3,
+} from 'three';
+
+import type { ContactShadows } from './description.ts';
+import type { RenderTarget, SceneRenderer } from './renderer.ts';
+import type { ContactShadowPasses, ShadowedScene } from './renderKit.ts';
+
+/** One blur direction's material, and how to point it at a texture by an amount. */
+export type BlurPass = {
+  readonly material: Material;
+  /** Reads `source`, blurring by `amount` of the texture's width (or height). */
+  readonly set: (source: Texture, amount: number) => void;
+};
+
+/** What a render kit draws contact shadows with. */
+export type ShadowMaterials = {
+  /**
+   * The material the scene is drawn through from below: colour `color · depth · 2`, alpha
+   * `1 − depth`, no depth test or write.
+   */
+  readonly depth: (color: Color) => Material;
+  readonly blur: (direction: 'horizontal' | 'vertical') => BlurPass;
+  /**
+   * Whether the renderer reads a target's texture with v running the other way from
+   * WebGL's: three's WebGPU renderer does, on either backend.
+   */
+  readonly flippedTargets: boolean;
+};
+
+/** Everything one set of contact shadows holds while shown. */
+type Shown = {
+  readonly description: ContactShadows;
+  readonly plane: Mesh<PlaneGeometry, MeshBasicMaterial>;
+  readonly camera: OrthographicCamera;
+  readonly target: RenderTarget;
+  readonly blurTarget: RenderTarget;
+  readonly color: Color;
+  readonly depthMaterial: Material;
+  readonly horizontal: BlurPass;
+  readonly vertical: BlurPass;
+  readonly quad: Mesh<PlaneGeometry, Material>;
+  readonly quadScene: Scene;
+  readonly quadCamera: OrthographicCamera;
+};
+
+const up = new Vector3(0, 1, 0);
+const aim = new Vector3();
+
+/**
+ * The plane's geometry: flat, facing up, its texture's v running towards +z as the shadow
+ * camera's image does (already so where the renderer reads targets flipped).
+ */
+const groundGeometry = (width: number, depth: number, flipped: boolean): PlaneGeometry => {
+  const geometry = new PlaneGeometry(width, depth).rotateX(-Math.PI / 2);
+  if (flipped) return geometry;
+  const uv = geometry.getAttribute('uv');
+  for (let i = 0; i < uv.count; i++) uv.setY(i, 1 - uv.getY(i));
+  return geometry;
+};
+
+/** Whether a change needs new targets, geometry or camera rather than an update. */
+const reshaped = (a: ContactShadows, b: ContactShadows): boolean =>
+  a.resolution !== b.resolution || a.size[0] !== b.size[0] || a.size[1] !== b.size[1];
+
+/** Creates the contact shadow passes for one scene graph and renderer, with `materials`. */
+export const createContactShadowPasses = (
+  graph: ShadowedScene,
+  renderer: SceneRenderer,
+  materials: ShadowMaterials,
+): ContactShadowPasses => {
+  let shown: Shown | undefined;
+
+  const release = (): void => {
+    if (shown === undefined) return;
+    shown.plane.removeFromParent();
+    shown.plane.geometry.dispose();
+    shown.plane.material.dispose();
+    shown.target.dispose();
+    shown.blurTarget.dispose();
+    shown.depthMaterial.dispose();
+    shown.horizontal.material.dispose();
+    shown.vertical.material.dispose();
+    shown.quad.geometry.dispose();
+    shown = undefined;
+  };
+
+  const build = (description: ContactShadows): Shown => {
+    const [width, depth] = description.size;
+    const target = renderer.createTarget(description.resolution, description.resolution);
+    const blurTarget = renderer.createTarget(description.resolution, description.resolution);
+    const material = new MeshBasicMaterial({
+      map: target.texture,
+      transparent: true,
+      depthWrite: false,
+    });
+    const plane = new Mesh(groundGeometry(width, depth, materials.flippedTargets), material);
+    // Shadows are scenery: never picked, never in the way of an overlay.
+    plane.raycast = () => undefined;
+    graph.scene.add(plane);
+    const color = new Color();
+    const quad = new Mesh<PlaneGeometry, Material>(new PlaneGeometry(2, 2));
+    // In front of the quad camera, between its near and far planes.
+    quad.position.z = -0.5;
+    const quadScene = new Scene();
+    quadScene.add(quad);
+    return {
+      description,
+      plane,
+      camera: new OrthographicCamera(-width / 2, width / 2, depth / 2, -depth / 2, 0, 1),
+      target,
+      blurTarget,
+      color,
+      depthMaterial: materials.depth(color),
+      horizontal: materials.blur('horizontal'),
+      vertical: materials.blur('vertical'),
+      quad,
+      quadScene,
+      quadCamera: new OrthographicCamera(-1, 1, 1, -1, 0, 1),
+    };
+  };
+
+  /** Applies the fields that change in place: placement, reach, colour and opacity. */
+  const update = (current: Shown, description: ContactShadows): Shown => {
+    current.plane.position.fromArray(description.position);
+    current.plane.material.opacity = description.opacity;
+    current.color.setHex(description.color);
+    current.camera.position.fromArray(description.position);
+    // Looking straight up, with +z as the image's up: its v runs towards +z, as the plane's.
+    current.camera.up.set(0, 0, 1);
+    current.camera.lookAt(aim.copy(current.camera.position).add(up));
+    current.camera.near = description.near;
+    current.camera.far = description.far;
+    current.camera.updateProjectionMatrix();
+    current.camera.updateMatrixWorld();
+    return { ...current, description };
+  };
+
+  /** One blur: horizontally into the spare target, then vertically back. */
+  const blurPass = (current: Shown, amount: number): void => {
+    const { horizontal, vertical, quad, quadScene, quadCamera } = current;
+    quad.material = horizontal.material;
+    horizontal.set(current.target.texture, amount / 256);
+    renderer.render(quadScene, quadCamera, undefined, current.blurTarget);
+    quad.material = vertical.material;
+    vertical.set(current.blurTarget.texture, amount / 256);
+    renderer.render(quadScene, quadCamera, undefined, current.target);
+  };
+
+  const render = (current: Shown): void => {
+    const { scene } = graph;
+    const background = scene.background;
+    const override = scene.overrideMaterial;
+    current.plane.visible = false;
+    scene.background = null;
+    scene.overrideMaterial = current.depthMaterial;
+    renderer.render(scene, current.camera, undefined, current.target);
+    scene.overrideMaterial = override;
+    scene.background = background;
+    current.plane.visible = true;
+    blurPass(current, current.description.blur);
+    if (current.description.smooth) blurPass(current, current.description.blur * 0.4);
+  };
+
+  return {
+    draw: () => {
+      const description = graph.contactShadows();
+      if (description === null) {
+        release();
+        return;
+      }
+      if (shown !== undefined && reshaped(shown.description, description)) release();
+      shown = update(shown ?? build(description), description);
+      render(shown);
+    },
+    dispose: release,
+  };
+};