@opsydyn/effect-three 0.2.0 → 0.4.0

package/src/kernel/pointBuffers.ts

@@ -0,0 +1,115 @@
+/**
+ * The buffers a render kit draws points from, made from their look: given points as
+ * they are, Drei's sparkles and stars scattered as Drei scatters them (`Sparkles.tsx`,
+ * `Stars.tsx` at `bf6f4ad`) but from a seed, so the same look gives the same buffers.
+ *
+ * @module
+ */
+import { Color, Spherical, Vector3 } from 'three';
+
+import type { PointLook } from './description.ts';
+import { seededRandom } from './seeded.ts';
+
+/** Per-point attributes: three numbers a point for positions, colours and noise. */
+export type PointBuffers = {
+  readonly count: number;
+  readonly positions: Float32Array;
+  readonly colors: Float32Array;
+  readonly sizes: Float32Array;
+  /** Sparkles only: each mote's drift speed, opacity and noise. */
+  readonly speeds: Float32Array;
+  readonly opacities: Float32Array;
+  readonly noise: Float32Array;
+};
+
+const linear = new Color();
+
+const dots = (look: Extract<PointLook, { readonly _tag: 'Dots' }>): PointBuffers => {
+  const count = look.positions.length;
+  const colors = new Float32Array(count * 3);
+  for (let point = 0; point < count; point++) {
+    linear.setHex(look.colors?.[point] ?? look.color).toArray(colors, point * 3);
+  }
+  return {
+    count,
+    positions: Float32Array.from(look.positions.flat()),
+    colors,
+    sizes: Float32Array.from({ length: count }, (_, point) => look.sizes?.[point] ?? 1),
+    speeds: new Float32Array(0),
+    opacities: new Float32Array(0),
+    noise: new Float32Array(0),
+  };
+};
+
+/** Drei's `Sparkles`: positions spread through the box, random sizes unless given. */
+const sparkles = (look: Extract<PointLook, { readonly _tag: 'Sparkles' }>): PointBuffers => {
+  const random = seededRandom(look.seed);
+  // three's `MathUtils.randFloatSpread`, as Drei spreads them, from the seed.
+  const spread = (range: number) => range * (0.5 - random());
+  const { count } = look;
+  const positions = new Float32Array(count * 3);
+  for (let point = 0; point < count; point++) {
+    positions[point * 3] = spread(look.scale[0]);
+    positions[point * 3 + 1] = spread(look.scale[1]);
+    positions[point * 3 + 2] = spread(look.scale[2]);
+  }
+  const colors = new Float32Array(count * 3);
+  linear.setHex(look.color);
+  for (let point = 0; point < count; point++) linear.toArray(colors, point * 3);
+  const noise = new Float32Array(count * 3);
+  for (let point = 0; point < count; point++) noise.set(look.noise, point * 3);
+  return {
+    count,
+    positions,
+    colors,
+    sizes: Float32Array.from({ length: count }, () => look.size ?? random()),
+    speeds: new Float32Array(count).fill(look.speed),
+    opacities: new Float32Array(count).fill(look.opacity),
+    noise,
+  };
+};
+
+/** Drei's `Stars`: a shell of stars, nearer ones later, hues round the colour wheel. */
+const stars = (look: Extract<PointLook, { readonly _tag: 'Stars' }>): PointBuffers => {
+  const random = seededRandom(look.seed);
+  const { count } = look;
+  const positions = new Float32Array(count * 3);
+  const colors = new Float32Array(count * 3);
+  const sizes = Float32Array.from({ length: count }, () => (0.5 + 0.5 * random()) * look.factor);
+  const place = new Vector3();
+  const spherical = new Spherical();
+  const increment = look.depth / count;
+  let radius = look.radius + look.depth;
+  for (let star = 0; star < count; star++) {
+    radius -= increment * random();
+    place.setFromSpherical(
+      spherical.set(radius, Math.acos(1 - random() * 2), random() * 2 * Math.PI),
+    );
+    place.toArray(positions, star * 3);
+    linear.setHSL(star / count, look.saturation, 0.9).toArray(colors, star * 3);
+  }
+  return {
+    count,
+    positions,
+    colors,
+    sizes,
+    speeds: new Float32Array(0),
+    opacities: new Float32Array(0),
+    noise: new Float32Array(0),
+  };
+};
+
+/** The buffers for a look. */
+export const pointBuffers = (look: PointLook): PointBuffers => {
+  switch (look._tag) {
+    case 'Dots':
+      return dots(look);
+    case 'Sparkles':
+      return sparkles(look);
+    case 'Stars':
+      return stars(look);
+  }
+};
+
+/** Whether a look moves on its own: sparkles drift and stars twinkle in scene time. */
+export const animatedLook = (look: PointLook): boolean => look._tag !== 'Dots';

