@solidrt/3d 0.0.57 → 0.0.58

package/examples/README.md

@@ -142,6 +142,12 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   transparent dome and a mesh without normals) parsed with `parseGltf`
   from a binary import and built by `createModel` into a Group of named
   parts; clicking a part hides it, clicking the body restores all.
+- `wireframe.tsx` - the rover drawn solid, as a wireframe or as its
+  feature edges: `wireframeGeometry`/`edgesGeometry` build "lines"
+  geometry over each part's own vertices (one shared vertex upload, a
+  second index buffer) and `setGeometry`/`setMaterial` swap it onto the
+  live mesh, no node touched. Space, a tap on the rover, or the `wire`
+  debug command (`{ mode: "solid" | "wireframe" | "edges" }`) cycles.
 - `model-load.tsx` - the same rover loaded ASYNC with `loadModel` from
   `assets/` under a `<Loading>` boundary: the async read lives in a memo,
   a second memo derives the scene JSX after that read, and the shell

package/examples/wireframe.tsx

@@ -0,0 +1,107 @@
+// The rover drawn solid, as a wireframe or as its feature edges. Both line
+// forms are GEOMETRY: wireframeGeometry lists every edge of a triangle
+// geometry once, edgesGeometry only the edges where two faces meet at the
+// threshold angle or more (plus the open borders), each as a "lines"
+// geometry over the source's OWN vertex array. The topology rides on the
+// geometry, so the plain unlit material draws it as lines, and the vertex
+// upload is shared, so a mode costs an index buffer, not a second model.
+// The swap is setGeometry + setMaterial on the live mesh: the node, its
+// transform and its pointer handlers are untouched. Space, a tap on the
+// rover or the `wire` debug command ({ mode }) cycles the modes.
+
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { createTexture } from "@solidrt/core/gpu"
+import type { TextureId } from "@solidrt/core/gpu"
+import { registerDebug } from "srt:dev"
+import { add, createModel, DirectionalLight, edgesGeometry, equirectToCube, Group, parseGltf, PerspectiveCamera, Scene, setGeometry, setMaterial, unlit, wireframeGeometry } from "@solidrt/3d"
+import type { SceneNode } from "@solidrt/3d"
+import modelBytes from "./model.glb" with { type: "binary" }
+
+const MODES = ["solid", "wireframe", "edges"] as const
+type Mode = (typeof MODES)[number]
+// Feature-edge threshold in degrees: above the facet angle of the rover's
+// rounded parts, so their seams stay hidden and only rims and creases draw.
+const EDGE_ANGLE = 20
+const LINE_COLOR: [number, number, number] = [0.85, 0.95, 1]
+// Face edge of the gradient environment cube: a gradient needs no detail.
+const ENV_FACE = 16
+// The gradient, zenith to nadir, sRGB bytes: sky, horizon, ground, below.
+const ENV_ROWS: [number, number, number][] = [
+  [96, 122, 168],
+  [176, 190, 210],
+  [120, 105, 90],
+  [60, 52, 45],
+]
+
+// A tiny equirectangular panorama turned into the cube the solid rover's
+// standard materials light by (see model.tsx).
+function gradientEnvironment(): TextureId {
+  let px = new Uint8Array(2 * ENV_ROWS.length * 4)
+  ENV_ROWS.forEach((c, y) => {
+    for (let x = 0; x < 2; x++) px.set([c[0], c[1], c[2], 255], (y * 2 + x) * 4)
+  })
+  let panorama = createTexture(px, 2, ENV_ROWS.length, { format: "rgba8-srgb", filter: "linear" })
+  return equirectToCube(panorama, ENV_FACE, { format: "rgba8-srgb", mipmap: true, label: "gradient-env" })
+}
+
+function App() {
+  let cube = gradientEnvironment()
+  let [t, setT] = createSignal(0)
+  onFrame(tick => setT(tick / 1000))
+
+  let model = createModel(parseGltf(modelBytes), { label: "rover" })
+  let b = model.bounds
+  let center: [number, number, number] = [(b[0]! + b[3]!) / 2, (b[1]! + b[4]!) / 2, (b[2]! + b[5]!) / 2]
+  let radius = Math.hypot(b[3]! - b[0]!, b[4]! - b[1]!, b[5]! - b[2]!) / 2
+
+  // One line material for every part and both line modes. Per part, what
+  // each mode swaps in: the line geometries share the solid's vertices,
+  // so building both up front costs their index buffers only.
+  let lines = unlit({ color: LINE_COLOR })
+  let looks = model.parts.map(part => ({
+    mesh: part.mesh,
+    solid: { geometry: part.mesh.geometry, material: part.mesh.material },
+    wireframe: wireframeGeometry(part.mesh.geometry),
+    edges: edgesGeometry(part.mesh.geometry, EDGE_ANGLE),
+  }))
+  let mode: Mode = "solid"
+  let apply = (next: Mode): void => {
+    mode = next
+    for (let look of looks) {
+      // Each call rebuilds the draw entry, so the intermediate state is
+      // always the line material over the solid's triangles - a pipeline
+      // unlit has anyway - never the solid material over lines.
+      if (next === "solid") {
+        setGeometry(look.mesh, look.solid.geometry)
+        setMaterial(look.mesh, look.solid.material)
+      } else {
+        setMaterial(look.mesh, lines)
+        setGeometry(look.mesh, look[next])
+      }
+    }
+  }
+  let cycle = (): void => apply(MODES[(MODES.indexOf(mode) + 1) % MODES.length]!)
+  for (let part of model.parts) part.mesh.onTap = cycle
+  registerDebug("wire", (args?: Record<string, unknown>) => {
+    if (typeof args?.mode === "string" && (MODES as readonly string[]).includes(args.mode)) apply(args.mode as Mode)
+    else cycle()
+  })
+
+  return (
+    <window
+      onKeyDown={e => {
+        if (e.key === " ") cycle()
+      }}
+    >
+      <view width={pct(100)} height={pct(100)}>
+        <Scene clearColor={[0.1, 0.11, 0.14, 1]} environment={{ cube }} samples={4} label="wireframe">
+          <PerspectiveCamera fov={40} position={[center[0] + radius * 1.4, center[1] + radius * 1.1, center[2] + radius * 2.2]} lookAt={center} />
+          <DirectionalLight direction={[0.5, -0.8, 0.3]} color={[1, 0.95, 0.85]} intensity={0.9} />
+          <Group rotation={[0, t() / 3, 0]} ref={(g: SceneNode) => add(g, model)} />
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -19,6 +19,6 @@
   ],
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.6",
-    "@solidrt/core": "0.0.57"
+    "@solidrt/core": "0.0.58"
   }
 }

