@solidrt/3d 0.0.46

package/src/material.ts

@@ -0,0 +1,209 @@
+// Materials pair GLSL with pipeline state, deduped hard: one program and
+// one render pipeline per material CLASS (unlit color, unlit textured),
+// created lazily at first use and kept for the app's lifetime. A material
+// INSTANCE is just the per-entry uniform values (and sampler bindings) it
+// contributes when a mesh becomes a draw entry - so a thousand meshes with
+// a thousand colors still share one pipeline.
+//
+// Colors are straight [r, g, b, a?] 0..1 at the API and premultiplied here
+// once, at the boundary (the engine's pixel contract). An alpha below 1
+// does NOT blend yet: v1 pipelines draw opaque (blend "none"), so a
+// translucent color overwrites what is behind it. Transparency arrives
+// with the blend-factor vocabulary and back-to-front sorting (see
+// okf/research/scene-graph-3d.md, staging step 4).
+//
+// Custom looks need no material system: the raw layer (compileShader /
+// createRenderPipeline in @solidrt/core/gpu) is first-class, and a scene
+// draws into an ordinary draw target - a custom-shaded mesh is a future
+// material class here, or the app's own addDraw beside the scene's.
+
+import {
+  compileShader,
+  createRenderPipeline,
+  destroyProgram,
+  destroyRenderPipeline,
+  destroyShader,
+  glsl,
+  linkProgram,
+} from "@solidrt/core/gpu"
+import type {
+  BlendMode,
+  CullMode,
+  ProgramId,
+  RenderPipelineId,
+  ShaderParams,
+  ShaderStageId,
+  TextureId,
+  Topology,
+} from "@solidrt/core/gpu"
+import { VERTEX_LAYOUT } from "./geometry.ts"
+
+export type Material = {
+  /** The pipeline this material draws with (lazily created). */
+  pipeline(): RenderPipelineId
+  /** Per-entry uniform values this material contributes at addDraw. */
+  params: ShaderParams
+  /** Per-entry sampler bindings, when the material samples textures. */
+  textures?: Record<string, TextureId>
+  /** Present on materials that own their pipeline (shaderMaterial). */
+  dispose?(): void
+}
+
+// One vertex stage serves every unlit class: model then view-projection,
+// plus the UV varying. uModel is per-entry (the scene writes it when the
+// mesh moves), uViewProj is target-shared (one write per camera move) - the
+// split is what keeps camera motion O(1) instead of O(meshes), and the
+// extra per-vertex mat4 multiply is free on the GPU. aNormal from the
+// shared layout is deliberately not declared - inactive attributes are
+// skipped and only the stride accounts for them.
+const VERTEX_SRC = glsl`
+  in vec3 aPos;
+  in vec2 aUV;
+  out vec2 vUv;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+
+  void main() {
+    gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
+    vUv = aUV;
+  }
+`
+
+const FRAGMENT_COLOR_SRC = glsl`
+  uniform vec4 uColor;
+  void main() {
+    fragColor = uColor;
+  }
+`
+
+const FRAGMENT_MAP_SRC = glsl`
+  in vec2 vUv;
+  uniform sampler2D uMap;
+  uniform vec4 uColor;
+  void main() {
+    fragColor = texture(uMap, vUv) * uColor;
+  }
+`
+
+let sharedVertex: ShaderStageId | undefined
+let pipelines: { color?: RenderPipelineId; map?: RenderPipelineId } = {}
+
+function pipelineFor(kind: "color" | "map"): RenderPipelineId {
+  let existing = pipelines[kind]
+  if (existing !== undefined) return existing
+  if (sharedVertex === undefined) sharedVertex = compileShader("vertex", VERTEX_SRC, { header: true })
+  let fragment = compileShader("fragment", kind === "color" ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
+    header: true,
+  })
+  let program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + kind })
+  let pipeline = createRenderPipeline(program, {
+    attributes: VERTEX_LAYOUT,
+    depth: true,
+    cull: "back",
+    label: "scene-unlit-" + kind,
+  })
+  pipelines[kind] = pipeline
+  return pipeline
+}
+
+export type UnlitOptions = {
+  /** Straight [r, g, b] or [r, g, b, a], 0..1. Default white. */
+  color?: [number, number, number] | [number, number, number, number]
+  /** A texture id to sample (tinted by `color` when both are given). */
+  map?: TextureId
+}
+
+/**
+ * An unlit material: flat color, textured when `map` is given. Unlit is
+ * the complete v1 set - lit materials arrive with uniform arrays (the
+ * light list); see the scene-graph research note.
+ */
+export function unlit(opts: UnlitOptions = {}): Material {
+  let color = opts.color ?? [1, 1, 1]
+  let a = color.length === 4 ? color[3] : 1
+  let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  if (opts.map !== undefined) {
+    return { pipeline: () => pipelineFor("map"), params: { uColor }, textures: { uMap: opts.map } }
+  }
+  return { pipeline: () => pipelineFor("color"), params: { uColor } }
+}
+
+// Mirrors the engine's own preamble rule: a source carrying its own
+// #version line is compiled exactly as written.
+function needsHeader(source: string): boolean {
+  return !source.trimStart().startsWith("#version")
+}
+
+export type ShaderMaterialOptions = {
+  /**
+   * Vertex stage GLSL. MUST declare and use `uniform mat4 uModel` (the
+   * mesh's world matrix, written per entry whenever the mesh moves) and
+   * `uniform mat4 uViewProj` (the camera's view-projection, shared by the
+   * whole scene target and written once per camera move) - transform with
+   * `uViewProj * uModel * vec4(aPos, 1.0)`. Declare any of the shared
+   * layout's `in` attributes (aPos vec3, aNormal vec3, aUV vec2);
+   * undeclared ones are skipped.
+   */
+  vertex: string
+  fragment: string
+  /** Uniform seeds beyond uModel/uViewProj; update per mesh later with
+   * setMeshParams. */
+  params?: ShaderParams
+  textures?: Record<string, TextureId>
+  /** Pipeline state; defaults match unlit: depth: true, cull: "back". */
+  depth?: boolean
+  depthWrite?: boolean
+  blend?: BlendMode
+  cull?: CullMode
+  topology?: Topology
+  label?: string
+}
+
+/**
+ * A material from your own GLSL: the custom-look escape hatch, first-class
+ * next to unlit. Sources without a `#version` line get the standard
+ * pipeline preamble (`fragColor`, `iResolution`).
+ *
+ * The INSTANCE is the pipeline handle: two calls with identical sources
+ * compile two pipelines - there is no dedupe by source value (a hidden
+ * cache keyed by content is the anti-pattern the GPU layer avoids
+ * throughout). Create one per look at app scope, share it across meshes,
+ * and `dispose()` it if the app is done with the look for good.
+ */
+export function shaderMaterial(opts: ShaderMaterialOptions): Material {
+  let program: ProgramId | undefined
+  let pipeline: RenderPipelineId | undefined
+  return {
+    pipeline() {
+      if (pipeline === undefined) {
+        let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
+        let fs = compileShader("fragment", opts.fragment, { header: needsHeader(opts.fragment) })
+        program = linkProgram(vs, fs, { label: opts.label })
+        destroyShader(vs)
+        destroyShader(fs)
+        pipeline = createRenderPipeline(program, {
+          attributes: VERTEX_LAYOUT,
+          depth: opts.depth ?? true,
+          depthWrite: opts.depthWrite,
+          blend: opts.blend,
+          cull: opts.cull ?? "back",
+          topology: opts.topology,
+          label: opts.label,
+        })
+      }
+      return pipeline
+    },
+    params: opts.params ?? {},
+    textures: opts.textures,
+    dispose() {
+      if (pipeline !== undefined) {
+        destroyRenderPipeline(pipeline)
+        pipeline = undefined
+      }
+      if (program !== undefined) {
+        destroyProgram(program)
+        program = undefined
+      }
+    },
+  }
+}

