@solidrt/3d 0.0.55 → 0.0.57

package/src/components/mesh.tsx

@@ -0,0 +1,92 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { syncNode } from "./node-props.ts"
+import type { TransformProps, PointerEventProps } from "./node-props.ts"
+import { add, remove } from "../node.ts"
+import { createMesh, setCastShadow, setCulling, setGeometry, setLayers, setMaterial, setMeshParams, setRenderOrder } from "../mesh.ts"
+import type { Mesh as MeshNode } from "../mesh.ts"
+import type { ShaderParams } from "@solidrt/core/gpu"
+import type { Geometry } from "../geometry.ts"
+import type { Material } from "../material.ts"
+
+export type MeshProps = TransformProps & PointerEventProps & {
+  geometry: Geometry
+  material: Material
+  /** Per-mesh uniforms for a custom material (setMeshParams as a prop).
+   * Keys merge - a key that disappears keeps its old value; there is no
+   * unset. Names must be declared by the material's shaders. For values
+   * changing every frame prefer `ref` + setMeshParams from onFrame, the
+   * same split as setTransform. */
+  params?: ShaderParams
+  /** Explicit draw-order key (setRenderOrder as a prop); default 0. */
+  renderOrder?: number
+  /** Draw into the scene's shadow map (setCastShadow as a prop); default
+   * false. Needs a `castShadow` light to show. */
+  castShadow?: boolean
+  /** Layer membership bitmask (setLayers as a prop; default 1): a target
+   * draws the mesh when its mask intersects this. Not inherited from
+   * ancestor Groups. */
+  layers?: number
+  /** Frustum culling switch (setCulling as a prop; default true). */
+  frustumCulled?: boolean
+  /** World units the culled box grows by (setCulling as a prop; default 0). */
+  cullMargin?: number
+  ref?: (mesh: MeshNode) => void
+}
+
+// The mesh-side props every mesh component shares (Sprite has no
+// geometry and casts no shadow, so those stay with the components that
+// take them); the
+// ref and the cleanup are each component's own (a populated mesh frees
+// its buffers, a plain one is removed).
+export function syncMesh(mesh: MeshNode, props: Omit<MeshProps, "geometry" | "castShadow" | "ref">): void {
+  createEffect(
+    () => props.material,
+    m => setMaterial(mesh, m),
+    { defer: true },
+  )
+  createEffect(
+    () => props.params,
+    p => {
+      if (p !== undefined) setMeshParams(mesh, p)
+    },
+  )
+  createEffect(
+    () => props.renderOrder,
+    o => setRenderOrder(mesh, o ?? 0),
+  )
+  createEffect(
+    () => props.layers,
+    l => setLayers(mesh, l ?? 1),
+  )
+  createEffect(
+    () => [props.frustumCulled, props.cullMargin] as const,
+    ([culled, margin]) => setCulling(mesh, { frustumCulled: culled !== false, cullMargin: margin ?? 0 }),
+  )
+  syncNode(mesh, props)
+}
+
+/** One draw entry: geometry drawn with a material at a transform. */
+export let Mesh: VoidComponent<MeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() => createMesh(props.geometry, props.material))
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.geometry,
+    g => setGeometry(mesh, g),
+    { defer: true },
+  )
+  createEffect(
+    () => props.castShadow,
+    c => setCastShadow(mesh, c === true),
+  )
+  syncMesh(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => remove(mesh))
+  return null
+}
+
+// The props both populated meshes share with Mesh: everything but the
+// geometry/material pair (documented per component) and the ref.
+export type PopulatedMeshProps = Omit<MeshProps, "geometry" | "material" | "ref">

package/src/components/node-props.ts

