@solidrt/3d 0.0.46 → 0.0.47

package/src/scene.ts

@@ -1,9 +1,12 @@
 // The retained scene: plain objects and dirty flags, no signals - the hot
 // path (a moved node) is flat imperative code, and reactivity stays at the
 // component boundary (components.tsx). A scene compiles to one draw
-// target: every mesh is one draw entry whose uModel uniform this module
-// keeps in step with the tree, and the camera is the target's SHARED
-// uViewProj - one setTargetParams per camera move, not one write per mesh.
+// target: every mesh is one draw entry whose uModel (and, for materials
+// declaring it, uNormal) this module keeps in step with the tree, and the
+// camera is the target's SHARED uViewProj + uCamPos - one setTargetParams
+// per camera move, not one write per mesh. uCamPos rides unconditionally:
+// shared params tolerate zero coverage (stored and skipped until a
+// declaring material arrives), so no bookkeeping tracks who reads it.
 // Mutations batch to a microtask, so a burst of writes (a whole subtree
 // moved, many effects in one flush) syncs once.
 //
@@ -17,20 +20,23 @@
 import { addDraw, createDrawTarget, destroyTexture, removeDraw, setDrawParams, setDrawRange, setTargetParams, setTargetSize } from "@solidrt/core/gpu"
 import type { DrawId, FilterMode, ShaderParams, TextureId, WrapMode } from "@solidrt/core/gpu"
 import { getOwner, onCleanup } from "@solidjs/signals"
-import { compose, lookAt, mat4, multiply, perspective } from "./math.ts"
-import type { Mat4, Vec3 } from "./math.ts"
+import { compose, copy, lookAt, mat4, multiply, normalMatrix, perspective, transformPoint } from "./math.ts"
+import type { Mat4, Vec3, Vec4 } from "./math.ts"
 import { geometryBuffers } from "./geometry.ts"
 import type { Geometry } from "./geometry.ts"
 import type { Material } from "./material.ts"
 
 const IDENTITY = mat4()
 const RESOLVED = Promise.resolve()
+// Param values are snapshotted at the FFI boundary (addDraw shares
+// IDENTITY the same way), so one scratch serves every uNormal write.
+let normalScratch = mat4()
 
 // The scene half a node needs to reach: attach/detach entries and schedule
 // a sync. Kept separate from the public Scene type so internals stay off
