@solidrt/3d 0.0.46 → 0.0.47

package/src/math.ts

@@ -9,7 +9,9 @@
 // interpreter. Mat4 is a 16-tuple so constant-index access stays plain
 // `number` under noUncheckedIndexedAccess.
 
+export type Vec2 = [number, number]
 export type Vec3 = [number, number, number]
+export type Vec4 = [number, number, number, number]
 // prettier-ignore
 export type Mat4 = [
   number, number, number, number,
@@ -39,6 +41,20 @@ export function copy(out: Mat4, m: Mat4): Mat4 {
   return out
 }
 
+/**
+ * Transform a point by m with w = 1, keeping the homogeneous result: the
+ * clip-space building block (scene.project, picking). The caller owns the
+ * perspective divide and the w <= 0 behind-the-camera test.
+ */
+export function transformPoint(out: Vec4, m: Mat4, p: Vec3): Vec4 {
+  let x = p[0], y = p[1], z = p[2]
+  out[0] = m[0] * x + m[4] * y + m[8] * z + m[12]
+  out[1] = m[1] * x + m[5] * y + m[9] * z + m[13]
+  out[2] = m[2] * x + m[6] * y + m[10] * z + m[14]
+  out[3] = m[3] * x + m[7] * y + m[11] * z + m[15]
+  return out
+}
+
 /** out = a * b (column vectors: b applies first). out may alias a or b. */
 export function multiply(out: Mat4, a: Mat4, b: Mat4): Mat4 {
   let a00 = a[0], a01 = a[1], a02 = a[2], a03 = a[3]
@@ -93,6 +109,30 @@ export function compose(out: Mat4, position: Vec3, rotation: Vec3, scale: Vec3):
   return out
 }
 
+/**
+ * The normal matrix for a world matrix: the inverse-transpose of its upper
+ * 3x3 (the cofactor matrix over the determinant), packed into a mat4 - the
+ * engine's settable uniform set has no mat3, so shaders take `mat3(uNormal)`.
+ * Correct under any transform including non-uniform scale, where
+ * `mat3(uModel)` would bend normals off the surface. A degenerate
+ * (zero-scale) input yields the raw cofactors instead of NaNs.
+ */
+export function normalMatrix(out: Mat4, m: Mat4): Mat4 {
+  let a = m[0], b = m[4], c = m[8]
+  let d = m[1], e = m[5], f = m[9]
+  let g = m[2], h = m[6], i = m[10]
+  let c00 = e * i - f * h
+  let c01 = f * g - d * i
+  let c02 = d * h - e * g
+  let det = a * c00 + b * c01 + c * c02
+  let s = 1 / (det || 1)
+  out[0] = c00 * s; out[1] = (c * h - b * i) * s; out[2] = (b * f - c * e) * s; out[3] = 0
+  out[4] = c01 * s; out[5] = (a * i - c * g) * s; out[6] = (c * d - a * f) * s; out[7] = 0
+  out[8] = c02 * s; out[9] = (b * g - a * h) * s; out[10] = (a * e - b * d) * s; out[11] = 0
+  out[12] = 0; out[13] = 0; out[14] = 0; out[15] = 1
+  return out
+}
+
 /**
  * Right-handed perspective projection with the engine's y-down clip flip
  * BAKED IN (row two is negated): geometry authored y-up displays y-up, and

package/src/orbit.ts

@@ -1,6 +1,38 @@
 // An orbit camera for a scene: azimuth/elevation/distance around a target,
-// with drag-to-rotate, wheel-to-zoom, optional auto-orbit, and clamps - the
-// standard interactive-viewer camera, extracted so apps stop rebuilding it.
+// with drag-to-rotate, pinch- and wheel-to-zoom, optional auto-orbit, and
+// clamps - the standard interactive-viewer camera, extracted so apps stop
+// rebuilding it.
+//
+// Input goes through core's merged transform recognizer (createTransform), so
+// the drag participates in the gesture arena: on a viewport embedded in a
+// scrollable layout, an orbit drag and the ancestor scroller's pan arbitrate
+// instead of both acting, and rotation only starts once the drag crosses the
+// recognizer's slop. One finger (or a mouse drag) rotates; two-finger pinch
+// zooms (pair rotation is ignored); wheel zooms directly - no recognizer
+// needed for a discrete wheel step. What two-finger translation means
+// depends on `viewport`: with it, two fingers pan - the scene slides under
+// the fingers 1:1 at the target's depth, the touch convention everywhere
+// (three.js DOLLY_PAN, Sketchfab, touch CAD) - which also keeps an
+// imperfect pinch from smearing rotation into the zoom. Without it there
+// is no pixel-to-world mapping, so focal translation falls back to
+// rotating regardless of finger count.
+//
+// Zoom aims at the target by default. With `zoomAnchor` the app maps the
+// pinch focal / wheel cursor to a world point, and the zoom scales the pose
+// about that point instead - the spot under the fingers stays under the
+// fingers, with the target sliding toward it. Only the app can own that
+// mapping: screen-to-ray needs the projection and the element's placement
+// (fov, aspect, viewBox scaling), which live in the app's camera and layout,
+// not here.
+//
+// Anchored zoom leaves the target wherever the zoom carried it - possibly a
+// point in empty air near the eye, and a drag orbiting THAT swings the scene
+// wildly around nothing. `rotateAnchor` is the countermeasure: at gesture
+// start the app names the world point rotation should pivot about (what the
+// camera is actually looking at), and the pivot is re-seated there. The
+// point is projected onto the view axis first, so re-seating moves only the
+// target's depth - the eye and the picture do not change, only what a drag
+// swings around.
 //
 // Pose is plain mutable state advanced by update(dt) from the app's own
 // onFrame; the control registers no frame loop of its own, so whether
@@ -8,11 +40,14 @@
 // animation costs nothing). Only `orbiting` is a signal - slow UI state
 // that HUDs read - while the pose moves at frame rate and bypasses
 // reactivity: the package's structure-vs-motion split. update() pushes the
-// pose to the scene camera only when it actually changed, and reports
-// that, so per-frame dependents (a uCamPos uniform) can follow the camera
-// without writing every frame.
+// pose to the scene camera only when it actually changed (one setCamera:
+// the scene's own shared write carries uViewProj and uCamPos), and reports
+// that, so per-frame dependents (reprojecting HUD overlays via
+// scene.project) can follow the camera without recomputing every frame.
 
 import { createSignal } from "@solidjs/signals"
+import { createTransform } from "@solidrt/core"
+import type { PointerEvent } from "@solidrt/core"
 import type { Scene } from "./scene.ts"
 import type { Vec3 } from "./math.ts"
 
@@ -35,11 +70,38 @@ export type OrbitCameraOptions = {
   minElevation?: number
   maxElevation?: number
   /** Auto-orbit rate in radians/second (default 0: none). Runs while
-   * `orbiting()` and not dragging; toggle with set({ orbiting }). */
+   * `orbiting()` and no drag/pinch is in progress; toggle with
+   * set({ orbiting }). */
   orbitSpeed?: number
-  /** Multipliers over the built-in drag/wheel sensitivities. */
+  /** Multipliers over the built-in drag and zoom (wheel + pinch) sensitivities. */
   rotateSpeed?: number
   zoomSpeed?: number
+  /** Multiplier over the two-finger pan (1 = the scene tracks the fingers
+   * exactly at the target's depth). */
+  panSpeed?: number
+  /** The viewport the pointer coordinates live in: height in the same
+   * logical units as clientX/clientY, and the camera's vertical fov in
+   * degrees. Providing it enables two-finger pan; without it two-finger
+   * translation rotates, as it always did. */
+  viewport?: () => { height: number; fov: number }
+  /** Constrain where a pan may put the target - return the target to use.
+   * The typical use: keep the pivot within a few radii of the subject so
+   * panning cannot strand the camera. Zoom and rotation do not consult it. */
+  clampTarget?: (target: Vec3) => Vec3
+  /** Map a screen point (window coordinates, the clientX/clientY frame) to
+   * the world point a zoom there should keep pinned. Called once per pinch
+   * gesture (at its first span change - the anchor then holds for the whole
+   * gesture, see the jitter note at `pinchAnchor`) and once per wheel event,
+   * with the pose the zoom is about to apply to. Return null to zoom toward
+   * the target as usual (also the default). */
+  zoomAnchor?: (x: number, y: number, view: { eye: Vec3; target: Vec3 }) => Vec3 | null
+  /** The world point rotation should pivot about - called when a drag or
+   * pinch starts. It is projected onto the view axis and becomes the new
+   * target, preserving the picture exactly (only the pivot's depth moves),
+   * so a drag after an anchored zoom orbits the scene under the camera
+   * instead of wherever the zoom left the target. Points at or behind the
+   * eye are ignored, as is null (both keep the current pivot). */
+  rotateAnchor?: (view: { eye: Vec3; target: Vec3 }) => Vec3 | null
 }
 
 export type OrbitPose = {
@@ -68,10 +130,12 @@ export type OrbitCamera = {
   /** Spread onto the element that receives input:
    * `<window {...orbit.handlers} />`. */
   handlers: {
-    onPointerDown(e: { clientX: number; clientY: number }): void
-    onPointerMove(e: { clientX: number; clientY: number }): void
-    onPointerUp(): void
-    onWheel(e: { deltaY: number }): void
+    onPointerDown(e: PointerEvent): void
+    onPointerMove(e: PointerEvent): void
+    onPointerUp(e: PointerEvent): void
+    /** Position is optional so a bare `{ deltaY }` still zooms; without it
+     * a zoomAnchor cannot apply and the zoom falls back to the target. */
+    onWheel(e: { deltaY: number; clientX?: number; clientY?: number }): void
   }
 }
 
@@ -98,13 +162,33 @@ export function createOrbitCamera(scene: Scene, options: OrbitCameraOptions = {}
   let wheelZoom = WHEEL_ZOOM * (options.zoomSpeed ?? 1)
 
   let [orbiting, setOrbiting] = createSignal(orbitSpeed > 0)
-  let drag: { x: number; y: number } | null = null
+  let interacting = false
   let dirty = false
 
   let clampPose = () => {
     elevation = clampNum(elevation, minElevation, maxElevation)
     distance = clampNum(distance, minDistance, maxDistance)
   }
+  // Slide eye and target together along the camera's right/up so the scene
+  // tracks the fingers: dragged pixels map to world units through the
+  // frustum height at the target's depth. Screen +y is down, so the up-axis
+  // term is added (fingers down -> camera up -> scene follows down).
+  let pan = (dx: number, dy: number) => {
+    let vp = options.viewport!()
+    let wpp = ((2 * Math.tan((vp.fov * Math.PI) / 360) * distance) / vp.height) * (options.panSpeed ?? 1)
+    let sa = Math.sin(azimuth)
+    let ca = Math.cos(azimuth)
+    let se = Math.sin(elevation)
+    let ce = Math.cos(elevation)
+    // right = (ca, 0, -sa), up = (-sa*se, ce, -ca*se) for this pose - the
+    // camera basis written out for eye() = target + distance * (ce*sa, se, ce*ca).
+    let next: Vec3 = [
+      target[0] - dx * wpp * ca - dy * wpp * sa * se,
+      target[1] + dy * wpp * ce,
+      target[2] + dx * wpp * sa - dy * wpp * ca * se,
+    ]
+    target = options.clampTarget ? options.clampTarget(next) : next
+  }
   let eye = (): Vec3 => {
     let ce = Math.cos(elevation)
     return [
@@ -115,9 +199,97 @@ export function createOrbitCamera(scene: Scene, options: OrbitCameraOptions = {}
   }
   let apply = () => scene.setCamera({ position: eye(), target })
 
+  // Zoom by `ratio` (new distance over old, before clamping) about a world
+  // anchor (null zooms toward the target). Scaling eye and target about the
+  // anchor by the distance ratio keeps it projecting to the same pixel, so
+  // the shift below uses the ratio that actually applied after clamping -
+  // once distance pins at a clamp the target stops moving too, instead of
+  // sliding the view sideways under a dead zoom.
+  let zoomAbout = (ratio: number, anchor: Vec3 | null | undefined) => {
+    let prev = distance
+    // Bounds widen to the current distance so a pose already outside them
+    // (a rotateAnchor re-seat may land anywhere) zooms back toward range
+    // instead of snap-jumping into it.
+    distance = clampNum(distance * ratio, Math.min(minDistance, prev), Math.max(maxDistance, prev))
+    if (!anchor) return
+    let s = distance / prev
+    target = [
+      anchor[0] + (target[0] - anchor[0]) * s,
+      anchor[1] + (target[1] - anchor[1]) * s,
+      anchor[2] + (target[2] - anchor[2]) * s,
+    ]
+  }
+  let anchorAt = (x?: number, y?: number) =>
+    x !== undefined && y !== undefined && options.zoomAnchor
+      ? options.zoomAnchor(x, y, { eye: eye(), target: [target[0], target[1], target[2]] })
+      : null
+
+  // The pinch keeps ONE anchor for its whole gesture, taken at the first
+  // span change. Per-event re-derivation looks equivalent but jitters in
+  // practice: the two fingers' events interleave, so the measured span
+  // oscillates around its true value even while the fingers rest, and every
+  // event zooms slightly in or back out. About a fixed point those pairs
+  // cancel exactly (the ratios telescope); about a fresh anchor each time -
+  // a new raycast against a pose the previous event just moved, or the
+  // app's hit/fallback choice flipping between events - each pair leaves a
+  // residual target slide and the model visibly crawls under resting
+  // fingers. The wheel stays per-event: its notches are discrete, there is
+  // no noise to cancel, and each notch re-aiming at the cursor is the point.
+  let pinchAnchor: Vec3 | null = null
+  let pinchSeen = false
+
   clampPose()
   apply()
 
+  // One finger rotates. With two down, the span change zooms and the focal
+  // translation pans (or, with no viewport to map pixels through, keeps
+  // rotating). Pair rotation has no orbit meaning and is ignored.
+  let transform = createTransform({
+    onTransformStart: () => {
+      interacting = true
+      let anchor = options.rotateAnchor?.({ eye: eye(), target: [target[0], target[1], target[2]] })
+      if (anchor) {
+        let e = eye()
+        let fx = (target[0] - e[0]) / distance
+        let fy = (target[1] - e[1]) / distance
+        let fz = (target[2] - e[2]) / distance
+        let depth = (anchor[0] - e[0]) * fx + (anchor[1] - e[1]) * fy + (anchor[2] - e[2]) * fz
+        if (depth > 0) {
+          // Deliberately unclamped: the pose is unchanged, this only decides
+          // what the gesture pivots about. The zoom clamps below widen to
+          // the current distance, so a pivot outside [min, max] cannot make
+          // the next zoom snap-jump either.
+          distance = depth
+          target = [e[0] + fx * depth, e[1] + fy * depth, e[2] + fz * depth]
+        }
+      }
+    },
+    onTransformMove: (t) => {
+      if (t.pointers >= 2 && options.viewport) {
+        pan(t.dx, t.dy)
+      } else {
+        azimuth -= t.dx * dragAzimuth
+        elevation = clampNum(elevation + t.dy * dragElevation, minElevation, maxElevation)
+      }
+      if (t.scale !== 1) {
+        // Fingers spreading (scale > 1) zooms in: the distance shrinks by the
+        // span ratio, exponent-weighted by the zoomSpeed multiplier, about
+        // the gesture's anchor when the app provides one.
+        if (!pinchSeen) {
+          pinchSeen = true
+          pinchAnchor = anchorAt(t.x, t.y)
+        }
+        zoomAbout(1 / Math.pow(t.scale, options.zoomSpeed ?? 1), pinchAnchor)
+      }
+      dirty = true
+    },
+    onTransformEnd: () => {
+      interacting = false
+      pinchSeen = false
+      pinchAnchor = null
+    },
+  })
+
   return {
     eye,
     pose: () => ({ azimuth, elevation, distance }),
@@ -132,7 +304,7 @@ export function createOrbitCamera(scene: Scene, options: OrbitCameraOptions = {}
       dirty = true
     },
     update(dt) {
-      if (orbitSpeed !== 0 && drag === null && orbiting()) {
+      if (orbitSpeed !== 0 && !interacting && orbiting()) {
         azimuth += dt * orbitSpeed
         dirty = true
       }
@@ -142,21 +314,9 @@ export function createOrbitCamera(scene: Scene, options: OrbitCameraOptions = {}
       return true
     },
     handlers: {
-      onPointerDown(e) {
-        drag = { x: e.clientX, y: e.clientY }
-      },
-      onPointerMove(e) {
-        if (!drag) return
-        azimuth -= (e.clientX - drag.x) * dragAzimuth
-        elevation = clampNum(elevation + (e.clientY - drag.y) * dragElevation, minElevation, maxElevation)
-        drag = { x: e.clientX, y: e.clientY }
-        dirty = true
-      },
-      onPointerUp() {
-        drag = null
-      },
+      ...transform.handlers,
       onWheel(e) {
-        distance = clampNum(distance * Math.exp(e.deltaY * wheelZoom), minDistance, maxDistance)
+        zoomAbout(Math.exp(e.deltaY * wheelZoom), anchorAt(e.clientX, e.clientY))
         dirty = true
       },
     },