@solidrt/3d 0.0.55 → 0.0.56

package/src/orbit.ts

@@ -3,6 +3,12 @@
 // clamps - the standard interactive-viewer camera, extracted so apps stop
 // rebuilding it.
 //
+// Rotation is viewport-relative when the control knows its viewport
+// (OrbitCameraOptions.viewport): dragging one viewport height sweeps one
+// full turn, Three's OrbitControls convention, so the same drag feels the
+// same on a phone and a 4k window. Without a viewport it falls back to a
+// fixed angle per pixel.
+//
 // 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
@@ -21,9 +27,8 @@
 // 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, designSize scaling), which live in the app's camera and layout,
-// not here.
+// mapping: screen-to-ray needs the projection (fov, aspect), which lives
+// in the app's camera, 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
@@ -34,6 +39,13 @@
 // target's depth - the eye and the picture do not change, only what a drag
 // swings around.
 //
+// Every pointer coordinate here is in the input element's own frame: the
+// recognizer measures drag deltas in the element's parent frame and the
+// pinch focal in its local frame, and the wheel uses localX/localY, so a
+// viewport under a designSize fit or any scaled ancestor behaves the same
+// as one filling the window. `viewport().height` is therefore the
+// element's laid-out height, which the OrbitCamera component passes.
+//
 // 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
 // anything animates stays the app's decision (a paused orbit with no other
@@ -44,37 +56,60 @@
 // 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.
+//
+// Options are read where they apply, not copied out: the clamps, the rates
+// (auto-orbit, rotate, zoom, pan), `viewport` and the anchor callbacks are
+// re-read from the options object on every input or update, so a caller
+// may change a field (or hand in an object of getters, which is what
+// `<OrbitCamera>` does with its props) and the next gesture or frame sees
+// it. Only the initial pose is copied at creation; later pose changes go
+// through set().
 
 import { createSignal } from "@solidjs/signals"
 import { createTransform } from "@solidrt/core"
 import type { PointerEvent } from "@solidrt/core"
-import type { CameraUpdate } from "./scene.ts"
+import type { CameraUpdate } from "./camera.ts"
 import type { Vec3 } from "./math.ts"
 
-// Baseline sensitivities at rotateSpeed/zoomSpeed 1, in radians per dragged
-// pixel and zoom exponent per wheel-delta unit.
+// Baseline sensitivities at rotateSpeed/zoomSpeed 1. With a `viewport` the
+// rotation is viewport-relative: dragging one viewport height sweeps
+// DRAG_TURNS full turns on either axis (Three's OrbitControls convention),
+// so the feel survives any window size or form factor. Without one it
+// falls back to fixed radians per dragged pixel - the relative rule frozen
+// at a ~785 px viewport. Wheel zoom is an exponent per wheel-delta unit.
+const DRAG_TURNS = 1
 const DRAG_AZIMUTH = 0.008
 const DRAG_ELEVATION = 0.006
 const WHEEL_ZOOM = 0.0015
+// Default clamps: the distance floor keeps the eye off the target; the
+// elevation limits (radians) stop just short of the poles.
+const MIN_DISTANCE = 0.01
+const ELEVATION_LIMIT = 1.55
 
 /** What an orbit camera drives: a Scene, or one of its Views. */
 export type OrbitTarget = { setCamera(update: CameraUpdate): void }
 
