@solidrt/3d 0.0.56 → 0.0.58

package/src/material.ts

@@ -41,7 +41,7 @@ import type {
   Topology,
   VertexAttribute,
 } from "@solidrt/core/gpu"
-import { layoutAttributes, layoutKey, layoutSlot } from "./geometry.ts"
+import { FORMAT_FLOATS, layoutAttributes, layoutKey, layoutSlot } from "./geometry.ts"
 import type { VertexLayout } from "./geometry.ts"
 import { linearColor } from "./color.ts"
 import {
@@ -63,9 +63,10 @@ import {
 } from "./glsl.ts"
 
 export type Material = {
-  /** The pipeline this material draws with for geometry of `layout`
-   * (lazily created, one per layout met). */
-  pipeline(layout: VertexLayout | undefined): RenderPipelineId
+  /** The pipeline this material draws with for geometry of `layout` and
+   * `topology` (lazily created, one per pair met): the geometry says what
+   * its indices are, the material draws them that way. */
+  pipeline(layout: VertexLayout | undefined, topology: Topology): RenderPipelineId
   /** Per-entry uniform values this material contributes at addDraw. */
   params: ShaderParams
   /** Per-entry sampler bindings, when the material samples textures. */
@@ -1072,7 +1073,6 @@ export type ShaderMaterialClassOptions = {
   depthWrite?: boolean
   blend?: BlendMode
   cull?: CullMode
-  topology?: Topology
   label?: string
 }
 
@@ -1142,6 +1142,24 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
   let depth = opts.depth ?? true
   let cull = opts.cull ?? "back"
+  // Formats are the vertex vocabulary (f32/vec2/vec3/vec4), not WebGPU's
+  // spelling, and an unknown one has no float count: it would leave here
+  // intact, make a NaN record stride at the mesh, and fail as an arithmetic
+  // complaint from createRecordMesh naming neither the attribute nor the
+  // format. Checked where the name is written instead.
+  for (let attr of opts.instanceAttributes ?? []) {
+    if (!(attr.format in FORMAT_FLOATS)) {
+      throw new Error(
+        "shaderMaterial unknown instance attribute format '" +
+          String(attr.format) +
+          "' for " +
+          attr.name +
+          " (expected " +
+          Object.keys(FORMAT_FLOATS).join(", ") +
+          ")",
+      )
+    }
+  }
   // An empty list declares nothing - same as absent (the engine requires an
   // instance buffer exactly when attributes are declared).
   let instanceAttributes = opts.instanceAttributes?.length ? opts.instanceAttributes.map(a => ({ ...a })) : undefined
@@ -1192,8 +1210,8 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   // record buffer, declared on the pipeline beside the layout).
   let attributes = (): VertexAttribute[] =>
     programAttributes(programFor()).filter(a => !instanceAttributes?.some(i => i.name === a.name))
-  let pipelineFor = (layout: VertexLayout | undefined): RenderPipelineId => {
-    let key = layoutKey(layout)
+  let pipelineFor = (layout: VertexLayout | undefined, topology: Topology): RenderPipelineId => {
+    let key = layoutKey(layout) + "|" + topology
     let pipeline = pipelines.get(key)
     if (pipeline === undefined) {
       pipeline = createRenderPipeline(programFor(), {
@@ -1205,7 +1223,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
         depthWrite: opts.depthWrite ?? (transparent && depth ? false : undefined),
         blend: opts.blend ?? (transparent ? "alpha" : undefined),
         cull,
-        topology: opts.topology,
+        topology,
         label: opts.label,
       })
       pipelines.set(key, pipeline)

package/src/mesh.ts

@@ -4,8 +4,8 @@
 // scene side is reached through the node's SceneHooks (node.ts).
 
 import { createBuffer, destroyBuffer, writeBuffer } from "@solidrt/core/gpu"
-import type { BufferId, DrawId, InstanceAttribute, ShaderParams, TextureBindings, VertexAttribute } from "@solidrt/core/gpu"
-import { geometryBounds, plane } from "./geometry.ts"
+import type { BufferId, DrawId, InstanceAttribute, ShaderParams, TextureBindings } from "@solidrt/core/gpu"
+import { FORMAT_FLOATS, geometryBounds, plane } from "./geometry.ts"
 import type { Geometry } from "./geometry.ts"
 import type { GeometryBuffers } from "./geometry-gpu.ts"
 import type { Material } from "./material.ts"
@@ -24,7 +24,8 @@ export type Mesh = SceneNode & {
   renderOrder: number
   /** Draw into the scene's shadow map (default false, Three's default).
    * Set with setCastShadow. A casting instanced mesh is skipped (the
-   * depth pass cannot know its record layout). */
+   * depth pass cannot know its record layout), and so is any geometry
+   * that is not a triangle list: lines and points cast nothing. */
   castShadow: boolean
   /** Layer membership bitmask (default 1, Three's `object.layers`): a
    * target draws the mesh when its mask intersects this. Not inherited
@@ -225,13 +226,11 @@ export function localBounds(mesh: Mesh): Float32Array | null {
   return mesh._sprite ? SPRITE_BOUNDS : geometryBounds(mesh.geometry)
 }
 
-const ATTRIBUTE_FLOATS: Record<VertexAttribute["format"], number> = { f32: 1, vec2: 2, vec3: 3, vec4: 4 }
-
 /** Floats per record of one instance slot of an attribute list (slot 0
  * by default; the list's `slot` keys pick the others). */
 export function instanceStride(attributes: InstanceAttribute[], slot = 0): number {
   let stride = 0
-  for (let a of attributes) if ((a.slot ?? 0) === slot) stride += ATTRIBUTE_FLOATS[a.format]
+  for (let a of attributes) if ((a.slot ?? 0) === slot) stride += FORMAT_FLOATS[a.format]
   return stride
 }
 

package/src/model.ts

@@ -24,6 +24,8 @@ import { add, createGroup, remove, setTransform } from "./node.ts"
 import type { SceneNode } from "./node.ts"
 import { createMesh } from "./mesh.ts"
 import type { Mesh } from "./mesh.ts"
+import { refreshJointBounds, unbindSkeleton } from "./skeleton.ts"
+import type { WornPiece } from "./skeleton.ts"
 
 /** Anisotropic filtering level for a model's textures: the engines' usual
  * default (Godot ships 2x, Unity's quality presets 2-8x) - enough to keep a
@@ -80,8 +82,30 @@ export type Model = SceneNode & {
   /** Local rest-pose [minX, minY, minZ, maxX, maxY, maxZ] over every part
    * (conservative for parts under rotated nodes). */
   bounds: Float32Array
-  /** Detach the model and free its geometry buffers and textures. */
+  /** Detach the model and free its geometry buffers and textures. A
+   * worn piece (bindSkeleton) comes off its body; a body takes the
+   * pieces it wears with it. */
   dispose(): void
+  /** @internal The skins the parts draw, in file order: the palette
+   * texture (shared by identical skins), the joint nodes in row order,
+   * their inverse binds and joint-space influence boxes. */
+  _skins: ModelSkinNodes[]
+  /** @internal The pieces bound onto this model's skeleton. */
+  _worn: WornPiece[]
+  /** @internal The body this model is bound onto, or null. */
+  _body: Model | null
+  /** @internal Subtrees bindSkeleton moved under the body's joints (no
+   * longer under this model); detached again by dispose. */
+  _grafts: SceneNode[]
+}
+
+/** @internal One skin of a built model: ModelSkin with its joints
+ * resolved to the model's nodes and its palette texture. */
+export type ModelSkinNodes = {
+  texture: TextureId
+  joints: SceneNode[]
+  inverseBind: Float32Array
+  jointBounds: Float32Array
 }
 
 /**
@@ -162,6 +186,10 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   let materials = data.materials.map((_, i) => materialFor(i, false))
 
   let model = createGroup() as Model
+  model._skins = []
+  model._worn = []
+  model._body = null
+  model._grafts = []
   // The node table is pre-order, so every parent group exists before its
   // children reference it.
   let groups: SceneNode[] = data.nodes.map((n) => {
@@ -183,39 +211,38 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   // joints move - there is no JS palette walk, and posing joints with
   // setTransform is always enough. Identical skins (same joints, same
   // inverse binds - the body/legs and LOD splits exporters produce) share
-  // one texture, so their palette is computed and uploaded once.
-  let skinTextures: TextureId[] = []
+  // one texture, so their palette is computed and uploaded once. A worn
+  // piece's rows move onto another model's joints (bindSkeleton).
   data.skins.forEach((skin, i) => {
-    let joints = skin.joints.join(",")
-    for (let j = 0; j < i; j++) {
-      let other = data.skins[j]!
-      if (
-        other.joints.join(",") === joints &&
-        other.inverseBind.length === skin.inverseBind.length &&
-        other.inverseBind.every((v, k) => v === skin.inverseBind[k])
-      ) {
-        skinTextures.push(skinTextures[j]!)
-        return
-      }
-    }
-    let texture = createMutableTexture(new Float32Array(skin.joints.length * 16), 4, skin.joints.length, {
-      format: "rgba32f",
-      autoFree: false,
-      label: label ? label + "-skin" + i : "skin" + i,
+    let joints = skin.joints.map((n) => {
+      let joint = groups[n]
+      if (joint === undefined) throw new Error("createModel: skin " + i + " names a missing node " + n)
+      return joint
     })
+    let key = skin.joints.join(",")
+    let same = model._skins.find(
+      (other, j) =>
+        data.skins[j]!.joints.join(",") === key &&
+        other.inverseBind.length === skin.inverseBind.length &&
+        other.inverseBind.every((v, k) => v === skin.inverseBind[k]),
+    )
+    let texture =
+      same?.texture ??
+      createMutableTexture(new Float32Array(skin.joints.length * 16), 4, skin.joints.length, {
+        format: "rgba32f",
+        autoFree: false,
+        label: label ? label + "-skin" + i : "skin" + i,
+      })
+    model._skins.push({ texture, joints, inverseBind: skin.inverseBind, jointBounds: skin.jointBounds })
+    if (same !== undefined) return
     textures.push(texture)
-    skinTextures.push(texture)
-    for (let j = 0; j < skin.joints.length; j++) {
-      let joint = groups[skin.joints[j]!]
-      if (joint === undefined) throw new Error("createModel: skin " + i + " names a missing node " + skin.joints[j])
+    joints.forEach((joint, j) => {
       ;(joint._palettes ??= []).push({ texture, row: j, post: skin.inverseBind.slice(j * 16, j * 16 + 16), anchor: model })
-      // The joint's influence box, in joint space: culling-only bounds the
-      // flush carries through the pose. A joint influencing nothing (an
-      // inverted box) gets none and contributes nothing to the union.
-      let jb = skin.jointBounds.subarray(j * 6, j * 6 + 6)
-      if (jb[0]! <= jb[3]! && jb[1]! <= jb[4]! && jb[2]! <= jb[5]!) joint._cullBounds = Float32Array.from(jb)
-    }
+    })
   })
+  // Each joint's influence box, in joint space: culling-only bounds the
+  // flush carries through the pose, united over every skin reaching it.
+  refreshJointBounds(model)
   model.parts = data.parts.map((part) => {
     let skinned = part.skin !== null
     let material = materialFor(part.material, skinned)
@@ -225,11 +252,11 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       // matrices place them, so its mesh hangs off the model root (the
       // spec ignores the node's transform for skinned meshes) and uModel
       // stays the model's own placement.
-      let texture = skinTextures[part.skin!]
-      if (texture === undefined) throw new Error("createModel: part '" + part.name + "' names a missing skin " + part.skin)
-      mesh._textures = { uBones: texture }
+      let skin = model._skins[part.skin!]
+      if (skin === undefined) throw new Error("createModel: part '" + part.name + "' names a missing skin " + part.skin)
+      mesh._textures = { uBones: skin.texture }
       // Culled by its joints' boxes, so the box follows the animation.
-      mesh._cullJoints = data.skins[part.skin!]!.joints.map((n) => groups[n]!)
+      mesh._cullJoints = skin.joints.slice()
       add(model, mesh)
     } else {
       let node = groups[part.node]
@@ -242,6 +269,11 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   model.clips = data.clips
   model.bounds = data.bounds
   model.dispose = () => {
+    // A worn piece comes off first (its rows sit on the body's joints);
+    // a body takes its pieces with it (their skins read joints that are
+    // about to go).
+    if (model._body !== null) unbindSkeleton(model)
+    for (let worn of model._worn.slice()) worn.piece.dispose()
     if (model.parent !== null) remove(model)
     for (let part of model.parts) disposeGeometry(part.mesh.geometry)
     for (let id of textures) destroyTexture(id)

package/src/node.ts

@@ -10,12 +10,14 @@ import * as spatial from "flux:spatial"
 import type { NodeId, NodeTransition } from "flux:spatial"
 import { on } from "srt:events"
 import type { ShaderParams, TextureId } from "@solidrt/core/gpu"
+import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
 // The scene's lookAt() aims a node; math's builds a camera's view matrix -
 // the same pairing (and the same name) as Three's Object3D/Matrix4.
 import { compose, eulerFromQuat, identity, mat4, multiply, quat, quatFromFrame, transformPoint, updateRotation, updateScale } from "./math.ts"
 import type { Mat4, Quat, TransformUpdate, Vec3, Vec4 } from "./math.ts"
 import type { CastingLight, Light } from "./light.ts"
 import type { InstancedMesh, InstanceNode, Mesh } from "./mesh.ts"
+import type { Scene, ViewHandle } from "./scene.ts"
 
 // lookAt()'s default roll reference. Read-only: quatFromFrame never
 // writes its inputs, so one shared vector is safe.
@@ -107,15 +109,23 @@ export type SceneNode = {
   visible: boolean
   /** Pointer event handlers - plain fields, assign freely (they touch no
    * GPU state, so they need no setTransform-style write path; components
-   * sync their props here). Down/move/up dispatch on the hit mesh and
-   * bubble through its ancestors (stopPropagation stops the walk);
-   * enter/leave fire on the mesh alone. Events flow once the element
-   * showing the scene carries `scene.handlers`. */
-  onPointerDown?: (event: ScenePointerEvent) => void
-  onPointerMove?: (event: ScenePointerEvent) => void
-  onPointerUp?: (event: ScenePointerEvent) => void
-  onPointerEnter?: (event: ScenePointerEvent) => void
-  onPointerLeave?: (event: ScenePointerEvent) => void
+   * sync their props here). Down/move/up/wheel/tap dispatch on the
+   * nearest hit - the struck instance of an instanced mesh, else the mesh
+   * - bubble through its ancestors and end at the scene's listeners
+   * (stopPropagation stops the walk, and a stopped down claims the whole
+   * press); enter/leave fire on the struck node alone. Events flow once
+   * the element showing the scene carries `scene.handlers`. */
+  onPointerDown?: (event: NodePointerEvent) => void
+  onPointerMove?: (event: NodePointerEvent) => void
+  onPointerUp?: (event: NodePointerEvent) => void
+  onPointerEnter?: (event: NodePointerEvent) => void
+  onPointerLeave?: (event: NodePointerEvent) => void
+  /** The wheel over the node (NodeWheelEvent: `deltaX`/`deltaY`), bubbling
+   * like down/move/up. */
+  onWheel?: (event: NodeWheelEvent) => void
+  /** A press released on this node within the slop, alone for its whole
+   * press (NodeTapEvent: `tapCount`); bubbles like down/move/up. */
+  onTap?: (event: NodeTapEvent) => void
   /** A declared transition (setTransition) settled naturally on one
    * component; a cancel, snap or scene leave never fires. */
   onTransitionEnd?: (event: TransitionEndEvent) => void
@@ -133,7 +143,8 @@ export type SceneNode = {
    * skin): bound to the core at every scene enter, so the flush writes
    * `inverse(anchorWorld) * world * post` - the model-local bone matrix -
    * to the palette texture's row whenever the node moves. `anchor` is the
-   * model root; null for non-joints (the common case pays one null check). */
+   * model root - the body's, for a piece bound onto its skeleton - and
+   * null for non-joints (the common case pays one null check). */
   _palettes: { texture: TextureId; row: number; post: Float32Array; anchor: SceneNode }[] | null
   /** A culling-only local box (a model joint's influence region, in joint
    * space): bound at every scene enter so the joint's world box follows
@@ -146,26 +157,19 @@ export type TransitionEndEvent = {
   component: "position" | "rotation" | "scale"
 }
 
-/**
- * The event a mesh, instance or ancestor group handler receives: the
- * element pointer vocabulary carried over, plus the 3D fields.
- * `point`/`distance` are null exactly when the ray misses the dispatch
- * target - which happens only during a captured drag or on a leave.
- */
-export type ScenePointerEvent = {
-  /** The mesh the event is about (the hit, or the captured mesh during a
-   * drag) - constant while the event bubbles. */
-  mesh: Mesh
+/** What every scene pointer event carries, whichever handler sees it:
+ * the element pointer vocabulary carried over, plus the 3D fields. */
+export type SceneEventBase = {
   /** The instance struck when `mesh` is an instanced mesh (the walk
    * starts there), null otherwise - constant while the event bubbles. */
   instance: InstanceNode | null
-  /** Node whose handler is running; changes as the event bubbles. */
-  currentTarget: SceneNode
-  /** World-space hit point on `mesh`, or null when the ray misses it. */
+  /** World-space hit point on `mesh`, or null when there is no mesh or
+   * the ray misses it (a captured drag off the mesh, a leave). */
   point: Vec3 | null
   /** Camera-ray distance to `point` in world units, or null with it. */
   distance: number | null
-  /** Pointer position in scene pixels - project()'s coordinate space. */
+  /** Pointer position in scene pixels - project()'s coordinate space
+   * (a view's own pixels under a view leaf). */
   x: number
   y: number
   pointerId: number
@@ -175,10 +179,77 @@ export type ScenePointerEvent = {
   ctrlKey: boolean
   altKey: boolean
   metaKey: boolean
-  /** Stops the bubble walk after the current handler. */
+  /**
+   * The element event the scene's leaf received, in the leaf's own frame
+   * (localX/localY, clientX/clientY, movementX/Y): what core's
+   * recognizers consume, so a mesh drags itself through `createPan` and
+   * a camera control's feed rides the same events the walk carries.
+   */
+  native: ElementPointerEvent
+  /**
+   * Stops the walk after the current handler: no ancestor and none of the
+   * scene's listeners see the event. Stopping a DOWN claims the whole
+   * press - that pointer's move, up and tap never reach the scene either,
+   * so a mesh that drags itself stops its down once and an orbit control
+   * fed at the root never turns under it.
+   */
   stopPropagation(): void
 }
 
+/**
+ * The event a mesh, instance or ancestor group handler receives: `mesh`
+ * is the hit (or the captured mesh during a drag), constant while the
+ * event bubbles; `currentTarget` the node whose handler is running.
+ */
+export type NodePointerEvent = SceneEventBase & {
+  mesh: Mesh
+  currentTarget: SceneNode
+}
+
+/**
+ * The event as the SCENE's listeners see it (scene.listen, the `<Scene>`
+ * pointer props; a view's under its own leaf), the last stop of the walk:
+ * `mesh` is the hit it bubbled from, or null over empty space, where the
+ * scene is the only target.
+ */
+export type ScenePointerEvent = SceneEventBase & {
+  mesh: Mesh | null
+  currentTarget: Scene | ViewHandle
+}
+
+type WheelFields = {
+  /** The wheel delta as the element event reports it. */
+  deltaX: number
+  deltaY: number
+  native: ElementWheelEvent
+}
+type TapFields = {
+  /** 1 for a tap, 2 for the second of a double tap (the same target,
+   * within the repeat interval and distance), and so on - DOM's `detail`,
+   * Unity's `clickCount`. */
+  tapCount: number
+}
+
+export type NodeWheelEvent = NodePointerEvent & WheelFields
+export type SceneWheelEvent = ScenePointerEvent & WheelFields
+/**
+ * A press that released on the target it pressed without travelling past
+ * the slop, the only pointer down for its whole press (a pinch never
+ * taps). Dispatched after the up, bubbling the same way; `x`/`y` and
+ * `point` are the release point.
+ */
+export type NodeTapEvent = NodePointerEvent & TapFields
+export type SceneTapEvent = ScenePointerEvent & TapFields
+
+/** A listener at the scene's (or a view's) root; see Scene.listen. */
+export type ScenePointerListener = {
+  onPointerDown?: (event: ScenePointerEvent) => void
+  onPointerMove?: (event: ScenePointerEvent) => void
+  onPointerUp?: (event: ScenePointerEvent) => void
+  onWheel?: (event: SceneWheelEvent) => void
+  onTap?: (event: SceneTapEvent) => void
+}
+
 /** A bare node record (internal: the mesh and light constructors build on it). */
 export function makeNode(kind: SceneNode["kind"]): SceneNode {
   return {
@@ -245,7 +316,10 @@ export function enterScene(node: SceneNode, scene: SceneHooks): void {
     }
   }
   if (node._cullBounds !== null) spatial.setCullBounds(node._node, node._cullBounds)
-  if (node.kind === "mesh") scene._attach(node as Mesh)
+  if (node.kind === "mesh") {
+    spatial.setLayers(node._node, (node as Mesh).layers)
+    scene._attach(node as Mesh)
+  }
   else if (node.kind === "light") scene._attachLight(node as Light)
   else if (node.kind === "instance") scene._attachInstance(node as InstanceNode)
   for (let c of node.children) enterScene(c, scene)