package/src/math.ts

@@ -0,0 +1,179 @@
+// 3D math over plain number arrays: column-major mat4 (the layout mat4
+// uniforms expect) in a right-handed, y-up world with the camera looking
+// down -z. perspective() bakes the engine's y-down clip flip into the
+// projection, so scene code never sees the flip and standard CCW-outward
+// meshes cull correctly with cull: "back" (see the pixel contract in
+// @solidrt/core/gpu). Every function writes into a caller-owned `out`
+// matrix and allocates nothing: the hot path - a moved node is one compose,
+// one or two multiplies, one param write - must stay allocation-free on an
+// interpreter. Mat4 is a 16-tuple so constant-index access stays plain
+// `number` under noUncheckedIndexedAccess.
+
+export type Vec3 = [number, number, number]
+// prettier-ignore
+export type Mat4 = [
+  number, number, number, number,
+  number, number, number, number,
+  number, number, number, number,
+  number, number, number, number,
+]
+
+/** A fresh identity matrix. */
+export function mat4(): Mat4 {
+  return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]
+}
+
+export function identity(out: Mat4): Mat4 {
+  out[0] = 1; out[1] = 0; out[2] = 0; out[3] = 0
+  out[4] = 0; out[5] = 1; out[6] = 0; out[7] = 0
+  out[8] = 0; out[9] = 0; out[10] = 1; out[11] = 0
+  out[12] = 0; out[13] = 0; out[14] = 0; out[15] = 1
+  return out
+}
+
+export function copy(out: Mat4, m: Mat4): Mat4 {
+  out[0] = m[0]; out[1] = m[1]; out[2] = m[2]; out[3] = m[3]
+  out[4] = m[4]; out[5] = m[5]; out[6] = m[6]; out[7] = m[7]
+  out[8] = m[8]; out[9] = m[9]; out[10] = m[10]; out[11] = m[11]
+  out[12] = m[12]; out[13] = m[13]; out[14] = m[14]; out[15] = 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]
+  let a10 = a[4], a11 = a[5], a12 = a[6], a13 = a[7]
+  let a20 = a[8], a21 = a[9], a22 = a[10], a23 = a[11]
+  let a30 = a[12], a31 = a[13], a32 = a[14], a33 = a[15]
+  let b0 = b[0], b1 = b[1], b2 = b[2], b3 = b[3]
+  out[0] = b0 * a00 + b1 * a10 + b2 * a20 + b3 * a30
+  out[1] = b0 * a01 + b1 * a11 + b2 * a21 + b3 * a31
+  out[2] = b0 * a02 + b1 * a12 + b2 * a22 + b3 * a32
+  out[3] = b0 * a03 + b1 * a13 + b2 * a23 + b3 * a33
+  b0 = b[4]; b1 = b[5]; b2 = b[6]; b3 = b[7]
+  out[4] = b0 * a00 + b1 * a10 + b2 * a20 + b3 * a30
+  out[5] = b0 * a01 + b1 * a11 + b2 * a21 + b3 * a31
+  out[6] = b0 * a02 + b1 * a12 + b2 * a22 + b3 * a32
+  out[7] = b0 * a03 + b1 * a13 + b2 * a23 + b3 * a33
+  b0 = b[8]; b1 = b[9]; b2 = b[10]; b3 = b[11]
+  out[8] = b0 * a00 + b1 * a10 + b2 * a20 + b3 * a30
+  out[9] = b0 * a01 + b1 * a11 + b2 * a21 + b3 * a31
+  out[10] = b0 * a02 + b1 * a12 + b2 * a22 + b3 * a32
+  out[11] = b0 * a03 + b1 * a13 + b2 * a23 + b3 * a33
+  b0 = b[12]; b1 = b[13]; b2 = b[14]; b3 = b[15]
+  out[12] = b0 * a00 + b1 * a10 + b2 * a20 + b3 * a30
+  out[13] = b0 * a01 + b1 * a11 + b2 * a21 + b3 * a31
+  out[14] = b0 * a02 + b1 * a12 + b2 * a22 + b3 * a32
+  out[15] = b0 * a03 + b1 * a13 + b2 * a23 + b3 * a33
+  return out
+}
+
+/**
+ * Compose translation + rotation + scale into a local matrix. Rotation is
+ * Euler angles in radians applied x, then y, then z (R = Rz * Ry * Rx on
+ * column vectors) - the common "XYZ" order.
+ */
+export function compose(out: Mat4, position: Vec3, rotation: Vec3, scale: Vec3): Mat4 {
+  let cx = Math.cos(rotation[0]), sx = Math.sin(rotation[0])
+  let cy = Math.cos(rotation[1]), sy = Math.sin(rotation[1])
+  let cz = Math.cos(rotation[2]), sz = Math.sin(rotation[2])
+  let r00 = cz * cy
+  let r01 = cz * sy * sx - sz * cx
+  let r02 = cz * sy * cx + sz * sx
+  let r10 = sz * cy
+  let r11 = sz * sy * sx + cz * cx
+  let r12 = sz * sy * cx - cz * sx
+  let r20 = -sy
+  let r21 = cy * sx
+  let r22 = cy * cx
+  out[0] = r00 * scale[0]; out[1] = r10 * scale[0]; out[2] = r20 * scale[0]; out[3] = 0
+  out[4] = r01 * scale[1]; out[5] = r11 * scale[1]; out[6] = r21 * scale[1]; out[7] = 0
+  out[8] = r02 * scale[2]; out[9] = r12 * scale[2]; out[10] = r22 * scale[2]; out[11] = 0
+  out[12] = position[0]; out[13] = position[1]; out[14] = position[2]; 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
+ * the flip this projection applies is exactly what makes displayed-CCW
+ * front faces line up with CCW-outward meshes, so cull: "back" works.
+ * `fovy` is the vertical field of view in RADIANS.
+ */
+export function perspective(out: Mat4, fovy: number, aspect: number, near: number, far: number): Mat4 {
+  let f = 1 / Math.tan(fovy / 2)
+  let nf = 1 / (near - far)
+  out[0] = f / aspect; out[1] = 0; out[2] = 0; out[3] = 0
+  out[4] = 0; out[5] = -f; out[6] = 0; out[7] = 0
+  out[8] = 0; out[9] = 0; out[10] = (far + near) * nf; out[11] = -1
+  out[12] = 0; out[13] = 0; out[14] = 2 * far * near * nf; out[15] = 0
+  return out
+}
+
+// Vec3 helpers for geometry construction. These allocate (unlike the matrix
+// functions above): they serve generation-time code - curve frames, normals -
+// not the per-frame path. Exposed on the /math subpath only, so `add` does
+// not collide with the scene's add() on the package root.
+
+export function add(a: Vec3, b: Vec3): Vec3 {
+  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]]
+}
+
+export function sub(a: Vec3, b: Vec3): Vec3 {
+  return [a[0] - b[0], a[1] - b[1], a[2] - b[2]]
+}
+
+export function cross(a: Vec3, b: Vec3): Vec3 {
+  return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]]
+}
+
+export function dot(a: Vec3, b: Vec3): number {
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+}
+
+export function scale(v: Vec3, s: number): Vec3 {
+  return [v[0] * s, v[1] * s, v[2] * s]
+}
+
+/** Unit vector; a zero-length input comes back unchanged. */
+export function normalize(v: Vec3): Vec3 {
+  let len = Math.hypot(v[0], v[1], v[2]) || 1
+  return [v[0] / len, v[1] / len, v[2] / len]
+}
+
+/**
+ * View matrix (world -> camera) for a camera at `eye` looking at `target`
+ * with the given `up`. Degenerate inputs (eye == target, up parallel to the
+ * view direction) fall back to axis defaults instead of producing NaNs.
+ */
+export function lookAt(out: Mat4, eye: Vec3, target: Vec3, up: Vec3): Mat4 {
+  let zx = eye[0] - target[0]
+  let zy = eye[1] - target[1]
+  let zz = eye[2] - target[2]
+  let len = Math.hypot(zx, zy, zz)
+  if (len === 0) {
+    zx = 0; zy = 0; zz = 1
+  } else {
+    zx /= len; zy /= len; zz /= len
+  }
+  let xx = up[1] * zz - up[2] * zy
+  let xy = up[2] * zx - up[0] * zz
+  let xz = up[0] * zy - up[1] * zx
+  len = Math.hypot(xx, xy, xz)
+  if (len === 0) {
+    xx = 1; xy = 0; xz = 0
+  } else {
+    xx /= len; xy /= len; xz /= len
+  }
+  let yx = zy * xz - zz * xy
+  let yy = zz * xx - zx * xz
+  let yz = zx * xy - zy * xx
+  out[0] = xx; out[1] = yx; out[2] = zx; out[3] = 0
+  out[4] = xy; out[5] = yy; out[6] = zy; out[7] = 0
+  out[8] = xz; out[9] = yz; out[10] = zz; out[11] = 0
+  out[12] = -(xx * eye[0] + xy * eye[1] + xz * eye[2])
+  out[13] = -(yx * eye[0] + yy * eye[1] + yz * eye[2])
+  out[14] = -(zx * eye[0] + zy * eye[1] + zz * eye[2])
+  out[15] = 1
+  return out
+}