-// the app-facing surface. uViewProj is written through the shared channel
-// only when the camera changes - attach never re-seeds it, because target
-// state survives entry churn.
+// the app-facing surface. The camera (uViewProj + uCamPos) is written
+// through the shared channel only when it changes - attach never re-seeds
+// it, because target state survives entry churn.
 type SceneHooks = {
   _schedule(): void
   _attach(mesh: Mesh): void
@@ -91,6 +97,18 @@ export type Scene = {
   /** Partial camera update; absent keys keep their current value. */
   setCamera(update: CameraUpdate): void
   setSize(width: number, height: number): void
+  /**
+   * Project a world point to scene pixels: origin top-left, y down - the
+   * output texture's own coordinate space, ready for overlay layout (HUD
+   * markers, labels). `w` is the clip-space w, the point's camera-forward
+   * distance (useful for depth-ordering or distance-scaling markers).
+   * Returns null for a point at or behind the camera plane - such a point
+   * has no place on screen. Reflects a pending setCamera immediately.
+   */
+  project(point: Vec3): { x: number; y: number; w: number } | null
+  /** The camera's view-projection matrix, copied into `out` (or a fresh
+   * mat4). The batch escape hatch; for single points use project(). */
+  viewProj(out?: Mat4): Mat4
   /** Destroy the target (entries die with it). Idempotent. Geometry
    * buffers and material pipelines are shared and survive - they are
    * app-lifetime (see geometry.ts / material.ts). */
@@ -238,7 +256,7 @@ function rebuildEntry(mesh: Mesh): void {
 
 /**
  * Write per-mesh uniforms - the channel for a custom material's app-driven
- * values (a camera position, a time, a per-object tint). Names must be
+ * values (a time, a per-object tint). Names must be
  * declared and used by the mesh's material shaders (unknown names throw at
  * the call site, the engine's validation contract). Values persist on the
  * mesh: they survive geometry/material entry rebuilds and re-apply then.
@@ -276,23 +294,34 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   let target: Vec3 = [0, 0, 0]
   let up: Vec3 = [0, 1, 0]
   let cameraDirty = true
-  let cameraSynced = false
+  let cameraPending = false
   let proj = mat4()
   let view = mat4()
   let viewProj = mat4()
+  let clip: Vec4 = [0, 0, 0, 0]
+
+  // Matrix recompute, split from sync so project()/viewProj() see a fresh
+  // matrix right after setCamera, before the microtask runs. cameraPending
+  // keeps the GPU write owed to the next sync.
+  let ensureCamera = () => {
+    if (!cameraDirty) return
+    cameraDirty = false
+    cameraPending = true
+    perspective(proj, (fov * Math.PI) / 180, width / height, near, far)
+    lookAt(view, eye, target, up)
+    multiply(viewProj, proj, view)
+  }
 
   let sync = () => {
     scheduled = false
     if (disposed) return
-    if (cameraDirty) {
+    ensureCamera()
+    if (cameraPending) {
       // The camera is target state: one shared write, whatever the scene
-      // holds. Entries are untouched - uModel is camera-independent.
-      cameraDirty = false
-      cameraSynced = true
-      perspective(proj, (fov * Math.PI) / 180, width / height, near, far)
-      lookAt(view, eye, target, up)
-      multiply(viewProj, proj, view)
-      setTargetParams(texture, { uViewProj: viewProj })
+      // holds. Entries are untouched - uModel is camera-independent, and
+      // uCamPos is stored even when no current material declares it.
+      cameraPending = false
+      setTargetParams(texture, { uViewProj: viewProj, uCamPos: eye })
     }
     let walk = (node: SceneNode, parentChanged: boolean, parentVisible: boolean) => {
       let changed = parentChanged
@@ -315,7 +344,14 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
             if (shown) mesh._fresh = true
           }
           if (!mesh._hidden && (changed || mesh._fresh)) {
-            setDrawParams(texture, mesh._entry, { uModel: mesh._world })
+            if (mesh.material.normalMatrix) {
+              setDrawParams(texture, mesh._entry, {
+                uModel: mesh._world,
+                uNormal: normalMatrix(normalScratch, mesh._world),
+              })
+            } else {
+              setDrawParams(texture, mesh._entry, { uModel: mesh._world })
+            }
             mesh._fresh = false
           } else if (changed) {
             // Moved while hidden: write the fresh matrix on unhide.
@@ -336,28 +372,33 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     },
     _attach(mesh) {
       if (disposed) return
+      // Layout is stride: a mismatched pair would not miss a channel, it
+      // would read garbage - so it is an error here, like the rest of the
+      // strict entry path.
+      let geoLayout = mesh.geometry.layout ?? "standard"
+      let matLayout = mesh.material.layout ?? "standard"
+      if (geoLayout !== matLayout) {
+        throw new Error(
+          "Mesh geometry layout '" + geoLayout + "' does not match its material's '" + matLayout +
+            "' - a material reading aColor needs withColors() geometry, and colored geometry needs such a material",
+        )
+      }
       let bufs = geometryBuffers(mesh.geometry)
-      mesh._entry = addDraw(
-        texture,
-        mesh.material.pipeline(),
-        { uModel: IDENTITY, ...mesh.material.params, ...mesh._params },
-        {
-          buffer: bufs.buffer,
-          indexBuffer: bufs.index,
-          indexFormat: "uint16",
-          textures: mesh.material.textures,
-        },
-      )
+      // The uNormal seed keys off the material flag because entry params
+      // validate strictly - and a material declaring uNormal without using
+      // it therefore throws right here, at add().
+      let seed: ShaderParams = mesh.material.normalMatrix
+        ? { uModel: IDENTITY, uNormal: IDENTITY, ...mesh.material.params, ...mesh._params }
+        : { uModel: IDENTITY, ...mesh.material.params, ...mesh._params }
+      mesh._entry = addDraw(texture, mesh.material.pipeline(), seed, {
+        buffer: bufs.buffer,
+        indexBuffer: bufs.index,
+        indexFormat: bufs.indexFormat,
+        textures: mesh.material.textures,
+      })
       mesh._hidden = false
       mesh._fresh = true
       this._schedule()
-      // Re-issue the camera (same value, one write): a scene whose only
-      // materials lack uViewProj then throws HERE, at add(), with the
-      // engine's coverage message, instead of inside the next camera sync's
-      // microtask. Before the first sync there is no value to re-issue; the
-      // sync this attach just scheduled writes (and checks) it. Scheduled
-      // first so a throw still leaves the walk queued.
-      if (cameraSynced) setTargetParams(texture, { uViewProj: viewProj })
     },
     _detach(mesh) {
       if (mesh._entry !== null && !disposed) removeDraw(texture, mesh._entry)
@@ -392,6 +433,19 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       cameraDirty = true
       hooks._schedule()
     },
+    project(point) {
+      ensureCamera()
+      transformPoint(clip, viewProj, point)
+      let w = clip[3]
+      if (w < 1e-6) return null
+      // perspective() bakes the y-down clip flip, so NDC maps straight to
+      // top-left-origin pixels with no negation here.
+      return { x: ((clip[0] / w) * 0.5 + 0.5) * width, y: ((clip[1] / w) * 0.5 + 0.5) * height, w }
+    },
+    viewProj(out) {
+      ensureCamera()
+      return copy(out ?? mat4(), viewProj)
+    },
     dispose() {
       if (disposed) return
       disposed = true