package/src/geometry-gpu.ts

@@ -15,7 +15,7 @@ import { createBuffer, destroyBuffer } from "@solidrt/core/gpu"
 import type { BufferId, IndexFormat } from "@solidrt/core/gpu"
 import { createShape, destroyShape } from "flux:spatial"
 import type { ShapeId } from "flux:spatial"
-import { layoutStride } from "./geometry.ts"
+import { geometryTopology, layoutStride } from "./geometry.ts"
 import type { Geometry } from "./geometry.ts"
 
 /** An acquired reference to a geometry's GPU buffers: what a draw entry
@@ -26,14 +26,45 @@ export type GeometryBuffers = {
   buffer: BufferId
   index: BufferId
   indexFormat: IndexFormat
-  /** The picking shape (positions at 0, uv at 6 of every layout). */
-  shape: ShapeId
+  /** The picking shape (positions at 0, uv at 6 of every layout); null
+   * for anything but a triangle list, which picks by its box. */
+  shape: ShapeId | null
 }
 
-type GpuEntry = GeometryBuffers & { geometry: Geometry; refs: number }
+type GpuEntry = GeometryBuffers & { geometry: Geometry; vertices: Float32Array; refs: number }
 
 let entries = new WeakMap<Geometry, GpuEntry>()
 
