@solidrt/3d 0.0.58 → 0.0.59

package/src/geometry-gpu.ts

@@ -1,7 +1,8 @@
 // Geometry on the GPU: the lazy buffer step for geometry.ts's data. Buffers
-// (and the picking shape - the spatial core's own copy of positions, UVs
-// and indices for the triangle narrowphase, one per geometry however many
-// meshes share it) are created on first acquire and shared by every mesh
+// (and the shape - the spatial core's own copy of positions, UVs and, for
+// a triangle list, indices, one per geometry however many meshes share
+// it: the box of every node drawing the geometry and the triangle
+// narrowphase) are created on first acquire and shared by every mesh
 // and scene drawing the geometry; each draw entry holds one reference, and
 // the buffers are
 // freed when the last reference is released - deferred to a microtask, so
@@ -11,52 +12,74 @@
 // disposeGeometry frees immediately, the explicit override; either way the
 // geometry stays usable - fresh buffers are created on next acquire.
 
-import { createBuffer, destroyBuffer } from "@solidrt/core/gpu"
-import type { BufferId, IndexFormat } from "@solidrt/core/gpu"
-import { createShape, destroyShape } from "flux:spatial"
+import { createBuffer, createTexture, destroyBuffer, destroyTexture, limits, writeBuffer } from "@solidrt/core/gpu"
+import type { BufferId, IndexFormat, TextureId } from "@solidrt/core/gpu"
+import { computeNormals, createShape, destroyShape, updateShape } from "flux:spatial"
 import type { ShapeId } from "flux:spatial"
-import { geometryTopology, layoutStride } from "./geometry.ts"
-import type { Geometry } from "./geometry.ts"
+import { geometrySlot, geometryStreams, geometryTopology, geometryVertexCount, layoutSlot, layoutStride, vertexBytes, MORPH_TEXEL_FLOATS } from "./geometry.ts"
+import type { Geometry, MorphTargets } from "./geometry.ts"
 
 /** An acquired reference to a geometry's GPU buffers: what a draw entry
  * binds, and the token releaseGeometryBuffers takes - releasing the exact
  * acquisition keeps the pairing correct however the caller's geometry
  * fields have moved since. */
 export type GeometryBuffers = {
-  buffer: BufferId
+  /** One vertex buffer per stream, in stream order: what the entry binds
+   * before the material's instance buffers. */
+  buffers: BufferId[]
   index: BufferId
   indexFormat: IndexFormat
-  /** 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
+  /** The core's shape: positions (and, when the layout carries a
+   * float32x2 aUV, uvs) for every topology, the box of each node set to
+   * it; the triangle narrowphase too for a triangle list. */
+  shape: ShapeId
+  /** The geometry's packed morph targets as an rgba32f texture (what a
+   * morphing material binds as `uMorphs`, `width` its `uMorphWidth`), or
+   * null for geometry without targets. */
+  morphs: { texture: TextureId; width: number } | null
 }
 
-type GpuEntry = GeometryBuffers & { geometry: Geometry; vertices: Float32Array; refs: number }
+type GpuEntry = GeometryBuffers & { geometry: Geometry; streams: ArrayBufferView[]; refs: number }
+
+// The packed texels laid into a texture: as square as the count allows
+// (the least padding), never wider than the device permits; the shader
+// turns a texel index back into coordinates by the width.
+function uploadMorphs(morphs: MorphTargets, label: string | undefined): { texture: TextureId; width: number } {
+  let texels = morphs.texels.length / MORPH_TEXEL_FLOATS
+  let width = Math.max(1, Math.min(limits.maxTextureSize, Math.ceil(Math.sqrt(texels))))
+  let height = Math.max(1, Math.ceil(texels / width))
+  if (height > limits.maxTextureSize) {
+    throw new Error("Morph targets need " + texels + " texels, past the device's " + limits.maxTextureSize + " x " + limits.maxTextureSize + " texture")
+  }
+  let data = morphs.texels
+  if (data.length !== width * height * MORPH_TEXEL_FLOATS) {
+    data = new Float32Array(width * height * MORPH_TEXEL_FLOATS)
+    data.set(morphs.texels)
+  }
+  let texture = createTexture(data, width, height, { format: "rgba32f", filter: "nearest", autoFree: false, label: label ? label + "-morphs" : undefined })
+  return { texture, width }
+}
 
 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 }>()
+ * vertex array (a wireframe or edges geometry over its source's, a
+ * stream shared through withAttribute) share one GPU buffer, each entry
+ * holding a reference to it - which is also what makes an in-place
+ * update (updateVertices) reach every sharer. */
+let vertexUploads = new WeakMap<ArrayBufferView, { buffer: BufferId; refs: number }>()
 