package/src/kernel/pointer.ts

@@ -209,6 +209,18 @@ export type SceneEvent =
     }
   /** A drag, wheel or pinch on the canvas, when the scene claims gestures. */
   | { readonly _tag: 'Gesture'; readonly gesture: Gesture }
+  /**
+   * A gesture that moved has ended: released, or the pointer left. Only after a `Drag`
+   * or `Pinch`, with the press's button, modifiers, mesh and view: the moment to finish
+   * what the gesture drew, such as a selection box.
+   */
+  | {
+      readonly _tag: 'GestureEnd';
+      readonly button: number;
+      readonly modifiers: Modifiers;
+      readonly key?: string;
+      readonly view?: string;
+    }
   /**
    * A gesture is about to begin on a camera that has turned by itself (`autoRotate`):
    * where it got to, so the Model can keep it (`autoRotated(camera, detail)`) and the
@@ -359,6 +371,12 @@ const pathOf = (graph: SceneGraph, object: Object3D): ReadonlyArray<string> => {
   return path;
 };
 
+/** Whether an object and every ancestor are visible. */
+const shown = (object: Object3D): boolean => {
+  for (let at: Object3D | null = object; at !== null; at = at.parent) if (!at.visible) return false;
+  return true;
+};
+
 /** Creates a raycasting picker over a graph's interactive meshes and groups. */
 export const createPicker = (graph: SceneGraph): Picker => {
   const raycaster = new Raycaster();
@@ -399,12 +417,17 @@ export const createPicker = (graph: SceneGraph): Picker => {
   const rayOrigin = new Vector3();
   const rayDirection = new Vector3();
 
-  /** The nearest keyed hit along the raycaster's ray, reporting `view` when there is one. */
-  const nearestHit = (view: string | undefined): Hit | undefined => {
+  /**
+   * The nearest keyed hit in `on` (the scene's graph or its HUD's) along the raycaster's
+   * ray, reporting `view` when there is one.
+   */
+  const nearestHit = (on: SceneGraph, view: string | undefined): Hit | undefined => {
     // Recursive, so an interactive group makes every mesh inside it pickable.
-    for (const intersection of raycaster.intersectObjects(graph.interactiveObjects(), true)) {
-      const owner = keyedOwner(graph, intersection.object);
-      const key = owner === undefined ? undefined : graph.keyOf(owner);
+    for (const intersection of raycaster.intersectObjects(on.interactiveObjects(), true)) {
+      // Hidden things are not hit: a level of detail not showing, as three's `LOD.raycast`.
+      if (!shown(intersection.object)) continue;
+      const owner = keyedOwner(on, intersection.object);
+      const key = owner === undefined ? undefined : on.keyOf(owner);
       if (owner !== undefined && key !== undefined) {
         normal.set(0, 0, 0);
         if (intersection.face) {
@@ -413,13 +436,13 @@ export const createPicker = (graph: SceneGraph): Picker => {
         const instance =
           intersection.instanceId === undefined
             ? undefined
-            : graph.instanceKeyOf(intersection.object, intersection.instanceId);
+            : on.instanceKeyOf(intersection.object, intersection.instanceId);
         return {
           key,
           ...(instance === undefined ? {} : { instance }),
           ...partOf(owner, intersection.object),
           ...(view === undefined ? {} : { view }),
-          path: pathOf(graph, owner),
+          path: pathOf(on, owner),
           point: toVec3(intersection.point),
           distance: intersection.distance,
           normal: toVec3(normal),
@@ -431,6 +454,17 @@ export const createPicker = (graph: SceneGraph): Picker => {
     return undefined;
   };
 
+  /** A hit on the HUD's interactive meshes, which are over everything else. */
+  const hudHit = (x: number, y: number): Hit | undefined => {
+    const hud = graph.hud();
+    if (hud === undefined || hud.graph.interactiveObjects().length === 0) return undefined;
+    hud.graph.scene.updateMatrixWorld();
+    hud.graph.camera.updateMatrixWorld();
+    ndc.set(x, y);
+    raycaster.setFromCamera(ndc, hud.graph.camera);
+    return nearestHit(hud.graph, undefined);
+  };
+
   const currentRay = (): Ray => ({
     origin: toVec3(raycaster.ray.origin),
     direction: toVec3(raycaster.ray.direction),
@@ -464,10 +498,12 @@ export const createPicker = (graph: SceneGraph): Picker => {
     holdCameras: graph.holdCameras,
     turned: graph.turned,
     pick: (x, y) => {
+      const hud = hudHit(x, y);
+      if (hud !== undefined) return hud;
       if (graph.interactiveObjects().length === 0) return undefined;
       const view = aim(x, y);
       if (view === false) return undefined;
-      return nearestHit(view);
+      return nearestHit(graph, view);
     },
     pickRay: (ray) => {
       if (graph.interactiveObjects().length === 0) return undefined;
@@ -476,7 +512,7 @@ export const createPicker = (graph: SceneGraph): Picker => {
         rayOrigin.fromArray(ray.origin),
         rayDirection.fromArray(ray.direction).normalize(),
       );
-      return nearestHit(undefined);
+      return nearestHit(graph, undefined);
     },
     viewport: graph.viewport,
   };
@@ -524,6 +560,8 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
   const pressedPointers = new Map<number, Point>();
   let primary: number | undefined;
   let gesturePress: GesturePress | undefined;
+  // Whether the gesture press has moved: only then does its release end a gesture.
+  let gestureMoved = false;
   let hovered: string | undefined;
   // The latest press, kept after release: double-click and context-menu events follow it.
   let press: Press | undefined;
@@ -616,6 +654,7 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
     pressedPointers.clear();
     primary = id;
     pressedPointers.set(id, { x: event.x, y: event.y });
+    gestureMoved = false;
     const region = picker.region(event.x, event.y);
     reportTurned(region, events);
     // Cameras turning by themselves hold still while it is pressed, as `OrbitControls`.
@@ -633,6 +672,7 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
     const from = pressedPointers.get(id);
     if (from === undefined || gesturePress === undefined) return;
     pressedPointers.set(id, to);
+    gestureMoved = true;
     const { view, width, height, x, y } = gesturePress;
     const region = { ...(view === undefined ? {} : { view }), width, height, x, y };
     const moved = pixels(from, to);
@@ -672,11 +712,22 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
     });
   };
 
-  const endGestures = (): void => {
+  const endGestures = (events: Array<SceneEvent>): void => {
     if (gesturePress !== undefined) picker.holdCameras(false);
+    if (gesturePress !== undefined && gestureMoved) {
+      const { button, modifiers, key, view } = gesturePress;
+      events.push({
+        _tag: 'GestureEnd',
+        button,
+        modifiers,
+        ...(key === undefined ? {} : { key }),
+        ...(view === undefined ? {} : { view }),
+      });
+    }
     pressedPointers.clear();
     primary = undefined;
     gesturePress = undefined;
+    gestureMoved = false;
   };
 
   /**
@@ -706,7 +757,7 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
     if (isSecondary(event, id)) return secondary(event, id);
     const events: Array<SceneEvent> = [];
     if (event._tag === 'PointerLeave') {
-      endGestures();
+      endGestures(events);
       // A cancelled or abandoned press still ends its drag, at the last known position.
       if (position !== undefined) endDrag(captured(), position.x, position.y, events);
       dragged = false;
@@ -740,7 +791,7 @@ export const createPointerTracker = (picker: Picker): PointerTracker => {
         release(hit, event, events);
         // Any release ends capture: a mouse's buttons share one pointer.
         endDrag(drag, event.x, event.y, events);
-        endGestures();
+        endGestures(events);
         break;
       case 'DoubleClick':
         if (hit !== undefined && pressed(hit)) {

package/src/kernel/renderKit.ts

@@ -9,7 +9,7 @@
  */
 import type { Object3D, Scene } from 'three';
 
-import type { ContactShadows, ShaderGridNode, Sky } from './description.ts';
+import type { ContactShadows, LineNode, PointsNode, ShaderGridNode, Sky } from './description.ts';
 import type { SceneRenderer } from './renderer.ts';
 
 /** A sky as a kit draws it: the object the graph adds to its scene, never picked. */
@@ -26,6 +26,24 @@ export type HostedShaderGrid = {
   readonly dispose: () => void;
 };
 
+/** A line as a kit draws it (three's fat lines), inside the node's wrapper. */
+export type HostedLine = {
+  readonly object: Object3D;
+  /** Applies new points or a new look; the wrapper carries the transform. */
+  readonly update: (line: LineNode) => void;
+  readonly dispose: () => void;
+};
+
+/** Points as a kit draws them, inside the node's wrapper. */
+export type HostedPoints = {
+  readonly object: Object3D;
+  /** Applies a new look; the wrapper carries the transform. */
+  readonly update: (points: PointsNode) => void;
+  /** Moves sparkles and twinkles stars to scene time `seconds`. */
+  readonly tick: (seconds: number) => void;
+  readonly dispose: () => void;
+};
+
 /** The contact shadow passes for one scene, drawn by the frame loop before each frame. */
 export type ContactShadowPasses = {
   /** Draws the scene's contact shadows, if it has any, before the frame is drawn. */
@@ -50,5 +68,9 @@ export type RenderKit = {
   readonly shading: 'webgl' | 'tsl';
   readonly sky: () => HostedSky;
   readonly shaderGrid: (node: ShaderGridNode) => HostedShaderGrid;
+  /** Draws a line; a kit without lines leaves them empty. */
+  readonly line?: (node: LineNode) => HostedLine;
+  /** Draws points; a kit without points leaves them empty. */
+  readonly points?: (node: PointsNode) => HostedPoints;
   readonly contactShadows: (graph: ShadowedScene, renderer: SceneRenderer) => ContactShadowPasses;
 };

package/src/kernel/renderer.ts

@@ -43,6 +43,12 @@ export type SceneRenderer = {
    * otherwise across the whole surface.
    */
   readonly render: (scene: Scene, camera: Camera, area?: RenderArea, target?: RenderTarget) => void;
+  /**
+   * Draws `scene` over what the surface already shows, across the whole of it: keeping
+   * the colour, clearing only depth (a HUD, as Drei's `Hud` draws). Without it, a HUD is
+   * not drawn. Not while presenting immersively.
+   */
+  readonly renderOver?: (scene: Scene, camera: Camera) => void;
   /** Creates an offscreen target of `width` × `height` pixels to render into. */
   readonly createTarget: (width: number, height: number) => RenderTarget;
   /**

package/src/kernel/resources.ts

@@ -22,17 +22,21 @@ import {
   CircleGeometry,
   ConeGeometry,
   CylinderGeometry,
+  Euler,
   ExtrudeGeometry,
   Material,
   type Object3D,
   type Texture,
   PlaneGeometry,
+  Quaternion,
   RingGeometry,
+  Shape,
   ShapeGeometry as ShapeGeometry3,
   SphereGeometry,
   TorusGeometry,
 } from 'three';
 import type { Font } from 'three/addons/loaders/FontLoader.js';
+import { toCreasedNormals } from 'three/addons/utils/BufferGeometryUtils.js';
 
 import type {
   GeometryRef,
@@ -191,6 +195,67 @@ const buildText = (shape: TextGeometry, font: Font | undefined): BufferGeometry
   return geometry;
 };
 
+/** Drei's `RoundedBox` nudge, keeping its corner arcs from being zero length. */
+const roundedEpsilon = 0.00001;
+
+/**
+ * Drei's `RoundedBox` (`bf6f4ad`): the corners' arcs drawn tiny and the bevel making the
+ * rounding, extruded through the depth less the bevels, centred, and its normals creased
+ * (three's `toCreasedNormals`, which Drei takes from three-stdlib).
+ */
+const buildRoundedBox = (shape: Extract<ShapeGeometry, { readonly _tag: 'RoundedBox' }>) => {
+  const { width, height, depth, radius } = shape;
+  const outline = new Shape();
+  const inset = radius - roundedEpsilon;
+  const e = roundedEpsilon;
+  outline.absarc(e, e, e, -Math.PI / 2, -Math.PI, true);
+  outline.absarc(e, height - inset * 2, e, Math.PI, Math.PI / 2, true);
+  outline.absarc(width - inset * 2, height - inset * 2, e, Math.PI / 2, 0, true);
+  outline.absarc(width - inset * 2, e, e, 0, -Math.PI / 2, true);
+  const geometry = new ExtrudeGeometry(outline, {
+    depth: depth - radius * 2,
+    bevelEnabled: true,
+    bevelSegments: shape.bevelSegments * 2,
+    steps: shape.steps,
+    bevelSize: radius - roundedEpsilon,
+    bevelThickness: radius,
+    curveSegments: shape.smoothness,
+  });
+  geometry.center();
+  return toCreasedNormals(geometry, shape.creaseAngle);
+};
+
+/** Drei's `Backdrop` mesh turn, built into the geometry: the floor flat, the wall behind. */
+const backdropTurn = new Quaternion().setFromEuler(new Euler(-Math.PI / 2, 0, Math.PI / 2));
+
+/** Drei's `Backdrop` easing: the floor stays flat, then sweeps up. */
+const easeInExpo = (x: number): number => (x === 0 ? 0 : 2 ** (10 * x - 10));
+
+/**
+ * Drei's `Backdrop` (`bf6f4ad`): a unit plane whose rows rise by an exponential ease, its
+ * first row pulled forward by `floor`, then turned as Drei turns its mesh.
+ */
+const buildBackdrop = (shape: Extract<ShapeGeometry, { readonly _tag: 'Backdrop' }>) => {
+  const { segments, floor } = shape;
+  const geometry = new PlaneGeometry(1, 1, segments, segments);
+  const position = geometry.getAttribute('position');
+  const offset = 0.5;
+  let vertex = 0;
+  for (let x = 0; x < segments + 1; x++) {
+    for (let y = 0; y < segments + 1; y++) {
+      position.setXYZ(
+        vertex++,
+        x / segments - offset + (x === 0 ? -floor : 0),
+        y / segments - offset,
+        easeInExpo(x / segments),
+      );
+    }
+  }
+  position.needsUpdate = true;
+  geometry.computeVertexNormals();
+  return geometry.applyQuaternion(backdropTurn);
+};
+
 /** Builds the three.js geometry for a shape description. */
 const buildShape = (
   shape: ShapeGeometry,
@@ -232,6 +297,10 @@ const buildShape = (
       return new RingGeometry(shape.innerRadius, shape.outerRadius, shape.thetaSegments);
     case 'Circle':
       return new CircleGeometry(shape.radius, shape.segments);
+    case 'RoundedBox':
+      return buildRoundedBox(shape);
+    case 'Backdrop':
+      return buildBackdrop(shape);
   }
 };