+/** Vertex uploads keyed by the array itself: geometries sharing one
+ * vertex array (a wireframe or edges geometry over its source's) share
+ * one GPU buffer, each entry holding a reference to it. */
+let vertexUploads = new WeakMap<Float32Array, { buffer: BufferId; refs: number }>()
+
+function acquireVertices(geometry: Geometry): BufferId {
+  let upload = vertexUploads.get(geometry.vertices)
+  if (upload === undefined) {
+    upload = {
+      buffer: createBuffer(geometry.vertices, {
+        autoFree: false,
+        label: geometry.label ? geometry.label + "-verts" : undefined,
+      }),
+      refs: 0,
+    }
+    vertexUploads.set(geometry.vertices, upload)
+  }
+  upload.refs++
+  return upload.buffer
+}
+
+function releaseVertices(vertices: Float32Array): void {
+  let upload = vertexUploads.get(vertices)
+  if (upload === undefined) return
+  upload.refs--
+  if (upload.refs > 0) return
+  vertexUploads.delete(vertices)
+  destroyBuffer(upload.buffer)
+}
+
 /** The geometry's GPU buffers, created on first use, plus the index format
  * the draw entry must bind them with. Takes a reference - pair every
  * acquire with a releaseGeometryBuffers of the returned token when the
@@ -43,16 +74,17 @@ export function acquireGeometryBuffers(geometry: Geometry): GeometryBuffers {
   if (entry === undefined) {
     entry = {
       geometry,
-      buffer: createBuffer(geometry.vertices, {
-        autoFree: false,
-        label: geometry.label ? geometry.label + "-verts" : undefined,
-      }),
+      vertices: geometry.vertices,
+      buffer: acquireVertices(geometry),
       index: createBuffer(geometry.indices, {
         autoFree: false,
         label: geometry.label ? geometry.label + "-indices" : undefined,
       }),
       indexFormat: geometry.indices instanceof Uint32Array ? "uint32" : "uint16",
-      shape: createShape(geometry.vertices, layoutStride(geometry.layout), 0, 6, geometry.indices),
+      shape:
+        geometryTopology(geometry) === "triangles"
+          ? createShape(geometry.vertices, layoutStride(geometry.layout), 0, 6, geometry.indices)
+          : null,
       refs: 0,
     }
     entries.set(geometry, entry)
@@ -74,9 +106,9 @@ export function releaseGeometryBuffers(acquired: GeometryBuffers): void {
   queueMicrotask(() => {
     if (entries.get(entry.geometry) !== entry || entry.refs > 0) return
     entries.delete(entry.geometry)
-    destroyBuffer(entry.buffer)
+    releaseVertices(entry.vertices)
     destroyBuffer(entry.index)
-    destroyShape(entry.shape)
+    if (entry.shape !== null) destroyShape(entry.shape)
   })
 }
 
@@ -91,7 +123,7 @@ export function disposeGeometry(geometry: Geometry): void {
   let entry = entries.get(geometry)
   if (entry === undefined) return
   entries.delete(geometry)
-  destroyBuffer(entry.buffer)
+  releaseVertices(entry.vertices)
   destroyBuffer(entry.index)
-  destroyShape(entry.shape)
+  if (entry.shape !== null) destroyShape(entry.shape)
 }

package/src/geometry.ts

@@ -21,7 +21,7 @@
 // array math (the check rig checks/geometry-check.ts runs it headless on
 // flux). The GPU buffer step lives in geometry-gpu.ts.
 
-import type { VertexAttribute } from "@solidrt/core/gpu"
+import type { Topology, VertexAttribute } from "@solidrt/core/gpu"
 import { add, compose, cross, mat4, normalize, normalMatrix, sub, updateRotation, updateScale } from "./math.ts"
 import type { Quat, TransformUpdate, Vec2, Vec3 } from "./math.ts"
 
@@ -50,7 +50,10 @@ export const VERTEX_LAYOUTS: Record<"standard" | "colored" | "skinned", VertexAt
  * format before packing). */
 export const STANDARD_FLOATS = 8
 
