@solidrt/3d 0.0.58 → 0.0.59

package/src/profile.ts

@@ -2,14 +2,11 @@
 // Profile is a closed simple polygon in the XY plane - bare [x, y] tuples
 // are sharp (creased) corners, tagged { p, smooth } points shade round -
 // and winding is normalized to CCW on use, so either authoring direction
-// works. fillet() and roundRect() produce smooth-tagged arc corners,
-// shape() fills a profile as a flat +z face in the shared vertex layout,
-// and triangulate() (the ear-clipping core behind every cap) is exported
-// for custom flat work. The swept-solid generators consuming this
-// vocabulary - extrude, lathe, sweep, tube - live in sweep.ts.
+// works. fillet() and roundRect() produce smooth-tagged arc corners, and
+// triangulate() (the ear-clipping core behind every cap) is exported for
+// custom flat work. The generators consuming this vocabulary - polygon,
+// extrude, lathe, sweep, tube - live in sweep.ts.
 
-import { packGeometry } from "./geometry.ts"
-import type { Geometry, GeometryOptions } from "./geometry.ts"
 import type { Vec2 } from "./math.ts"
 
 /** A profile point: `p` in profile space, `smooth` to share an averaged
@@ -291,21 +288,3 @@ export function roundRect(
   let corners: Vec2[] = [[-x, -y], [x, -y], [x, y], [-x, y]]
   return fillet(corners, radius, segments)
 }
-
-/**
- * The profile filled as a flat face in the XY plane facing +z - the
- * general case of circle()/ring() for arbitrary outlines. UVs map the
- * profile's bounding box to the unit square like plane(); rotate flat the
- * same way: `rotation={[-Math.PI / 2, 0, 0]}`.
- */
-export function shape(profile: Profile, options: GeometryOptions = {}): Geometry {
-  let pts = normalizeProfile(profile)
-  let { minX, maxY, w, h } = profileBounds(pts)
-  let px = pts.map((p) => p.x)
-  let py = pts.map((p) => p.y)
-  let verts: number[] = []
-  for (let p of pts) {
-    verts.push(p.x, p.y, 0, 0, 0, 1, (p.x - minX) / w, (maxY - p.y) / h)
-  }
-  return packGeometry(verts, earClip(px, py), options)
-}

package/src/resolve.ts