@@ -0,0 +1,90 @@
+import { createEffect } from "@solidrt/core"
+import { setTransform, setTransition, setVisible } from "../node.ts"
+import type { NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneNode, TransitionEndEvent } from "../node.ts"
+import type { NodeTransition } from "flux:spatial"
+import type { Quat, Vec3 } from "../math.ts"
+
+export type TransformProps = {
+  position?: Vec3
+  /** Euler radians in XYZ order (x first), Three's `Euler` default. */
+  rotation?: Vec3
+  /** The rotation as a quaternion - what the node stores. Pass this or
+   * `rotation`, not both. */
+  quaternion?: Quat
+  scale?: Vec3 | number
+  visible?: boolean
+  /** How transform-prop changes animate (see setTransition); the mount
+   * transform always snaps. */
+  transition?: NodeTransition | string | null
+  /** A declared transition settled on one component. */
+  onTransitionEnd?: (event: TransitionEndEvent) => void
+}
+
+/**
+ * Node pointer events, the element vocabulary one tree deeper: the nearest
+ * hit (the struck instance, else the mesh) receives the event,
+ * down/move/up/wheel/tap bubble to ancestor Groups and end at the
+ * `<Scene>`'s own handlers (stopPropagation stops the walk; a stopped
+ * down claims the whole press, so a mesh that drags itself keeps an
+ * `<OrbitCamera>` still), enter/leave pair on the struck node alone.
+ * Events flow while the element showing the scene carries scene.handlers -
+ * the built-in <Scene> leaf does (opt out with events={false}); an `output`
+ * leaf spreads them itself.
+ */
+export type PointerEventProps = {
+  onPointerDown?: (event: NodePointerEvent) => void
+  onPointerMove?: (event: NodePointerEvent) => void
+  onPointerUp?: (event: NodePointerEvent) => void
+  /** Meshes and instances only: a Group never receives enter/leave. */
+  onPointerEnter?: (event: NodePointerEvent) => void
+  onPointerLeave?: (event: NodePointerEvent) => void
+  /** The wheel over the node: `deltaX`/`deltaY`. */
+  onWheel?: (event: NodeWheelEvent) => void
+  /** A press released on the node within the slop, alone for its whole
+   * press: DOM's click, with `tapCount` for repeats. */
+  onTap?: (event: NodeTapEvent) => void
+}
+
+export function syncNode(node: SceneNode, props: TransformProps & PointerEventProps): void {
+  // One effect for the transform and the handlers: re-assigning eight
+  // handler fields on a transform write is free, an effect of its own is
+  // not (a node component's mount cost is mostly its effects and its
+  // context provider, see probes/3d-instance-mount-bench.tsx).
+  createEffect(
+    () =>
+      [
+        props.position,
+        props.rotation,
+        props.quaternion,
+        props.scale,
+        props.visible,
+        props.onPointerDown,
+        props.onPointerMove,
+        props.onPointerUp,
+        props.onPointerEnter,
+        props.onPointerLeave,
+        props.onWheel,
+        props.onTap,
+        props.onTransitionEnd,
+      ] as const,
+    ([position, rotation, quaternion, scale, visible, down, move, up, enter, leave, wheel, tap, end]) => {
+      setTransform(node, { position, rotation, quaternion, scale })
+      setVisible(node, visible !== false)
+      node.onPointerDown = down
+      node.onPointerMove = move
+      node.onPointerUp = up
+      node.onPointerEnter = enter
+      node.onPointerLeave = leave
+      node.onWheel = wheel
+      node.onTap = tap
+      node.onTransitionEnd = end
+    },
+  )
+  // After the transform effect, so the mount transform snaps before writes
+  // animate. Its own effect: merged above, every transform write would
+  // re-send the config to the core.
+  createEffect(
+    () => props.transition,
+    transition => setTransition(node, transition ?? null),
+  )
+}

package/src/components/orbit-camera.tsx