-const FORMAT_FLOATS: Record<VertexAttribute["format"], number> = { f32: 1, vec2: 2, vec3: 3, vec4: 4 }
+/** Floats per attribute format: the vertex vocabulary itself, so it is
+ * also the list a declared format must be one of (vertex attributes and
+ * instance attributes both). */
+export const FORMAT_FLOATS: Record<VertexAttribute["format"], number> = { f32: 1, vec2: 2, vec3: 3, vec4: 4 }
 
 /** The attribute list of a layout (a preset name resolves to its list). */
 export function layoutAttributes(layout?: VertexLayout): VertexAttribute[] {
@@ -123,7 +126,35 @@ export function validateGeometry(geometry: Geometry): void {
       name + ": " + geometry.vertices.length + " vertex floats is not a whole number of " + stride + "-float (" + layoutKey(layout) + ") vertices",
     )
   }
-  if (geometry.indices.length === 0) throw new Error(name + ": no indices")
+  let topology = geometryTopology(geometry)
+  let count = geometry.indices.length
+  // Lines and points may be empty: a feature-edge pass over a smooth
+  // closed shape has nothing to draw, and that is a result, not a bug.
+  switch (topology) {
+    case "triangles":
+      if (count === 0) throw new Error(name + ": no indices")
+      if (count % 3 !== 0) throw new Error(name + ": " + count + " indices is not a whole number of triangles")
+      break
+    case "lines":
+      if (count % 2 !== 0) throw new Error(name + ": " + count + " indices is not a whole number of lines")
+      break
+    case "line-strip":
+      if (count < 2) throw new Error(name + ": a line strip needs at least 2 indices")
+      break
+    case "triangle-strip":
+      if (count < 3) throw new Error(name + ": a triangle strip needs at least 3 indices")
+      break
+    case "points":
+      break
+    default:
+      throw new Error(name + ": unknown topology '" + String(topology) + "'")
+  }
+}
+
+/** The geometry's topology with the default applied: what its indices
+ * list, "triangles" unless it says otherwise. */
+export function geometryTopology(geometry: Geometry): Topology {
+  return geometry.topology ?? "triangles"
 }
 
 /** The options every generator shares (each generator's own options type
@@ -194,6 +225,20 @@ export type Geometry = {
   /** The array type picks the draw's index format: Uint32Array past 64k
    * vertices. */
   indices: Uint16Array | Uint32Array
+  /** What the indices describe; absent means "triangles". The index
+   * buffer and the primitive it lists travel together (Godot's surface
+   * primitive, Unity's Mesh.SetIndices topology, Three's Line/Points
+   * object types over one BufferGeometry): the material draws whatever
+   * topology its geometry carries, one pipeline per (layout, topology)
+   * pair. Only a triangle list gets the picking shape - a lines, points
+   * or strip geometry picks (and collides) by its bounds box, the tier a
+   * sprite or an instanced mesh is at, so hits carry no face/uv. Lines
+   * are one pixel wide on GL ES whatever the display density. A lines
+   * or points geometry may have no indices at all (it then draws
+   * nothing; the other topologies reject that at add()).
+   * wireframeGeometry/edgesGeometry build "lines" over a triangle
+   * geometry's own vertices. */
+  topology?: Topology
   /** Vertex layout; absent means "standard". Must match the material's
    * layout - the scene rejects a mismatched pair at add(). */
   layout?: VertexLayout