@@ -0,0 +1,181 @@
+// A target's RESOLVE: the rgba8 draw target the app displays, holding one
+// covering-triangle entry that samples the buffer as `uScene` and writes
+// display pixels (exposure, tone mapping, the encode - the RESOLVE set in
+// glsl.ts). An ordinary auto target: it re-renders exactly when the buffer
+// does, so a static scene still costs zero passes. The pipeline and
+// program are the target's own (a custom source recompiles them). The
+// stock bloom hangs on it: a chain of shader textures over the buffer
+// (threshold, then blur across and down per round) at a fraction of the
+// target's size, bound on the resolve target as `uBloom`.
+import { addDraw, createDrawTarget, createShaderTexture, createTexture, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, setDrawTextures, setTargetParams, setTargetSize, setTargetTextures } from "@solidrt/core/gpu"
+import type { DrawId, FilterMode, ProgramId, RenderPipelineId, TextureBindings, TextureId, WrapMode } from "@solidrt/core/gpu"
+import { BLOOM_BLUR, BLOOM_RESOLVE, BLOOM_THRESHOLD, DEFAULT_RESOLVE } from "./glsl.ts"
+import { resolvePipeline } from "./material.ts"
+
+/** A custom resolve (SceneOptions.resolve, scene.setResolve): the fragment
+ * source and the extra textures it declares (a chain's result), bound
+ * beside `uScene`. */
+export type ResolveOptions = { source: string; textures?: TextureBindings }
+/** What the `resolve` option takes: a source, ResolveOptions, or a
+ * function of the buffer id (`hdrTexture`) returning either - the form
+ * that builds a chain over the buffer before the resolve is made. */
+export type ResolveInput = string | ResolveOptions | ((hdr: TextureId) => string | ResolveOptions)
+
+/** The stock bloom (SceneOptions.bloom, scene.setBloom): radiance above
+ * `threshold` (default 1: what a white surface lit to 1 reaches, so only
+ * brighter blooms) is blurred over `radius` rounds (default 2) of a
+ * separable blur at a quarter of the target's size and added back with
+ * `intensity` (default 0.5). Three's UnrealBloomPass strength / radius /
+ * threshold, Unity's Bloom threshold / intensity / scatter, Godot's glow. */
+export type BloomOptions = { threshold?: number; intensity?: number; radius?: number }
+
+// The bloom defaults: only radiance above a fully lit white surface
+// blooms, at half weight, blurred over two rounds.
+const BLOOM_THRESHOLD_DEFAULT = 1
+const BLOOM_INTENSITY_DEFAULT = 0.5
+const BLOOM_RADIUS_DEFAULT = 2
+// The chain renders at this fraction of the target on each axis: a blur
+// is low-frequency, and a coarse chain is what makes a 9-tap kernel wide
+// on screen.
+const BLOOM_SCALE = 4
+
+type Bloom = {
+  threshold: TextureId
+  blurs: TextureId[]
+  radius: number
+}
+
+export type ResolveRecord = {
+  target: TextureId
+  entry: DrawId
+  pipeline: RenderPipelineId
+  program: ProgramId
+  source: string
+  /** Whether the app gave the source (then bloom never swaps it). */
+  custom: boolean
+  textures: TextureBindings | undefined
+  bloom: Bloom | null
+  /** What `uBloom` binds while bloom is off (a target binding cannot be
+   * removed, and the chain it named is destroyed): a 1x1 black texture,
+   * made at the first switch. */
+  placeholder: TextureId | null
+  label: string
+}
+
+function resolveSource(r: ResolveInput | undefined, buffer: TextureId): ResolveOptions {
+  if (r === undefined) return { source: DEFAULT_RESOLVE }
+  if (typeof r === "function") r = r(buffer)
+  return typeof r === "string" ? { source: r } : r
+}
+
+export function makeResolve(
+  buffer: TextureId,
+  width: number,
+  height: number,
+  r: ResolveInput | undefined,
+  sampler: { filter?: FilterMode; wrap?: WrapMode },
+  label: string,
+): ResolveRecord {
+  let o = resolveSource(r, buffer)
+  let built = resolvePipeline(o.source, label + "-resolve")
+  let target = createDrawTarget(width, height, null, { filter: sampler.filter, wrap: sampler.wrap, label: label + "-resolve", autoFree: false })
+  let entry = addDraw(target, built.pipeline, null, { vertexCount: 3, textures: { ...o.textures, uScene: buffer } })
+  return { target, entry, pipeline: built.pipeline, program: built.program, source: o.source, custom: r !== undefined, textures: o.textures, bloom: null, placeholder: null, label }
+}
+
+// Swap the entry's program for `source`, keeping the bindings.
+function recompile(rec: ResolveRecord, buffer: TextureId, source: string): void {
+  let built = resolvePipeline(source, rec.label + "-resolve")
+  removeDraw(rec.target, rec.entry)
+  destroyRenderPipeline(rec.pipeline)
+  destroyProgram(rec.program)
+  rec.entry = addDraw(rec.target, built.pipeline, null, { vertexCount: 3, textures: { ...rec.textures, uScene: buffer } })
+  rec.pipeline = built.pipeline
+  rec.program = built.program
+  rec.source = source
+}
+
+export function replaceResolve(rec: ResolveRecord, buffer: TextureId, r: ResolveInput): void {
+  let o = resolveSource(r, buffer)
+  rec.custom = true
+  rec.textures = o.textures
+  if (o.source === rec.source) {
+    setDrawTextures(rec.target, rec.entry, { ...o.textures, uScene: buffer })
+    return
+  }
+  recompile(rec, buffer, o.source)
+}
+
+function chainSize(size: number): number {
+  return Math.max(1, Math.round(size / BLOOM_SCALE))
+}
+
+function makeChain(rec: ResolveRecord, buffer: TextureId, width: number, height: number, threshold: number, radius: number): Bloom {
+  let w = chainSize(width)
+  let h = chainSize(height)
+  let label = rec.label + "-bloom"
+  let first = createShaderTexture(BLOOM_THRESHOLD, w, h, { uThreshold: threshold }, { textures: { uSource: buffer }, label: label + "-threshold", autoFree: false })
+  let blurs: TextureId[] = []
+  let source = first
+  for (let i = 0; i < radius; i++) {
+    source = createShaderTexture(BLOOM_BLUR, w, h, { uDir: [1, 0] }, { textures: { uSource: source }, label: label + "-x", autoFree: false })
+    blurs.push(source)
+    source = createShaderTexture(BLOOM_BLUR, w, h, { uDir: [0, 1] }, { textures: { uSource: source }, label: label + "-y", autoFree: false })
+    blurs.push(source)
+  }
+  return { threshold: first, blurs, radius }
+}
+
+function destroyChain(bloom: Bloom): void {
+  for (let t of bloom.blurs) destroyTexture(t)
+  destroyTexture(bloom.threshold)
+}
+
+/** Switch the stock bloom on (options) or off (null) on a resolve. */
+export function setResolveBloom(rec: ResolveRecord, buffer: TextureId, width: number, height: number, opts: BloomOptions | null): void {
+  if (opts === null) {
+    if (rec.bloom === null) return
+    if (rec.placeholder === null) rec.placeholder = createTexture(new Uint8Array([0, 0, 0, 255]), 1, 1, { label: rec.label + "-bloom-none", autoFree: false })
+    setTargetTextures(rec.target, { uBloom: rec.placeholder })
+    setTargetParams(rec.target, { uBloomIntensity: 0 })
+    destroyChain(rec.bloom)
+    rec.bloom = null
+    if (!rec.custom) recompile(rec, buffer, DEFAULT_RESOLVE)
+    return
+  }
+  let threshold = opts.threshold ?? BLOOM_THRESHOLD_DEFAULT
+  let intensity = opts.intensity ?? BLOOM_INTENSITY_DEFAULT
+  let radius = opts.radius ?? BLOOM_RADIUS_DEFAULT
+  if (!Number.isFinite(threshold) || threshold < 0) throw new Error("bloom: threshold must be a finite number >= 0, got " + threshold)
+  if (!Number.isFinite(intensity) || intensity < 0) throw new Error("bloom: intensity must be a finite number >= 0, got " + intensity)
+  if (!Number.isInteger(radius) || radius < 1) throw new Error("bloom: radius must be a positive integer (blur rounds), got " + radius)
+  if (rec.bloom !== null && rec.bloom.radius !== radius) {
+    destroyChain(rec.bloom)
+    rec.bloom = null
+  }
+  if (rec.bloom === null) {
+    rec.bloom = makeChain(rec, buffer, width, height, threshold, radius)
+    setTargetTextures(rec.target, { uBloom: rec.bloom.blurs[rec.bloom.blurs.length - 1]! })
+  } else {
+    setTargetParams(rec.bloom.threshold, { uThreshold: threshold })
+  }
+  setTargetParams(rec.target, { uBloomIntensity: intensity })
+  if (!rec.custom && rec.source !== BLOOM_RESOLVE) recompile(rec, buffer, BLOOM_RESOLVE)
+}
+
+export function resizeResolve(rec: ResolveRecord, width: number, height: number): void {
+  setTargetSize(rec.target, width, height)
+  if (rec.bloom === null) return
+  let w = chainSize(width)
+  let h = chainSize(height)
+  setTargetSize(rec.bloom.threshold, w, h)
+  for (let t of rec.bloom.blurs) setTargetSize(t, w, h)
+}
+
+export function disposeResolve(rec: ResolveRecord): void {
+  if (rec.bloom !== null) destroyChain(rec.bloom)
+  destroyTexture(rec.target)
+  if (rec.placeholder !== null) destroyTexture(rec.placeholder)
+  destroyRenderPipeline(rec.pipeline)
+  destroyProgram(rec.program)
+}