+/** The pose fields (target, azimuth, elevation, distance) are initial
+ * values, copied at creation and changed through set() afterwards. Every
+ * other field is live: read from this object where it applies, so a
+ * change takes effect on the next gesture or update. */
 export type OrbitCameraOptions = {
-  /** The point the camera orbits and looks at (default origin). */
+  /** Initial point the camera orbits and looks at (default origin). */
   target?: Vec3
   /** Initial pose, radians and world units. */
   azimuth?: number
   elevation?: number
   distance?: number
+  /** Distance clamps, world units. */
   minDistance?: number
   maxDistance?: number
   /** Elevation clamps, radians; the defaults stop just short of the poles. */
   minElevation?: number
   maxElevation?: number
   /** Auto-orbit rate in radians/second (default 0: none). Runs while
-   * `orbiting()` and no drag/pinch is in progress; toggle with
-   * set({ orbiting }). */
+   * `orbiting()` and no drag/pinch is in progress; `orbiting` starts on
+   * when the initial rate is positive and toggles with set({ orbiting }).
+   * A new rate applies from the next update. */
   orbitSpeed?: number
   /** Multipliers over the built-in drag and zoom (wheel + pinch) sensitivities. */
   rotateSpeed?: number
@@ -82,21 +117,25 @@ export type OrbitCameraOptions = {
   /** 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 }
+  /** The viewport the drag lives in: the input element's own height (its
+   * laid-out size, the frame the recognizer's deltas arrive in), and the
+   * camera's vertical fov in degrees; return null while neither is known
+   * yet. Providing it makes rotation viewport-relative (a drag across the
+   * viewport height is one full turn, whatever the window size) and
+   * enables two-finger pan; without it rotation is a fixed angle per pixel
+   * and two-finger translation rotates. */
+  viewport?: () => { height: number; fov: number } | null
   /** 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). */
+  /** Map a point in the input element's own pixels (the frame
+   * localX/localY report in) 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
@@ -126,6 +165,10 @@ export type OrbitCamera = {
   /** Whether the auto-orbit is running. Reactive (signal-backed), so HUD
    * text can read it. */
   orbiting(): boolean
+  /** Whether update(dt) still has work: the auto-orbit on with a non-zero
+   * `orbitSpeed`. The frame-loop gate, reactive like orbiting() - the
+   * same predicate the 2d camera and the first-person camera expose. */
+  active(): boolean
   /** Advance the auto-orbit and push any pose change to the driven camera.
    * Call from onFrame with the frame's dt in seconds; returns whether the
    * pose changed. */
@@ -136,9 +179,10 @@ export type OrbitCamera = {
     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
+    /** Position (the element's own pixels) 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; localX?: number; localY?: number }): void
   }
 }
 
@@ -147,38 +191,38 @@ let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo,
 /**
  * Create an orbit camera driving `camera`'s position and target, where
  * `camera` is a Scene or one of its Views (fov, near, and far stay yours via
- * its setCamera). The initial pose applies immediately. In a component tree,
- * reach the scene via `<Scene ref>` or useScene() (a view via `<View ref>`)
- * and hand the handlers to whichever element owns input.
+ * its setCamera). The initial pose applies immediately. In a component
+ * tree, prefer the `<OrbitCamera>` component: it wires all of this -
+ * scene, input, viewport, frame loop - through the Scene context.
  */
 export function createOrbitCamera(camera: OrbitTarget, options: OrbitCameraOptions = {}): OrbitCamera {
   let target: Vec3 = options.target ? [options.target[0], options.target[1], options.target[2]] : [0, 0, 0]
   let azimuth = options.azimuth ?? 0
   let elevation = options.elevation ?? 0
   let distance = options.distance ?? 5
-  let minDistance = options.minDistance ?? 0.01
-  let maxDistance = options.maxDistance ?? Infinity
-  let minElevation = options.minElevation ?? -1.55
-  let maxElevation = options.maxElevation ?? 1.55
-  let orbitSpeed = options.orbitSpeed ?? 0
-  let dragAzimuth = DRAG_AZIMUTH * (options.rotateSpeed ?? 1)
-  let dragElevation = DRAG_ELEVATION * (options.rotateSpeed ?? 1)
-  let wheelZoom = WHEEL_ZOOM * (options.zoomSpeed ?? 1)
+  // Everything below the pose is read from `options` where it applies.
+  let minDistance = () => options.minDistance ?? MIN_DISTANCE
+  let maxDistance = () => options.maxDistance ?? Infinity
+  let minElevation = () => options.minElevation ?? -ELEVATION_LIMIT
+  let maxElevation = () => options.maxElevation ?? ELEVATION_LIMIT
+  let orbitSpeed = () => options.orbitSpeed ?? 0
+  let rotateSpeed = () => options.rotateSpeed ?? 1
+  let zoomSpeed = () => options.zoomSpeed ?? 1
 
-  let [orbiting, setOrbiting] = createSignal(orbitSpeed > 0)
+  // The auto-orbit switch: starts on when the initial rate is positive.
+  let [orbiting, setOrbiting] = createSignal(orbitSpeed() > 0)
   let interacting = false
   let dirty = false
 
   let clampPose = () => {
-    elevation = clampNum(elevation, minElevation, maxElevation)
-    distance = clampNum(distance, minDistance, maxDistance)
+    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 pan = (dx: number, dy: number, vp: { height: number; fov: number }) => {
     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)
@@ -214,7 +258,7 @@ export function createOrbitCamera(camera: OrbitTarget, options: OrbitCameraOptio
     // 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))
+    distance = clampNum(distance * ratio, Math.min(minDistance(), prev), Math.max(maxDistance(), prev))
     if (!anchor) return
     let s = distance / prev
     target = [
@@ -269,11 +313,14 @@ export function createOrbitCamera(camera: OrbitTarget, options: OrbitCameraOptio
       }
     },
     onTransformMove: (t) => {
-      if (t.pointers >= 2 && options.viewport) {
-        pan(t.dx, t.dy)
+      let vp = options.viewport?.() ?? null
+      if (t.pointers >= 2 && vp !== null) {
+        pan(t.dx, t.dy, vp)
       } else {
-        azimuth -= t.dx * dragAzimuth
-        elevation = clampNum(elevation + t.dy * dragElevation, minElevation, maxElevation)
+        // Viewport-relative when the height is known, per-pixel otherwise.
+        let rel = vp !== null ? (DRAG_TURNS * 2 * Math.PI) / vp.height : null
+        azimuth -= t.dx * (rel ?? DRAG_AZIMUTH) * rotateSpeed()
+        elevation = clampNum(elevation + t.dy * (rel ?? DRAG_ELEVATION) * rotateSpeed(), minElevation(), maxElevation())
       }
       if (t.scale !== 1) {
         // Fingers spreading (scale > 1) zooms in: the distance shrinks by the
@@ -283,7 +330,7 @@ export function createOrbitCamera(camera: OrbitTarget, options: OrbitCameraOptio
           pinchSeen = true
           pinchAnchor = anchorAt(t.x, t.y)
         }
-        zoomAbout(1 / Math.pow(t.scale, options.zoomSpeed ?? 1), pinchAnchor)
+        zoomAbout(1 / Math.pow(t.scale, zoomSpeed()), pinchAnchor)
       }
       dirty = true
     },
@@ -298,6 +345,7 @@ export function createOrbitCamera(camera: OrbitTarget, options: OrbitCameraOptio
     eye,
     pose: () => ({ azimuth, elevation, distance }),
     orbiting,
+    active: () => orbiting() && orbitSpeed() !== 0,
     set(pose) {
       if (pose.azimuth !== undefined) azimuth = pose.azimuth
       if (pose.elevation !== undefined) elevation = pose.elevation
@@ -308,8 +356,9 @@ export function createOrbitCamera(camera: OrbitTarget, options: OrbitCameraOptio
       dirty = true
     },
     update(dt) {
-      if (orbitSpeed !== 0 && !interacting && orbiting()) {
-        azimuth += dt * orbitSpeed
+      let rate = orbitSpeed()
+      if (rate !== 0 && !interacting && orbiting()) {
+        azimuth += dt * rate
         dirty = true
       }
       if (!dirty) return false
@@ -320,7 +369,7 @@ export function createOrbitCamera(camera: OrbitTarget, options: OrbitCameraOptio
     handlers: {
       ...transform.handlers,
       onWheel(e) {
-        zoomAbout(Math.exp(e.deltaY * wheelZoom), anchorAt(e.clientX, e.clientY))
+        zoomAbout(Math.exp(e.deltaY * WHEEL_ZOOM * zoomSpeed()), anchorAt(e.localX, e.localY))
         dirty = true
       },
     },

package/src/scene-pointer.ts

@@ -0,0 +1,166 @@
+// Pointer dispatch behind scene.handlers: element pointer events in,
+// instance/mesh/group handler calls out - nearest hit wins, down/move/up
+// bubble from the struck instance (or the mesh) up through the ancestors,
+// pointer-down captures until up, enter/leave pair on hover changes. One
+// system per scene; everything it needs of the scene is `pick` and the
+// target size (makePointerInput's deps), the capture/hover bookkeeping is
+// its own.
+
+import type { PointerEvent as ElementPointerEvent } from "@solidrt/core"
+import type { SceneNode, ScenePointerEvent } from "./node.ts"
+import type { InstanceNode, Mesh } from "./mesh.ts"
+import type { Hit, SceneHandlers } from "./scene.ts"
+
+type BubbleName = "onPointerDown" | "onPointerMove" | "onPointerUp"
+type InternalEvent = ScenePointerEvent & { _stopped: boolean }
+// What a press captures and a hover tracks: the struck mesh, and the
+// instance when the mesh is instanced.
+type Target = { mesh: Mesh; instance: InstanceNode | null }
+
+export type PointerInputDeps = {
+  /** The scene's pick: camera ray through a scene pixel, hits nearest
+   * first. */
+  pick(x: number, y: number): Hit[]
+  /** The scene target's current size (handlersFor's layout scaling). */
+  targetSize(): { width: number; height: number }
+}
+
+export type PointerInput = {
+  /** scene.handlers: for a leaf laid out at the target size. */
+  handlers: SceneHandlers
+  /** scene.handlersFor: for a leaf whose layout size differs (the
+   * supersampling pattern); `layout` is read per event. */
+  handlersFor(layout: () => { width: number; height: number }): SceneHandlers
+}
+
+export function makePointerInput(deps: PointerInputDeps): PointerInput {
+  let capture = new Map<number, Target>()
+  let hover = new Map<number, Target>()
+
+  let targetOf = (hit: Hit): Target => ({ mesh: hit.mesh, instance: hit.instance ?? null })
+  let sameTarget = (hit: Hit, target: Target): boolean => hit.mesh === target.mesh && (hit.instance ?? null) === target.instance
+  // The node the walk starts at, and the one enter/leave fire on.
+  let nodeOf = (target: Target): SceneNode => target.instance ?? target.mesh
+
+  let makeEvent = (e: ElementPointerEvent, target: Target, x: number, y: number, hit: Hit | null): InternalEvent => {
+    let event: InternalEvent = {
+      mesh: target.mesh,
+      instance: target.instance,
+      currentTarget: nodeOf(target),
+      point: hit !== null ? hit.point : null,
+      distance: hit !== null ? hit.distance : null,
+      x,
+      y,
+      pointerId: e.pointerId,
+      pointerType: e.pointerType,
+      button: e.button,
+      shiftKey: e.shiftKey,
+      ctrlKey: e.ctrlKey,
+      altKey: e.altKey,
+      metaKey: e.metaKey,
+      _stopped: false,
+      stopPropagation() {
+        event._stopped = true
+      },
+    }
+    return event
+  }
+
+  // The struck instance first (its chain passes through the mesh), then
+  // the mesh, then its ancestors.
+  let bubble = (name: BubbleName, event: InternalEvent): void => {
+    for (let n: SceneNode | null = event.instance ?? event.mesh; n !== null && !event._stopped; n = n.parent) {
+      let handler = n[name]
+      if (handler) {
+        event.currentTarget = n
+        handler(event)
+      }
+    }
+  }
+
+  // The captured target's own hit, if the ray still strikes it.
+  let hitOn = (target: Target, x: number, y: number): Hit | null => {
+    for (let h of deps.pick(x, y)) if (sameTarget(h, target)) return h
+    return null
+  }
+
+  // localX/localY arrive in the leaf's LAYOUT frame (the hit test undoes
+  // every transform above it, design-size fits included), so a leaf laid out at
+  // the target size - the built-in <Scene> leaf, a d-texture at natural
+  // size - is already in scene pixels. Only a leaf deliberately laid out at
+  // a DIFFERENT size (the supersampling pattern) needs the ratio, and only
+  // the app knows that layout: handlersFor takes it.
+  let makeHandlers = (layout: (() => { width: number; height: number }) | null): SceneHandlers => {
+    let eventX = 0
+    let eventY = 0
+    let toScene = (e: ElementPointerEvent): void => {
+      if (layout === null) {
+        eventX = e.localX
+        eventY = e.localY
+        return
+      }
+      let l = layout()
+      let size = deps.targetSize()
+      eventX = e.localX * (l.width > 0 ? size.width / l.width : 1)
+      eventY = e.localY * (l.height > 0 ? size.height / l.height : 1)
+    }
+    return {
+      onPointerDown(e) {
+        toScene(e)
+        let hit = deps.pick(eventX, eventY)[0]
+        if (hit === undefined) return
+        let target = targetOf(hit)
+        capture.set(e.pointerId, target)
+        bubble("onPointerDown", makeEvent(e, target, eventX, eventY, hit))
+      },
+      onPointerMove(e) {
+        toScene(e)
+        let captured = capture.get(e.pointerId)
+        if (captured !== undefined) {
+          bubble("onPointerMove", makeEvent(e, captured, eventX, eventY, hitOn(captured, eventX, eventY)))
+          return
+        }
+        let hit = deps.pick(eventX, eventY)[0]
+        let prev = hover.get(e.pointerId)
+        let changed = prev === undefined ? hit !== undefined : hit === undefined || !sameTarget(hit, prev)
+        if (changed) {
+          if (prev !== undefined) {
+            hover.delete(e.pointerId)
+            nodeOf(prev).onPointerLeave?.(makeEvent(e, prev, eventX, eventY, null))
+          }
+          if (hit !== undefined) {
+            let target = targetOf(hit)
+            hover.set(e.pointerId, target)
+            nodeOf(target).onPointerEnter?.(makeEvent(e, target, eventX, eventY, hit))
+          }
+        }
+        if (hit !== undefined) {
+          bubble("onPointerMove", makeEvent(e, targetOf(hit), eventX, eventY, hit))
+        }
+      },
+      onPointerUp(e) {
+        toScene(e)
+        let captured = capture.get(e.pointerId)
+        if (captured !== undefined) {
+          capture.delete(e.pointerId)
+          bubble("onPointerUp", makeEvent(e, captured, eventX, eventY, hitOn(captured, eventX, eventY)))
+          return
+        }
+        let hit = deps.pick(eventX, eventY)[0]
+        if (hit !== undefined) {
+          bubble("onPointerUp", makeEvent(e, targetOf(hit), eventX, eventY, hit))
+        }
+      },
+      onPointerLeave(e) {
+        let prev = hover.get(e.pointerId)
+        if (prev !== undefined) {
+          hover.delete(e.pointerId)
+          toScene(e)
+          nodeOf(prev).onPointerLeave?.(makeEvent(e, prev, eventX, eventY, null))
+        }
+      },
+    }
+  }
+
+  return { handlers: makeHandlers(null), handlersFor: makeHandlers }
+}