-function acquireVertices(geometry: Geometry): BufferId {
-  let upload = vertexUploads.get(geometry.vertices)
+function acquireVertices(vertices: ArrayBufferView, label: string | undefined): BufferId {
+  let upload = vertexUploads.get(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 = { buffer: createBuffer(vertices, { autoFree: false, label }), refs: 0 }
+    vertexUploads.set(vertices, upload)
   }
   upload.refs++
   return upload.buffer
 }
 
-function releaseVertices(vertices: Float32Array): void {
+function releaseVertices(vertices: ArrayBufferView): void {
   let upload = vertexUploads.get(vertices)
   if (upload === undefined) return
   upload.refs--
@@ -65,6 +88,29 @@ function releaseVertices(vertices: Float32Array): void {
   destroyBuffer(upload.buffer)
 }
 
+// The shape reads positions (and uvs, when they are plain floats in
+// stream 0) through a Float32Array view over the main buffer's bytes:
+// every stride and offset is a multiple of 4, so the view is exact
+// whatever the layout packs elsewhere. A uv in a packed format or in
+// another stream is left out (hits carry no uv); positions are float32x3
+// in stream 0 by the layout rule.
+type ShapeView = { floats: Float32Array; stride: number; uvAt: number }
+
+function shapeView(geometry: Geometry): ShapeView {
+  let v = geometry.vertices
+  let floats = new Float32Array(v.buffer, v.byteOffset, v.byteLength / Float32Array.BYTES_PER_ELEMENT)
+  let uv = layoutSlot(geometry.layout, "aUV")
+  let uvAt = uv !== null && uv.format === "float32x2" ? uv.offset / Float32Array.BYTES_PER_ELEMENT : -1
+  return { floats, stride: layoutStride(geometry.layout) / Float32Array.BYTES_PER_ELEMENT, uvAt }
+}
+
+// Only a triangle list hands the core its indices: any other topology is
+// box-only, its shape there for the box alone.
+function createGeometryShape(geometry: Geometry): ShapeId {
+  let { floats, stride, uvAt } = shapeView(geometry)
+  return createShape(floats, stride, 0, uvAt, geometryTopology(geometry) === "triangles" ? geometry.indices : undefined)
+}
+
 /** 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
@@ -72,19 +118,18 @@ function releaseVertices(vertices: Float32Array): void {
 export function acquireGeometryBuffers(geometry: Geometry): GeometryBuffers {
   let entry = entries.get(geometry)
   if (entry === undefined) {
+    let streams = geometryStreams(geometry).map(s => s.vertices)
     entry = {
       geometry,
-      vertices: geometry.vertices,
-      buffer: acquireVertices(geometry),
+      streams,
+      buffers: streams.map((vertices, i) => acquireVertices(vertices, geometry.label ? geometry.label + (i === 0 ? "-verts" : "-stream" + i) : undefined)),
       index: createBuffer(geometry.indices, {
         autoFree: false,
         label: geometry.label ? geometry.label + "-indices" : undefined,
       }),
       indexFormat: geometry.indices instanceof Uint32Array ? "uint32" : "uint16",
-      shape:
-        geometryTopology(geometry) === "triangles"
-          ? createShape(geometry.vertices, layoutStride(geometry.layout), 0, 6, geometry.indices)
-          : null,
+      shape: createGeometryShape(geometry),
+      morphs: geometry.morphs === undefined ? null : uploadMorphs(geometry.morphs, geometry.label),
       refs: 0,
     }
     entries.set(geometry, entry)
@@ -106,12 +151,17 @@ export function releaseGeometryBuffers(acquired: GeometryBuffers): void {
   queueMicrotask(() => {
     if (entries.get(entry.geometry) !== entry || entry.refs > 0) return
     entries.delete(entry.geometry)
-    releaseVertices(entry.vertices)
-    destroyBuffer(entry.index)
-    if (entry.shape !== null) destroyShape(entry.shape)
+    freeEntry(entry)
   })
 }
 
+function freeEntry(entry: GpuEntry): void {
+  for (let vertices of entry.streams) releaseVertices(vertices)
+  destroyBuffer(entry.index)
+  destroyShape(entry.shape)
+  if (entry.morphs !== null) destroyTexture(entry.morphs.texture)
+}
+
 /**
  * Free the geometry's GPU buffers now, held references or not - the
  * explicit override for geometry an app is done with for good. Draw
@@ -123,7 +173,90 @@ export function disposeGeometry(geometry: Geometry): void {
   let entry = entries.get(geometry)
   if (entry === undefined) return
   entries.delete(geometry)
-  releaseVertices(entry.vertices)
-  destroyBuffer(entry.index)
-  if (entry.shape !== null) destroyShape(entry.shape)
+  freeEntry(entry)
+}
+
+/** Options of `updateVertices`: the stream (default 0, the main buffer)
+ * and the vertex range (default the whole stream). */
+export type UpdateVerticesOptions = { stream?: number; first?: number; count?: number }
+
+/**
+ * Re-upload vertices `[first, first + count)` of one stream from the
+ * geometry's own array, in place: Three's `attribute.needsUpdate` with an
+ * update range. Write the array first (through geometryAttribute or
+ * fillAttribute), then call this; every mesh, view and wireframe over the
+ * geometry sees the new bytes, and the other streams are untouched -
+ * which is what a per-frame channel in a stream of its own buys. A
+ * stream-0 update drops the cached bounds and rewrites the same range of
+ * the core's shape, so every node drawing the geometry picks and culls
+ * where it is now drawn: the box follows at the next flush, the triangle
+ * index is rebuilt by the next query (Three's raycast reads the live
+ * attribute the same way; Unity's and Godot's colliders never follow). A
+ * geometry not yet on the GPU has nothing to update: its first acquire
+ * uploads the array as it is then.
+ */
+export function updateVertices(geometry: Geometry, options: UpdateVerticesOptions = {}): void {
+  let streams = geometryStreams(geometry)
+  let index = options.stream ?? 0
+  if (!Number.isInteger(index) || index < 0 || index >= streams.length) {
+    throw new Error("updateVertices: stream " + index + " is out of range; the geometry has streams 0.." + (streams.length - 1))
+  }
+  let total = geometryVertexCount(geometry, "updateVertices")
+  let first = options.first ?? 0
+  let count = options.count ?? total - first
+  if (!Number.isInteger(first) || !Number.isInteger(count) || first < 0 || count < 0 || first + count > total) {
+    throw new Error("updateVertices: range [" + first + ", " + (first + count) + ") is outside the geometry's " + total + " vertices")
+  }
+  if (index === 0) geometry._bounds = undefined
+  let stream = streams[index]!
+  let upload = vertexUploads.get(stream.vertices)
+  if (upload === undefined || count === 0) return
+  let stride = layoutStride(stream.layout)
+  writeBuffer(upload.buffer, vertexBytes(stream.vertices).subarray(first * stride, (first + count) * stride), first * stride)
+  let entry = entries.get(geometry)
+  if (index === 0 && entry !== undefined) {
+    let view = shapeView(geometry)
+    updateShape(entry.shape, view.floats.subarray(first * view.stride, (first + count) * view.stride), view.stride, 0, view.uvAt, first)
+  }
+}
+
+/**
+ * Recompute a triangle geometry's normals in place from its faces
+ * (Three's computeVertexNormals, Unity's RecalculateNormals, Godot's
+ * generate_normals, all in place): each vertex takes the normals of the
+ * faces that name its INDEX, weighted by the corner angle, normalized -
+ * a vertex shared across faces shades smooth, a split one per face, so a
+ * merged or deformed generator geometry comes out right with no options
+ * (except along a uv seam, whose copies each see one side; Three's
+ * artifact too, and withNormals, which matches faces by position, has
+ * none). The math runs in the core in one call over the vertex floats;
+ * only the layout is resolved here. Needs aNormal in float32x3 (or x4):
+ * a packed normal is an authoring format, so pack after withNormals
+ * instead. Returns the stream carrying aNormal, the one updateVertices
+ * re-uploads, which makes the CPU deformation loop `fillAttribute(g,
+ * "aPos", ...)`, `computeVertexNormals(g)`, `updateVertices(g)`. That
+ * loop is for data that genuinely changes on the CPU - a streamed cloud,
+ * a cloth solved in JS, an editor edit. A per-frame ripple, sway or wave
+ * belongs in a vertex shader: displace and derive the normal in the
+ * vertex stage (shaderMaterial) and no per-vertex work touches the CPU
+ * at all. Morph normal deltas are left alone.
+ */
+export function computeVertexNormals(geometry: Geometry): ArrayBufferView {
+  if (geometryTopology(geometry) !== "triangles") throw new Error("computeVertexNormals: needs a triangle geometry, got " + geometryTopology(geometry))
+  let slot = geometrySlot(geometry, "aNormal")
+  if (slot === null) throw new Error("computeVertexNormals: geometry has no aNormal channel; withNormals adds one")
+  if (slot.format !== "float32x3" && slot.format !== "float32x4") {
+    throw new Error("computeVertexNormals: aNormal is " + slot.format + "; a packed normal is an authoring format, compute with withNormals before packing")
+  }
+  geometryVertexCount(geometry, "computeVertexNormals")
+  let { floats, stride } = shapeView(geometry)
+  let target = geometryStreams(geometry)[slot.stream]!
+  let t = target.vertices
+  let normals = new Float32Array(t.buffer, t.byteOffset, t.byteLength / Float32Array.BYTES_PER_ELEMENT)
+  computeNormals(
+    { data: floats, stride, offset: 0 },
+    { data: normals, stride: layoutStride(target.layout) / Float32Array.BYTES_PER_ELEMENT, offset: slot.offset / Float32Array.BYTES_PER_ELEMENT },
+    geometry.indices,
+  )
+  return t
 }