package/src/scene-shadows.ts

@@ -11,7 +11,7 @@ import { createDrawTarget, depthTexture, destroyTexture, limits, setTargetRect,
 import type { ShaderParams, TextureId } from "@solidrt/core/gpu"
 import { cascadeSplit, copy, frustumSliceSphere, lookAt as lookAtMatrix, mat4, snapToGrid, transformVector } from "./math.ts"
 import type { Mat4, Vec3 } from "./math.ts"
-import { MAX_SHADOW_MAPS } from "./glsl.ts"
+import { MAX_LIGHTS, MAX_SHADOW_MAPS } from "./glsl.ts"
 import { shadowDepthMaterial } from "./material.ts"
 import type { Material } from "./material.ts"
 import { updateCamera } from "./camera.ts"
@@ -113,14 +113,22 @@ export type ShadowSystem = {
    * uShadow*[i] slot): every non-hemisphere light counts, casting or
    * not, so it matches the lit loop's index. */
   forEachShadowSlot(fn: (slot: number, lightIndex: number, cascade: number, rect: ShadowRect) => void): void
-  /** The light started casting (attach, or castShadow flipped on). */
-  createShadow(light: CastingLight): void
-  /** The light stopped casting (detach, or castShadow flipped off).
-   * Safe when it never cast. */
-  destroyShadow(light: CastingLight): void
-  /** The light's castShadow/shadow options changed: rebuild, re-place or
-   * re-fit whatever the change touches (SceneHooks._shadowChanged). */
-  shadowChanged(light: CastingLight): void
+  /** The light attached, detached, or its castShadow/shadow options
+   * changed: the shadow set settles at the next sync (`settle`), never
+   * here. A declarative swap attaches the incoming branch before the
+   * outgoing one detaches, inside one flush, so a budget summed at attach
+   * counts both. Safe for a light that never cast. */
+  invalidate(light: CastingLight): void
+  /** Settle the shadow set against the light list, early in the scene's
+   * sync: drop the shadows of lights that left, stopped casting or
+   * changed shape (cascade count), place every wanted caster's tiles in
+   * attach order while the budget holds (first fit: a later spot still
+   * gets its map when an earlier point light does not), create the views
+   * of new casters. A set past the budget returns the error for the sync
+   * to throw AFTER its own writes, so a failing set never leaves the
+   * scene half-written: the casters that fit keep their maps, the rest
+   * light the scene unshadowed. Reported once per change of the set. */
+  settle(): Error | null
   /** Re-place every caster's map cameras from its light's current world
    * matrix (each compares against the matrix it was last placed from, so
    * a scene animating elsewhere rewrites nothing). Run per sync;
@@ -184,37 +192,88 @@ export function makeShadowSystem<V extends ShadowView>(deps: ShadowSystemDeps<V>
   let forEachShadowSlot = (fn: (slot: number, lightIndex: number, cascade: number, rect: ShadowRect) => void): void => {
     eachSlot((slot, i, shadow, c) => fn(slot, i, c, shadow.rects[c]!))
   }
-  // Place every shadow tile for the current caster set plus `adding` (not
-  // yet in `shadows`; its rects are returned for the view creates), in
-  // light order, a light's cascades consecutive. Sizes the atlas, moves
-  // tiles whose place changed, and drops the atlas when nothing casts.
-  // The rects reach receivers through the next light rewrite.
-  let placeShadows = (adding: CastingLight | null): ShadowRect[] | null => {
+  // The set changed (attach, detach, options) since the last settle.
+  let setDirty = false
+  let invalidate = (light: CastingLight) => {
+    // An option that moves no tile (near, the box camera) still
+    // re-places the map cameras.
+    let shadow = shadows.get(light)
+    if (shadow !== undefined) shadow.dirty = true
+    setDirty = true
+    deps.schedule()
+  }
+  // A caster's views: one square tile of the shadow atlas per map,
+  // drawing the casting meshes with the depth override from that map's
+  // frustum. The light rewrite writes the rects in the light's slots on
+  // every receiving target.
+  let createShadow = (light: CastingLight, rects: ShadowRect[]) => {
+    let atlas = shadowAtlas!
+    let views = rects.map(rect =>
+      deps.makeView(
+        {
+          width: rect.width,
+          height: rect.height,
+          into: atlas.texture,
+          x: rect.x,
+          y: rect.y,
+          overrideMaterial: shadowDepthMaterial(),
+          clearColor: [1, 1, 1, 1],
+          label: deps.label + "-shadow",
+        },
+        m => m.castShadow,
+      ),
+    )
+    shadows.set(light, { light, views, lastWorld: mat4(), dirty: true, rects })
+  }
+  // Settle the set (ShadowSystem.settle): the wanted casters in light
+  // order, as many as fit, then the atlas sized to them, tiles whose
+  // place changed moved, new casters' views made. The rects reach
+  // receivers through the light rewrite this marks.
+  let settle = (): Error | null => {
+    if (!setDirty) return null
+    setDirty = false
+    // Every casting light within the light cap (one past it is not lit,
+    // and its slots would name a uShadow*[i] that does not exist) whose
+    // tiles still fit the budget.
     let casters: CastingLight[] = []
+    let tiles = 0
+    let wanted = 0
+    let index = 0
     for (let l of deps.lights) {
-      if (l.type !== "hemisphere" && (shadows.has(l) || l === adding)) casters.push(l)
+      if (l.type === "hemisphere") continue
+      let i = index++
+      if (!l.castShadow || i >= MAX_LIGHTS) continue
+      let n = shadowTiles(l)
+      wanted += n
+      if (tiles + n > MAX_SHADOW_MAPS) continue
+      casters.push(l)
+      tiles += n
+    }
+    // A shadow no longer wanted (its light left, stopped casting or fell
+    // past the budget) or of the wrong shape (a cascade count change is a
+    // different view set) goes; its light draws plain.
+    for (let [light, shadow] of shadows) {
+      if (casters.includes(light) && shadow.views.length === shadowTiles(light)) continue
+      shadows.delete(light)
+      for (let v of shadow.views) deps.disposeView(v)
     }
-    if (adding !== null && !casters.includes(adding)) casters.push(adding)
     deps.markLightsDirty()
+    let error =
+      wanted > MAX_SHADOW_MAPS
+        ? new Error(
+            "The scene's shadow set is full: " + wanted + " maps over the " + MAX_SHADOW_MAPS +
+              "-slot budget, the casters that do not fit light the scene unshadowed (a cascaded light claims shadow.cascades slots, a point light six)",
+          )
+        : null
     if (casters.length === 0) {
       if (shadowAtlas !== null) {
         destroyTexture(shadowAtlas.texture)
         shadowAtlas = null
       }
-      return null
+      return error
     }
     let maxSize = 1
-    let tiles = 0
-    for (let l of casters) {
-      maxSize = Math.max(maxSize, l.shadow.mapSize)
-      tiles += shadowTiles(l)
-    }
-    if (tiles > MAX_SHADOW_MAPS) {
-      throw new Error(
-        "The scene's shadow set is full: " + tiles + " maps over the " + MAX_SHADOW_MAPS +
-          "-slot budget (a cascaded light claims shadow.cascades slots, a point light six)",
-      )
-    }
+    for (let l of casters) maxSize = Math.max(maxSize, l.shadow.mapSize)
     let lay = shadowLayout(tiles, maxSize)
     if (shadowAtlas === null) {
       shadowAtlas = {
@@ -232,16 +291,15 @@ export function makeShadowSystem<V extends ShadowView>(deps: ShadowSystemDeps<V>
       shadowAtlas.width = lay.width
       shadowAtlas.height = lay.height
     }
-    let placed: ShadowRect[] | null = null
     let k = 0
     for (let l of casters) {
       let size = Math.max(1, Math.floor(l.shadow.mapSize * lay.scale))
       let shadow = shadows.get(l)
+      let fresh: ShadowRect[] = []
       for (let c = 0; c < shadowTiles(l); c++, k++) {
         let rect: ShadowRect = { x: (k % lay.cols) * lay.cell, y: Math.floor(k / lay.cols) * lay.cell, width: size, height: size }
         if (shadow === undefined) {
-          if (placed === null) placed = []
-          placed.push(rect)
+          fresh.push(rect)
           continue
         }
         let r = shadow.rects[c]!
@@ -254,43 +312,9 @@ export function makeShadowSystem<V extends ShadowView>(deps: ShadowSystemDeps<V>
         // A tile's texel size moved: the cascade fit snaps to it.
         shadow.dirty = true
       }
+      if (shadow === undefined) createShadow(l, fresh)
     }
-    return placed
-  }
-  // A shadow's views: one square tile of the shadow atlas per map drawing
-  // the casting meshes with the depth override from that map's frustum.
-  // The light rewrite writes the rects in the light's slots on every
-  // receiving target.
-  let createShadow = (light: CastingLight) => {
-    let rects = placeShadows(light)
-    if (rects === null || shadowAtlas === null) return
-    let atlas = shadowAtlas
-    let views = rects.map(rect =>
-      deps.makeView(
-        {
-          width: rect.width,
-          height: rect.height,
-          into: atlas.texture,
-          x: rect.x,
-          y: rect.y,
-          overrideMaterial: shadowDepthMaterial(),
-          clearColor: [1, 1, 1, 1],
-          label: deps.label + "-shadow",
-        },
-        m => m.castShadow,
-      ),
-    )
-    shadows.set(light, { light, views, lastWorld: mat4(), dirty: true, rects })
-    deps.markLightsDirty()
-  }
-  let destroyShadow = (light: CastingLight) => {
-    let shadow = shadows.get(light)
-    if (shadow === undefined) return
-    shadows.delete(light)
-    for (let v of shadow.views) deps.disposeView(v)
-    placeShadows(null)
-    deps.markLightsDirty()
-    deps.schedule()
+    return error
   }
   // Place a shadow's cameras from its light's world matrix. A box light:
   // at its world position, looking along its world direction, the light
@@ -407,31 +431,8 @@ export function makeShadowSystem<V extends ShadowView>(deps: ShadowSystemDeps<V>
   return {
     atlas: () => shadowAtlas,
     forEachShadowSlot,
-    createShadow,
-    destroyShadow,
-    shadowChanged(light) {
-      let shadow = shadows.get(light)
-      if (shadow !== undefined) {
-        if (!light.castShadow) {
-          destroyShadow(light)
-          return
-        }
-        // A cascade count change is a different view set: rebuild it. A
-        // mapSize change re-places every tile (the grid cell follows the
-        // largest map).
-        if (shadow.views.length !== shadowTiles(light)) {
-          destroyShadow(light)
-          createShadow(light)
-          return
-        }
-        placeShadows(null)
-        shadow.dirty = true
-        deps.markLightsDirty()
-        deps.schedule()
-      } else if (light.castShadow) {
-        createShadow(light)
-      }
-    },
+    invalidate,
+    settle,
     placeCameras(sceneCameraMoved) {
       for (let shadow of shadows.values()) placeShadowCamera(shadow, sceneCameraMoved)
     },