@@ -0,0 +1,75 @@
+import { createEffect, merge, onFrame, untrack, useContext } from "@solidrt/core"
+import type { InputMap, VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { createOrbitCamera } from "../orbit.ts"
+import type { OrbitAxes, OrbitCamera as OrbitCameraHandle, OrbitCameraOptions } from "../orbit.ts"
+
+// Cap on the frame loop's per-frame dt in seconds, so the first tick after
+// a suspended stretch (a resumed app, a reload) cannot leap the pose.
+const MAX_ORBIT_DT = 0.1
+
+export type OrbitCameraProps = OrbitCameraOptions & {
+  /** The input map driving the control (InputMap.drive): its `rotate`,
+   * `zoom` and `pan` actions, or the ones `actions` names. Live: a new
+   * map reconnects. Without one the control moves only through `ref`. */
+  input?: InputMap<any>
+  /** Action names per axis when the map's differ (null skips an axis). */
+  actions?: Partial<Record<keyof OrbitAxes, string | null>>
+  /** The control's handle (pose()/set()/eye()/orbiting()/active(), the
+   * verbs, `axes` - also the debug command shape). */
+  ref?: (orbit: OrbitCameraHandle) => void
+}
+
+/**
+ * createOrbitCamera as a Scene (or View3d) child: drives the enclosing
+ * camera - the scene's, or inside a `<View3d>` that view's - through
+ * context, and takes its input from the map in `input`, nothing else
+ * (ARCHITECTURE.md: no device wiring in a component; the app binds a
+ * pointer feed, a pad or anything else to the map). The pose props
+ * (target, azimuth, elevation, distance) are initial values - change the
+ * pose at runtime through `ref`'s set() or the verbs; every other prop is
+ * live, forwarded to the control as a getter and read where it applies,
+ * so a clamp, a rate or an anchor callback follows its prop, and a clamp
+ * change re-clamps the pose at once. The frame loop runs only while
+ * `active()` (auto-orbit on, or an axis rate driving); a camera moved
+ * by drags alone leaves the app demand-driven idle.
+ */
+export let OrbitCamera: VoidComponent<OrbitCameraProps> = props => {
+  let ctx = useContext(SceneContext)
+  // The control keeps this object and reads each option where it applies,
+  // so the props go through as getters (merge), never a spread: a spread
+  // would snapshot every prop once and a change could only remount.
+  let options: OrbitCameraOptions = merge(props, {})
+  let orbit = untrack(() => createOrbitCamera(ctx.viewport, options))
+  createEffect(
+    () => props.input,
+    input => (input ? input.drive(orbit.axes, untrack(() => props.actions)) : undefined),
+  )
+  createEffect(
+    () => orbit.active(),
+    on => {
+      if (!on) return
+      let last: number | null = null
+      return onFrame(tick => {
+        let now = tick / 1000
+        let dt = last === null ? 0 : Math.min(now - last, MAX_ORBIT_DT)
+        last = now
+        orbit.update(dt)
+      })
+    },
+  )
+  // A clamp prop change re-clamps the pose at once (set({}) applies the
+  // clamps and pushes) - the update() call a Three OrbitControls app
+  // makes after setting minDistance, done by the prop. Deferred: the
+  // creation already clamped and pushed the initial pose. Untracked: the
+  // control reads the clamps through the getters while it applies them,
+  // and the apply wants the values of that moment (the compute above is
+  // what tracks them).
+  createEffect(
+    () => [options.minDistance, options.maxDistance, options.minElevation, options.maxElevation],
+    () => untrack(() => orbit.set({})),
+    { defer: true },
+  )
+  untrack(() => props.ref)?.(orbit)
+  return null
+}

package/src/components/perspective-camera.tsx

@@ -0,0 +1,32 @@
+import { createEffect, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import type { Vec3 } from "../math.ts"
+
+export type PerspectiveCameraProps = {
+  /** Vertical field of view in DEGREES (default 60). */
+  fov?: number
+  near?: number
+  far?: number
+  position?: Vec3
+  lookAt?: Vec3
+  up?: Vec3
+}
+
+/**
+ * Drives the enclosing camera from props - the scene's, or inside a
+ * `<View3d>` that view's (both have a default camera, so this component is
+ * optional). The camera is target state, not a tree node: to orbit it,
+ * update `position`/`lookAt`. The Scene and View3d `camera` props drive the
+ * same state (a partial CameraUpdate, ortho included) - use one form, not
+ * both.
+ */
+export let PerspectiveCamera: VoidComponent<PerspectiveCameraProps> = props => {
+  let ctx = useContext(SceneContext)
+  createEffect(
+    () => [props.fov, props.near, props.far, props.position, props.lookAt, props.up] as const,
+    ([fov, near, far, position, lookAt, up]) =>
+      ctx.viewport.setCamera({ fov, near, far, position, target: lookAt, up }),
+  )
+  return null
+}

package/src/components/point-light.tsx

@@ -0,0 +1,52 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { syncNode } from "./node-props.ts"
+import type { TransformProps } from "./node-props.ts"
+import { add, remove } from "../node.ts"
+import { createPointLight, setLight } from "../light.ts"
+import type { PointLight as PointLightNode, SpotShadowOptions } from "../light.ts"
+import type { Vec3 } from "../math.ts"
+
+export type PointLightProps = TransformProps & {
+  color?: Vec3
+  intensity?: number
+  /** Falloff cutoff in world units (0 = no cutoff). */
+  distance?: number
+  /** Falloff exponent; default 2 (inverse square). */
+  decay?: number
+  /** Render shadow maps from this light (six 90-degree face maps, one
+   * per cube face; six shadow slots). Far = `distance`, so give a
+   * casting bulb one. */
+  castShadow?: boolean
+  /** Shadow-map options (mapSize, bias, normalBias, near), merged key
+   * by key. */
+  shadow?: SpotShadowOptions
+  ref?: (light: PointLightNode) => void
+}
+
+/** A point light node (createPointLight): light in every direction from
+ * the node's world position - give it a `position`; rotation does not
+ * matter. Counts against MAX_LIGHTS with the other non-ambient lights. */
+export let PointLight: VoidComponent<PointLightProps> = props => {
+  let ctx = useContext(SceneContext)
+  let light = untrack(() =>
+    createPointLight({
+      color: props.color,
+      intensity: props.intensity,
+      distance: props.distance,
+      decay: props.decay,
+      castShadow: props.castShadow,
+      shadow: props.shadow,
+    }),
+  )
+  add(ctx.parent, light)
+  syncNode(light, props)
+  createEffect(
+    () => [props.color, props.intensity, props.distance, props.decay, props.castShadow, props.shadow] as const,
+    ([color, intensity, distance, decay, castShadow, shadow]) => setLight(light, { color, intensity, distance, decay, castShadow, shadow }),
+  )
+  untrack(() => props.ref)?.(light)
+  onCleanup(() => remove(light))
+  return null
+}

package/src/components/record-mesh.tsx

@@ -0,0 +1,68 @@
+import { createEffect, onCleanup, untrack, useContext } from "@solidrt/core"
+import type { VoidComponent } from "@solidrt/core"
+import { SceneContext } from "./context.tsx"
+import { syncMesh } from "./mesh.tsx"
+import type { PopulatedMeshProps } from "./mesh.tsx"
+import { add } from "../node.ts"
+import { createRecordMesh, disposeInstances, setCastShadow, setGeometry, setRecordCount, setRecords } from "../mesh.ts"
+import type { RecordMesh as RecordMeshNode } from "../mesh.ts"
+import type { Geometry } from "../geometry.ts"
+import type { Material } from "../material.ts"
+
+export type RecordMeshProps = PopulatedMeshProps & {
+  geometry: Geometry
+  /** Must declare instanceAttributes (shaderMaterialClass), slot 0 only. */
+  material: Material
+  /** Interleaved per-instance records (stride = the material's instance
+   * attributes summed). Reactive; a later array larger than the buffer
+   * grows it (capacity doubles into a replacement buffer). */
+  records: Float32Array
+  /** How many records draw; default all of the latest `records`. */
+  count?: number
+  /** LOCAL bounds covering every instance ([minX..maxZ]), fixed at
+   * creation. Without them the mesh has no picking leaf, so pointer events
+   * never target it. */
+  bounds?: ArrayLike<number>
+  /** Draw into the scene's shadow map (setCastShadow as a prop); default
+   * false. Needs a `castShadow` light AND a material class declaring
+   * `shadowVertex` (the depth pass with the instance placement) - the
+   * shadow views skip a populated mesh without one. */
+  castShadow?: boolean
+  ref?: (mesh: RecordMeshNode) => void
+}
+
+/** One draw entry covering N records: geometry repeated per record of
+ * `records` (createRecordMesh as a component, the JS-written population).
+ * The record buffer is component-owned and freed on unmount. */
+export let RecordMesh: VoidComponent<RecordMeshProps> = props => {
+  let ctx = useContext(SceneContext)
+  let mesh = untrack(() =>
+    createRecordMesh(props.geometry, props.material, props.records, props.count, { bounds: props.bounds }),
+  )
+  add(ctx.parent, mesh)
+  createEffect(
+    () => props.records,
+    r => setRecords(mesh, r, untrack(() => props.count)),
+    { defer: true },
+  )
+  createEffect(
+    () => props.count,
+    c => {
+      if (c !== undefined) setRecordCount(mesh, c)
+    },
+    { defer: true },
+  )
+  createEffect(
+    () => props.geometry,
+    g => setGeometry(mesh, g),
+    { defer: true },
+  )
+  createEffect(
+    () => props.castShadow,
+    c => setCastShadow(mesh, c === true),
+  )
+  syncMesh(mesh, props)
+  untrack(() => props.ref)?.(mesh)
+  onCleanup(() => disposeInstances(mesh))
+  return null
+}