@@ -270,6 +315,7 @@ export function withAttribute(geometry: Geometry, attr: VertexAttribute, fill: A
   return {
     vertices: out,
     indices: geometry.indices,
+    topology: geometry.topology,
     layout,
     label: label ?? (geometry.label ? geometry.label + "-" + attr.name : undefined),
   }
@@ -394,6 +440,7 @@ export function transformGeometry(geometry: Geometry, transform: TransformUpdate
   return {
     vertices: out,
     indices: geometry.indices,
+    topology: geometry.topology,
     layout: geometry.layout,
     label: label ?? (geometry.label ? geometry.label + "-transformed" : undefined),
   }
@@ -403,7 +450,9 @@ export function transformGeometry(geometry: Geometry, transform: TransformUpdate
  * Concatenate geometries into one: vertices appended in order, indices
  * offset to match, uint32 indices past 64k vertices. Every part must share
  * one layout - a mixed list throws, because the strides differ and a merge
- * that picked one would draw garbage, not a mesh missing a channel. The
+ * that picked one would draw garbage, not a mesh missing a channel - and
+ * one list topology (a mixed list throws the same way; strips cannot be
+ * concatenated at all, the seam would join them). The
  * second half of authoring a static scene as data (Three's
  * `BufferGeometryUtils.mergeGeometries`): the result is one draw entry and
  * one uModel write however many parts went in, so only what actually moves
@@ -414,12 +463,17 @@ export function mergeGeometries(parts: Geometry[], label?: string): Geometry {
   let layout = parts[0]!.layout
   let key = layoutKey(layout)
   let stride = layoutStride(layout)
+  let topology = geometryTopology(parts[0]!)
+  if (topology === "line-strip" || topology === "triangle-strip") throw new Error("mergeGeometries: cannot merge " + topology + " geometry")
   let floats = 0
   let indexCount = 0
   for (let part of parts) {
     if (layoutKey(part.layout) !== key) {
       throw new Error("mergeGeometries: mixed layouts (" + key + " and " + layoutKey(part.layout) + ")")
     }
+    if (geometryTopology(part) !== topology) {
+      throw new Error("mergeGeometries: mixed topologies (" + topology + " and " + geometryTopology(part) + ")")
+    }
     if (part.vertices.length % stride !== 0) {
       throw new Error("mergeGeometries: a part's vertex data is not a whole number of " + key + " vertices")
     }
@@ -439,7 +493,134 @@ export function mergeGeometries(parts: Geometry[], label?: string): Geometry {
     vOffset += part.vertices.length
     iOffset += src.length
   }
-  return { vertices, indices, layout, label }
+  return { vertices, indices, topology: parts[0]!.topology, layout, label }
+}
+
+/** Positions closer than this (model units) are one vertex to the edge
+ * builders: a uv seam or a per-face normal split duplicates a position,
+ * and an edge is the same edge whichever copy a triangle names. */
+const WELD_PRECISION = 1e-4
+
+/** Degrees between two faces' normals from which the edge between them
+ * counts as a feature edge in edgesGeometry; under it the faces read as
+ * one smooth surface and the edge stays hidden. Three's default. */
+const EDGES_THRESHOLD_ANGLE = 1
+
+/** One id per vertex, shared by every vertex at the same position (to
+ * WELD_PRECISION) whatever its normal and uv; plus the id count. */
+function weldPositions(geometry: Geometry): { ids: Uint32Array; count: number } {
+  let v = geometry.vertices
+  let stride = layoutStride(geometry.layout)
+  let count = v.length / stride
+  let ids = new Uint32Array(count)
+  let seen = new Map<string, number>()
+  let scale = 1 / WELD_PRECISION
+  for (let i = 0; i < count; i++) {
+    let b = i * stride
+    let key = Math.round(v[b]! * scale) + "," + Math.round(v[b + 1]! * scale) + "," + Math.round(v[b + 2]! * scale)
+    let id = seen.get(key)
+    if (id === undefined) {
+      id = seen.size
+      seen.set(key, id)
+    }
+    ids[i] = id
+  }
+  return { ids, count: seen.size }
+}
+
+/** The edge table of a triangle geometry, welded by position, as a lines
+ * index list: every edge once for `cosThreshold` null, else the feature
+ * edges - those with one face (a border) or whose two faces' normals
+ * dot at or below the threshold. Each edge names the vertex pair of the
+ * first triangle that had it. */
+function edgeIndices(geometry: Geometry, name: string, cosThreshold: number | null): Uint16Array | Uint32Array {
+  if (geometryTopology(geometry) !== "triangles") {
+    throw new Error(name + ": needs a triangle geometry, got " + geometryTopology(geometry))
+  }
+  let v = geometry.vertices
+  let stride = layoutStride(geometry.layout)
+  let weld = weldPositions(geometry)
+  let src = geometry.indices
+  type Edge = { a: number; b: number; nx: number; ny: number; nz: number; faces: number; sharp: boolean }
+  let edges = new Map<number, Edge>()
+  for (let t = 0; t + 2 < src.length; t += 3) {
+    let i0 = src[t]!, i1 = src[t + 1]!, i2 = src[t + 2]!
+    let p0 = i0 * stride, p1 = i1 * stride, p2 = i2 * stride
+    // The face normal, for the feature test.
+    let ux = v[p1]! - v[p0]!, uy = v[p1 + 1]! - v[p0 + 1]!, uz = v[p1 + 2]! - v[p0 + 2]!
+    let wx = v[p2]! - v[p0]!, wy = v[p2 + 1]! - v[p0 + 1]!, wz = v[p2 + 2]! - v[p0 + 2]!
+    let nx = uy * wz - uz * wy, ny = uz * wx - ux * wz, nz = ux * wy - uy * wx
+    let len = Math.hypot(nx, ny, nz) || 1
+    nx /= len
+    ny /= len
+    nz /= len
+    for (let k = 0; k < 3; k++) {
+      let ia = k === 0 ? i0 : k === 1 ? i1 : i2
+      let ib = k === 0 ? i1 : k === 1 ? i2 : i0
+      let wa = weld.ids[ia]!, wb = weld.ids[ib]!
+      if (wa === wb) continue
+      let key = Math.min(wa, wb) * weld.count + Math.max(wa, wb)
+      let e = edges.get(key)
+      if (e === undefined) {
+        edges.set(key, { a: ia, b: ib, nx, ny, nz, faces: 1, sharp: false })
+      } else {
+        e.faces++
+        if (cosThreshold !== null && !e.sharp && e.nx * nx + e.ny * ny + e.nz * nz <= cosThreshold) e.sharp = true
+      }
+    }
+  }
+  let out: number[] = []
+  for (let e of edges.values()) {
+    if (cosThreshold === null || e.faces === 1 || e.sharp) out.push(e.a, e.b)
+  }
+  return packIndices(out, v.length / stride)
+}
+
+/**
+ * Every edge of a triangle geometry as a "lines" geometry over the SAME
+ * vertices (Three's WireframeGeometry): each triangle's three sides, once
+ * each - edges are matched by position, so a uv seam or a per-face
+ * normal split draws one line, not two on top of each other. The
+ * source's vertex array and layout are shared by reference, and so is
+ * their GPU upload, which makes the wireframe a second index buffer over
+ * the same vertices: a "skinned" part's wireframe draws in its pose
+ * under `unlit({ skinned: true })` with the mesh's own palette, and any
+ * material draws it as lines because the topology rides on the
+ * geometry. Lines are one pixel wide.
+ */
+export function wireframeGeometry(geometry: Geometry, label?: string): Geometry {
+  return {
+    vertices: geometry.vertices,
+    indices: edgeIndices(geometry, "wireframeGeometry", null),
+    topology: "lines",
+    layout: geometry.layout,
+    label: label ?? (geometry.label ? geometry.label + "-wireframe" : undefined),
+  }
+}
+
+/**
+ * The feature edges of a triangle geometry as a "lines" geometry over the
+ * same vertices (Three's EdgesGeometry): an edge draws when its two faces
+ * meet at `thresholdAngle` degrees or more, or when only one face has it
+ * (an open border): the outline that a dense mesh's wireframe, a solid
+ * blob, cannot give. A box draws its twelve edges and no face diagonals
+ * at any threshold; a generated round shape is faceted, so its facet
+ * lines show until the threshold passes its facet angle (360 divided by
+ * the radial segments: a default cylinder loses its side seams and keeps
+ * its two rims from 16 degrees, a default sphere draws nothing from 16).
+ * A smooth closed shape above its facet angle has no edges at all, and
+ * the empty lines geometry that comes back attaches and draws nothing.
+ * Shares vertices, layout and GPU upload with the source like
+ * wireframeGeometry.
+ */
+export function edgesGeometry(geometry: Geometry, thresholdAngle = EDGES_THRESHOLD_ANGLE, label?: string): Geometry {
+  return {
+    vertices: geometry.vertices,
+    indices: edgeIndices(geometry, "edgesGeometry", Math.cos((thresholdAngle * Math.PI) / 180)),
+    topology: "lines",
+    layout: geometry.layout,
+    label: label ?? (geometry.label ? geometry.label + "-edges" : undefined),
+  }
 }
 
 // Indices for a row-major (cellRows + 1) x (cellCols + 1) vertex grid: two