package/src/orbit.ts

@@ -0,0 +1,164 @@
+// 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.
+//
+// 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
+// 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.
+
+import { createSignal } from "@solidjs/signals"
+import type { Scene } from "./scene.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.
+const DRAG_AZIMUTH = 0.008
+const DRAG_ELEVATION = 0.006
+const WHEEL_ZOOM = 0.0015
+
+export type OrbitCameraOptions = {
+  /** The point the camera orbits and looks at (default origin). */
+  target?: Vec3
+  /** Initial pose, radians and world units. */
+  azimuth?: number
+  elevation?: number
+  distance?: number
+  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 not dragging; toggle with set({ orbiting }). */
+  orbitSpeed?: number
+  /** Multipliers over the built-in drag/wheel sensitivities. */
+  rotateSpeed?: number
+  zoomSpeed?: number
+}
+
+export type OrbitPose = {
+  azimuth?: number
+  elevation?: number
+  distance?: number
+  target?: Vec3
+  orbiting?: boolean
+}
+
+export type OrbitCamera = {
+  /** Camera position for the current pose (a fresh array per call). */
+  eye(): Vec3
+  /** Pose snapshot - the shape debug commands return and set() takes. */
+  pose(): { azimuth: number; elevation: number; distance: number }
+  /** Merge a pose in (clamps apply); reaches the scene at the next
+   * update(). Also the auto-orbit switch: set({ orbiting: false }). */
+  set(pose: OrbitPose): void
+  /** Whether the auto-orbit is running. Reactive (signal-backed), so HUD
+   * text can read it. */
+  orbiting(): boolean
+  /** Advance the auto-orbit and push any pose change to the scene camera.
+   * Call from onFrame with the frame's dt in seconds; returns whether the
+   * pose changed. */
+  update(dt: number): boolean
+  /** 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
+  }
+}
+
+let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
+
+/**
+ * Create an orbit camera driving `scene`'s camera position and target (fov,
+ * near, and far stay yours via scene.setCamera). The initial pose applies
+ * immediately. In a component tree, reach the scene via `<Scene ref>` or
+ * useScene() and hand the handlers to whichever element owns input.
+ */
+export function createOrbitCamera(scene: Scene, 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)
+
+  let [orbiting, setOrbiting] = createSignal(orbitSpeed > 0)
+  let drag: { x: number; y: number } | null = null
+  let dirty = false
+
+  let clampPose = () => {
+    elevation = clampNum(elevation, minElevation, maxElevation)
+    distance = clampNum(distance, minDistance, maxDistance)
+  }
+  let eye = (): Vec3 => {
+    let ce = Math.cos(elevation)
+    return [
+      target[0] + distance * ce * Math.sin(azimuth),
+      target[1] + distance * Math.sin(elevation),
+      target[2] + distance * ce * Math.cos(azimuth),
+    ]
+  }
+  let apply = () => scene.setCamera({ position: eye(), target })
+
+  clampPose()
+  apply()
+
+  return {
+    eye,
+    pose: () => ({ azimuth, elevation, distance }),
+    orbiting,
+    set(pose) {
+      if (pose.azimuth !== undefined) azimuth = pose.azimuth
+      if (pose.elevation !== undefined) elevation = pose.elevation
+      if (pose.distance !== undefined) distance = pose.distance
+      if (pose.target) target = [pose.target[0], pose.target[1], pose.target[2]]
+      clampPose()
+      if (pose.orbiting !== undefined) setOrbiting(pose.orbiting)
+      dirty = true
+    },
+    update(dt) {
+      if (orbitSpeed !== 0 && drag === null && orbiting()) {
+        azimuth += dt * orbitSpeed
+        dirty = true
+      }
+      if (!dirty) return false
+      dirty = false
+      apply()
+      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
+      },
+      onWheel(e) {
+        distance = clampNum(distance * Math.exp(e.deltaY * wheelZoom), minDistance, maxDistance)
+        dirty = true
+      },
+    },
+  }
+}