lecodes-gl-lite 2.0.0

package/src/webgl/batching.ts

@@ -0,0 +1,453 @@
+// Instanced batching for the lite engine's scene passes.
+//
+// A level built from a modular kit is thousands of nodes over a few hundred distinct meshes
+// (Twig & Twine's map: 9 441 prefab placements of 152 GLBs → ~57 k drawables). Drawn one OGL Mesh at a
+// time that is 57 k draw calls, each re-uploading every uniform of its program — the frame was
+// 250 ms+ before a single triangle rasterized. Here every drawable that shares (geometry, program,
+// mode, render order, shadow flags, winding) joins ONE batch and the batch draws with
+// `drawElementsInstanced`, the per-instance world matrix coming from an `instanceMatrix` vertex
+// attribute (shaders.ts: the `INSTANCED` define swaps `modelMatrix` for it). The per-node Mesh
+// objects stay exactly as they were — picking, the selection outline, wireframe companions, bounds
+// and the editor all keep reading them — they just stop being drawn one by one.
+//
+// `collect()` walks the OGL graph only when the host says the graph changed (a `graphVersion` the
+// engine bumps on every matrix / parent / visibility / drawable mutation — every one of them goes
+// through the core's backend hooks): the walk fills one instance stream per batch, `all` (every
+// hierarchy-visible instance — the shadow casters), plus the instances' world bounding spheres
+// and the list of singles. Every frame the camera moved, a flat pass over those cached spheres
+// (no graph traversal — 57 k nodes are ~2 ms this way, ~40 ms as a recursive walk) fills `vis`,
+// the camera-visible subset the main pass draws, and culls the singles. A static scene with a
+// still camera does nothing at all. What can't batch — transparent programs (their draw order is
+// depth-sorted per object), skinned meshes (per-mesh bone textures), morph targets (per-node
+// weights), points, particle streams, programs whose vertex shader has no INSTANCED path — is a
+// `single` and draws the way OGL's renderer draws it, in OGL's sort order.
+
+import { Camera, Geometry, GLTFSkin, Mesh, Program, Renderer, Transform, type OGLRenderingContext } from 'ogl'
+import { transformPoint } from '../core/math3d'
+
+type GL = OGLRenderingContext & WebGL2RenderingContext
+
+type Batch = {
+  key: string
+  source: Geometry
+  program: Program
+  /** The instanced twin of `program` (same uniforms object, INSTANCED vertex path). */
+  twin: Program
+  mode: number
+  renderOrder: number
+  castShadows: boolean
+  receiveShadows: boolean
+  /** Mirrored instances (negative world determinant) draw with the front face flipped. */
+  flip: boolean
+  all: Float32Array
+  allCount: number
+  allDirty: boolean
+  geoAll: Geometry
+  /** Per `all` instance: world bounding sphere (cx, cy, cz, r) — the cull pass reads these. */
+  sph: Float32Array
+  vis: Float32Array
+  visCount: number
+  visDirty: boolean
+  geoVis: Geometry
+  /** World AABB of `all` (min xyz, max xyz) — recomputed when `all` changes. */
+  bounds: Float32Array
+  lastUsed: number
+}
+
+const ZERO = { value: 0 }
+const INITIAL_CAPACITY = 16
+/** Frames a batch may sit empty before its GPU buffers go. */
+const IDLE_FRAMES = 600
+
+const maxScaleOnAxis = (m: ArrayLike<number>): number => Math.sqrt(Math.max(
+  m[0] * m[0] + m[1] * m[1] + m[2] * m[2],
+  m[4] * m[4] + m[5] * m[5] + m[6] * m[6],
+  m[8] * m[8] + m[9] * m[9] + m[10] * m[10],
+))
+
+const determinant3 = (m: ArrayLike<number>): number =>
+  m[0] * (m[5] * m[10] - m[6] * m[9]) - m[1] * (m[4] * m[10] - m[6] * m[8]) + m[2] * (m[4] * m[9] - m[5] * m[8])
+
+export type Batcher = ReturnType<typeof createBatcher>
+
+export const createBatcher = (gl: GL, renderer: Renderer) => {
+  const batches = new Map<string, Batch>()
+  /** This frame's camera-visible singles (the main pass). */
+  const singles: Mesh[] = []
+  /** Every hierarchy-visible single (the walk's output; the cull pass filters it into `singles`). */
+  const singlesAll: Mesh[] = []
+  /** The shadow-casting subset of `singlesAll`. */
+  const casterSingles: Mesh[] = []
+  let lastGraph = -1
+  const lastPV = new Float32Array(16)
+  let lastCull = true
+  /** Off = every drawable is a single (the per-mesh path, for A/B checks and debugging). */
+  let enabled = true
+  /** Source program → its instanced twin (null = the vertex shader has no INSTANCED path). */
+  const twins = new Map<Program, Program | null>()
+  let frame = 0
+
+  // ---- instanced program twins ----------------------------------------------------------------
+
+  const twinFor = (src: Program): Program | null => {
+    const known = twins.get(src)
+    if (known !== undefined) return known
+    let twin: Program | null = null
+    const vs = gl.getShaderSource(src.vertexShader)
+    const fs = gl.getShaderSource(src.fragmentShader)
+    if (vs && fs && vs.startsWith('#version')) {
+      // the define goes right after the #version line (the only thing allowed before it)
+      const vertex = vs.replace(/^([^\n]*\n)/, '$1#define INSTANCED\n')
+      const t = new Program(gl, {
+        vertex, fragment: fs, uniforms: src.uniforms,
+        transparent: src.transparent, cullFace: src.cullFace as any, frontFace: src.frontFace,
+        depthTest: src.depthTest, depthWrite: src.depthWrite, depthFunc: src.depthFunc,
+      })
+      let hasInstanceAttr = false
+      t.attributeLocations.forEach((_loc: number, info: { name: string }) => { if (info.name === 'instanceMatrix') hasInstanceAttr = true })
+      if (hasInstanceAttr && gl.getProgramParameter(t.program, gl.LINK_STATUS)) twin = t
+      else t.remove()
+    }
+    twins.set(src, twin)
+    return twin
+  }
+
+  /** The per-draw GL state lives on the source program (the SDK mutates it: depth flags, cull
+   *  mode, blend) — mirror it onto the twin right before the batch draws. */
+  const syncState = (twin: Program, src: Program): void => {
+    twin.transparent = src.transparent
+    twin.cullFace = src.cullFace
+    twin.frontFace = src.frontFace
+    twin.depthTest = src.depthTest
+    twin.depthWrite = src.depthWrite
+    twin.depthFunc = src.depthFunc
+    twin.blendFunc = src.blendFunc
+    twin.blendEquation = src.blendEquation
+  }
+
+  // ---- geometry twins (shared vertex buffers + an instanceMatrix stream) -------------------------
+
+  const makeInstanceGeometry = (source: Geometry, capacity: number): Geometry => {
+    const attrs: Record<string, unknown> = {}
+    for (const [ name, a ] of Object.entries<any>(source.attributes)) {
+      attrs[name] = {
+        size: a.size, data: a.data, type: a.type, normalized: a.normalized,
+        stride: a.stride, offset: a.offset, buffer: a.buffer, count: a.count,
+      }
+    }
+    attrs.instanceMatrix = { instanced: 1, size: 16, data: new Float32Array(capacity * 16), usage: gl.DYNAMIC_DRAW }
+    const g = new Geometry(gl, attrs as any)
+    g.drawRange.start = source.drawRange.start
+    g.drawRange.count = source.drawRange.count
+    return g
+  }
+
+  const disposeInstanceGeometry = (g: Geometry): void => {
+    // ONLY the instance stream and the VAOs are ours — every other buffer belongs to the source
+    for (const vao of Object.values(g.VAOs)) renderer.deleteVertexArray(vao as WebGLVertexArrayObject)
+    g.VAOs = {}
+    const attr = (g.attributes as any).instanceMatrix
+    if (attr?.buffer) { gl.deleteBuffer(attr.buffer); attr.buffer = null }
+    ;(renderer as any).currentGeometry = null
+  }
+
+  /** Grow the instance stream to hold `needed` matrices (the VAOs re-bind on the next draw). */
+  const growInstanceGeometry = (g: Geometry, needed: number): Float32Array => {
+    const attr = (g.attributes as any).instanceMatrix
+    let capacity = Math.max(INITIAL_CAPACITY, attr.count)
+    while (capacity < needed) capacity *= 2
+    const data = new Float32Array(capacity * 16)
+    data.set(attr.data)
+    disposeInstanceGeometry(g)
+    g.instancedCount = 0
+    g.addAttribute('instanceMatrix', { instanced: 1, size: 16, data, usage: gl.DYNAMIC_DRAW } as any)
+    return data
+  }
+
+  const upload = (g: Geometry, data: Float32Array, count: number): void => {
+    const attr = (g.attributes as any).instanceMatrix
+    if (count > 0) {
+      gl.bindBuffer(gl.ARRAY_BUFFER, attr.buffer)
+      ;(renderer.state as any).boundBuffer = attr.buffer
+      gl.bufferSubData(gl.ARRAY_BUFFER, 0, data, 0, count * 16)
+    }
+    g.setInstancedCount(count)
+  }
+
+  // ---- batches ------------------------------------------------------------------------------------
+
+  const batchFor = (node: any, twin: Program, flip: boolean): Batch => {
+    const program: Program = node.program
+    const cast = node._castShadows !== false
+    const receive = node._receiveShadows !== false
+    const key = `${node.geometry.id}|${(program as any).id}|${node.mode}|${node.renderOrder}|${cast ? 1 : 0}${receive ? 1 : 0}${flip ? 1 : 0}`
+    let b = batches.get(key)
+    if (!b) {
+      const source: Geometry = node.geometry
+      b = {
+        key, source, program, twin, mode: node.mode, renderOrder: node.renderOrder,
+        castShadows: cast, receiveShadows: receive, flip,
+        all: new Float32Array(INITIAL_CAPACITY * 16), allCount: 0, allDirty: true,
+        geoAll: makeInstanceGeometry(source, INITIAL_CAPACITY),
+        sph: new Float32Array(INITIAL_CAPACITY * 4),
+        vis: new Float32Array(INITIAL_CAPACITY * 16), visCount: 0, visDirty: true,
+        geoVis: makeInstanceGeometry(source, INITIAL_CAPACITY),
+        bounds: new Float32Array(6),
+        lastUsed: frame,
+      }
+      batches.set(key, b)
+    }
+    return b
+  }
+
+  /** Why a drawable can't join a batch — see the header. */
+  const batchable = (node: any): Program | null => {
+    if (!enabled) return null
+    if (node instanceof GLTFSkin || node._particles || node.mode === gl.POINTS) return null
+    const program: Program = node.program
+    if (program.transparent || !program.depthTest) return null
+    if (!node.geometry?.attributes?.position || node.geometry.isInstanced) return null
+    if ((program.uniforms as any).uMorphTex) return null
+    return twinFor(program)
+  }
+
+  const bounds = (node: any): { center: { x: number, y: number, z: number }, radius: number, min: any, max: any } | null => {
+    const g = node.geometry
+    if (!g.bounds || g.bounds.radius === Infinity) g.computeBoundingSphere()
+    return g.bounds && isFinite(g.bounds.radius) ? g.bounds : null
+  }
+
+  const sphereInFrustum = (camera: Camera, cx: number, cy: number, cz: number, r: number): boolean => {
+    const planes = camera.frustum as unknown as (ArrayLike<number> & { constant: number })[]
+    for (let i = 0; i < 6; i++) {
+      const p = planes[i]
+      if (p[0] * cx + p[1] * cy + p[2] * cz + p.constant < -r) return false
+    }
+    return true
+  }
+
+  /** Write matrix `w` at instance slot `i` of `data`; true when any value changed. */
+  const writeMatrix = (data: Float32Array, i: number, w: ArrayLike<number>): boolean => {
+    const o = i * 16
+    let changed = false
+    for (let k = 0; k < 16; k++) {
+      const v = w[k]
+      if (data[o + k] !== v) { data[o + k] = v; changed = true }
+    }
+    return changed
+  }
+
+  /** World AABB over a batch's `all` instances × its geometry's local AABB (8 corners each). */
+  const computeBounds = (b: Batch): void => {
+    const g = b.source
+    if (!g.bounds) g.computeBoundingBox()
+    const out = b.bounds
+    out[0] = out[1] = out[2] = Infinity; out[3] = out[4] = out[5] = -Infinity
+    if (!g.bounds || !isFinite(g.bounds.min.x)) return
+    const { min, max } = g.bounds
+    const corner = [ 0, 0, 0 ]
+    for (let i = 0; i < b.allCount; i++) {
+      const w = b.all.subarray(i * 16, i * 16 + 16)
+      for (let c = 0; c < 8; c++) {
+        transformPoint(corner, w, c & 1 ? max.x : min.x, c & 2 ? max.y : min.y, c & 4 ? max.z : min.z, 1)
+        for (let k = 0; k < 3; k++) {
+          if (corner[k] < out[k]) out[k] = corner[k]
+          if (corner[k] > out[k + 3]) out[k + 3] = corner[k]
+        }
+      }
+    }
+  }
+
+  // ---- the per-frame walk -------------------------------------------------------------------------
+
+  const centre = [ 0, 0, 0 ]
+
+  /** The graph walk (world matrices must be current): rebuild every batch's `all` stream + spheres
+   *  and the singles lists. Runs only when the graph version moved. */
+  const walk = (root: Transform): void => {
+    frame++
+    singlesAll.length = 0
+    casterSingles.length = 0
+    for (const b of batches.values()) b.allCount = 0
+    root.traverse((node: any) => {
+      if (!node.visible) return true
+      if (!node.draw) return false
+      const w = node.worldMatrix
+      const twin = batchable(node)
+      if (!twin) {
+        singlesAll.push(node)
+        if (node._castShadows !== false) casterSingles.push(node)
+        return false
+      }
+      const flip = !!node.program.cullFace && determinant3(w) < 0
+      const b = batchFor(node, twin, flip)
+      b.lastUsed = frame
+      const i = b.allCount
+      if (i * 16 >= b.all.length) {
+        b.all = growInstanceGeometry(b.geoAll, i + 1)
+        const sph = new Float32Array(b.all.length / 4)
+        sph.set(b.sph)
+        b.sph = sph
+      }
+      if (writeMatrix(b.all, i, w)) b.allDirty = true
+      const bnd = bounds(node)
+      const o = i * 4
+      if (bnd && node.frustumCulled) {
+        transformPoint(centre, w, bnd.center.x, bnd.center.y, bnd.center.z, 1)
+        b.sph[o] = centre[0]; b.sph[o + 1] = centre[1]; b.sph[o + 2] = centre[2]
+        b.sph[o + 3] = bnd.radius * maxScaleOnAxis(w)
+      } else {
+        b.sph[o + 3] = -1   // never culled (frustumCulled off, or no bounds to test)
+      }
+      b.allCount++
+      return false
+    })
+    for (const [ key, b ] of batches) {
+      if (b.allCount !== b.geoAll.instancedCount) b.allDirty = true
+      if (b.allDirty) { upload(b.geoAll, b.all, b.allCount); computeBounds(b); b.allDirty = false }
+      if (b.allCount === 0 && frame - b.lastUsed > IDLE_FRAMES) {
+        disposeInstanceGeometry(b.geoAll)
+        disposeInstanceGeometry(b.geoVis)
+        batches.delete(key)
+      }
+    }
+  }
+
+  /** The cull pass: `all` → `vis` per batch from the cached spheres, `singlesAll` → `singles`.
+   *  `cull` off copies everything through (a drawable with `frustumCulled = false` always
+   *  passes, as in OGL). */
+  const cullPass = (camera: Camera, cull: boolean): void => {
+    camera.updateFrustum()
+    for (const b of batches.values()) {
+      b.visCount = 0
+      const n = b.allCount
+      for (let i = 0; i < n; i++) {
+        const o = i * 4
+        if (cull && b.sph[o + 3] >= 0 && !sphereInFrustum(camera, b.sph[o], b.sph[o + 1], b.sph[o + 2], b.sph[o + 3])) continue
+        const v = b.visCount
+        if (v * 16 >= b.vis.length) b.vis = growInstanceGeometry(b.geoVis, v + 1)
+        const src = i * 16, dst = v * 16
+        for (let k = 0; k < 16; k++) {
+          const x = b.all[src + k]
+          if (b.vis[dst + k] !== x) { b.vis[dst + k] = x; b.visDirty = true }
+        }
+        b.visCount++
+      }
+      if (b.visCount !== b.geoVis.instancedCount) b.visDirty = true
+      if (b.visDirty) { upload(b.geoVis, b.vis, b.visCount); b.visDirty = false }
+    }
+    singles.length = 0
+    for (const node of singlesAll) {
+      if (cull && node.frustumCulled && !camera.frustumIntersectsMesh(node)) continue
+      singles.push(node)
+    }
+  }
+
+  /** Refresh the frame's draw lists. `graphVersion` = the engine's mutation counter (a change
+   *  re-walks the graph); the camera moving re-culls; otherwise nothing happens. `force` re-walks
+   *  regardless (a caller that changed drawables behind the counter's back). */
+  const collect = (root: Transform, camera: Camera, cull: boolean, graphVersion = -2, force = false): void => {
+    const graphChanged = force || graphVersion !== lastGraph
+    if (graphChanged) { walk(root); lastGraph = graphVersion }
+    camera.updateMatrixWorld()
+    const pv = camera.projectionViewMatrix as unknown as ArrayLike<number>
+    let camChanged = cull !== lastCull
+    for (let k = 0; k < 16 && !camChanged; k++) if (lastPV[k] !== pv[k]) camChanged = true
+    if (!graphChanged && !camChanged) return
+    cullPass(camera, cull)
+    for (let k = 0; k < 16; k++) lastPV[k] = pv[k]
+    lastCull = cull
+  }
+
+  // ---- draws ------------------------------------------------------------------------------------
+
+  const sortedBatches = (): Batch[] => [ ...batches.values() ].sort((a, b) => a.renderOrder - b.renderOrder)
+
+  /** The main pass: batches (all opaque) in render-order, then the singles in OGL's order —
+   *  opaque front-to-back, transparent back-to-front, depth-test-off last. `shadowEnabled` is the
+   *  scene's live { value } slot; batches that don't receive shadows draw with it forced off (the
+   *  same swap wireReceiveShadows does per single). */
+  const drawMain = (camera: Camera, shadowEnabled: { value: number }): void => {
+    for (const b of sortedBatches()) {
+      if (b.visCount === 0) continue
+      const u = b.twin.uniforms as Record<string, { value: unknown }>
+      ;(u.projectionMatrix ??= { value: null }).value = camera.projectionMatrix
+      ;(u.viewMatrix ??= { value: null }).value = camera.viewMatrix
+      ;(u.cameraPosition ??= { value: null }).value = camera.worldPosition
+      // the uniforms object is the source program's too — swap the slot for this draw only, so
+      // a single drawn later through the same program still sees the scene's live value
+      const prevShadow = u.shadowEnabled
+      if (prevShadow) u.shadowEnabled = b.receiveShadows ? shadowEnabled : ZERO
+      syncState(b.twin, b.program)
+      b.twin.use({ flipFaces: b.flip })
+      b.geoVis.draw({ mode: b.mode, program: b.twin })
+      if (prevShadow) u.shadowEnabled = prevShadow
+    }
+
+    const opaque: Mesh[] = [], transparent: Mesh[] = [], ui: Mesh[] = []
+    const pv = camera.projectionViewMatrix as unknown as ArrayLike<number>
+    for (const node of singles as any[]) {
+      if (!node.program.transparent) opaque.push(node)
+      else if (node.program.depthTest) transparent.push(node)
+      else ui.push(node)
+      node.zDepth = 0
+      if (node.renderOrder !== 0 || !node.program.depthTest) continue
+      const w = node.worldMatrix
+      const x = w[12], y = w[13], z = w[14]
+      const cw = pv[3] * x + pv[7] * y + pv[11] * z + pv[15] || 1
+      node.zDepth = (pv[2] * x + pv[6] * y + pv[10] * z + pv[14]) / cw
+    }
+    ;(opaque as any[]).sort(renderer.sortOpaque)
+    ;(transparent as any[]).sort(renderer.sortTransparent)
+    ;(ui as any[]).sort(renderer.sortUI)
+    for (const node of opaque) node.draw({ camera })
+    for (const node of transparent) node.draw({ camera })
+    for (const node of ui) node.draw({ camera })
+  }
+
+  /** The shadow pass for the batches: every `all` instance of every casting batch through the
+   *  instanced depth program (`shadowViewProjection` already set by the caller). */
+  const drawShadow = (depthInstanced: Program): void => {
+    for (const b of batches.values()) {
+      if (!b.castShadows || b.allCount === 0) continue
+      depthInstanced.use({ flipFaces: b.flip })
+      b.geoAll.draw({ mode: b.mode, program: depthInstanced })
+    }
+  }
+
+  /** Extend `min`/`max` by the world AABB of every casting batch (cached per batch). */
+  const casterBounds = (min: number[], max: number[]): void => {
+    for (const b of batches.values()) {
+      if (!b.castShadows || b.allCount === 0 || !isFinite(b.bounds[0])) continue
+      for (let k = 0; k < 3; k++) {
+        if (b.bounds[k] < min[k]) min[k] = b.bounds[k]
+        if (b.bounds[k + 3] > max[k]) max[k] = b.bounds[k + 3]
+      }
+    }
+  }
+
+  const dispose = (): void => {
+    for (const b of batches.values()) { disposeInstanceGeometry(b.geoAll); disposeInstanceGeometry(b.geoVis) }
+    batches.clear()
+    for (const t of twins.values()) t?.remove()
+    twins.clear()
+  }
+
+  /** Whether a drawable is drawn through a batch (so a caller enumerating singles skips it). */
+  const isBatched = (node: Mesh): boolean => batchable(node) !== null
+
+  return {
+    collect, drawMain, drawShadow, casterBounds, isBatched, dispose,
+    setEnabled: (v: boolean): void => { enabled = v; lastGraph = -1 },
+    /** This frame's individually drawn meshes (after `collect`). */
+    singles,
+    /** The hierarchy-visible singles that cast shadows (every one, not only the camera-visible). */
+    casterSingles,
+    /** Diagnostics: batch count / instance totals. */
+    stats: () => {
+      let all = 0, vis = 0, n = 0
+      for (const b of batches.values()) if (b.allCount > 0) { n++; all += b.allCount; vis += b.visCount }
+      return { batches: n, instances: all, visible: vis, singles: singles.length }
+    },
+  }
+}