@solidrt/3d 0.0.52 → 0.0.53

package/AGENTS.md

@@ -54,20 +54,37 @@ blendMode and pointer events like any element.
   the `castShadow` meshes (`<Mesh castShadow>`, `setCastShadow`) from an
   orthographic camera at the light's WORLD position along its world
   direction, `shadow.camera` (+-5, 0.5..500 by default) as the frustum.
-  Any directional light may cast (each map is a pass, capped by
-  MAX_LIGHTS = MAX_SHADOWS): shadow slot i is directional light i's -
-  the map's depth id binds as the target-level `uShadowMap<i>` of the
-  scene and every non-shadow view (a white texel when light i does not
-  cast), `uShadowMatrix[i]` is its view's own view-projection (the whole
-  array is one write per shadow-camera move), `uShadowCast[i]` says
-  whether it casts, `uShadowBias[i]`/`uShadowNormalBias[i]` its knobs;
-  `SHADOW_SLOTS` in glsl declares the set. Every `lit` material RECEIVES by default
+  Any directional light may cast (capped by MAX_LIGHTS = MAX_SHADOWS).
+  `shadow: { cascades: N }` (1..MAX_CASCADES = 4) replaces the box with
+  N maps fitted to slices of the SCENE camera's frustum (near ..
+  `shadow.distance`, default the camera far; the practical split; each
+  slice's bounding sphere as an ortho box along the light, its centre
+  snapped to the map's texel grid so edges do not swim; re-fitted
+  whenever the scene camera or the light moves) - a receiver samples the
+  tightest map that covers the point, fading into the next over the
+  map's outer 10% (`SHADOW_BLEND`) so the hand-over is a band, not a
+  seam; contact shadows stay sharp near the camera while the horizon
+  still has coarse ones, and pulling `distance` in sharpens all of them.
+  The box is the honest tier for a bounded scene; cascades are for a
+  scene that outgrows it, at N times the shadow fill. Every map is a
+  TILE of the scene's one shadow atlas (a `depth: "texture"` draw target,
+  a grid of cells the largest `mapSize` wide, scaled down uniformly
+  against `limits.maxTextureSize`), so N maps are ONE pass: the atlas
+  depth binds as the target-level `uShadowAtlas` of the scene and every
+  non-shadow view (a white texel when nothing casts); maps are MAP slots
+  dealt in light order, a light's cascades consecutive and tightest
+  first - `uShadowRect[j]` slot j's tile in atlas UV, `uShadowMatrix[j]`
+  its view's own view-projection (the whole array is one write per
+  shadow-camera move) - and per light i `uShadowFirst[i]`/`uShadowCount[i]`
+  name its slots (count 0 = it does not cast) with
+  `uShadowBias[i]`/`uShadowNormalBias[i]` its knobs; `SHADOW_SLOTS` in
+  glsl declares the set. Every `lit` material RECEIVES by default
   (Godot's and Three's default); `lit({ receiveShadow: false })` opts a
   material out and drops the map from its program - a material option,
   as with vertexColors/triplanar, because the material picks the program
   (Godot's `disable_receive_shadows`). The factor is `SHADOW`'s 3x3 PCF
   on each casting light's own term. `examples/shadows.tsx` (three
-  casting lights) is the shape.
+  casting lights) is the shape; `examples/cascades.tsx` the cascaded sun.
 - RETARGETED motion is native: `setTransition(node, { position:
   { duration: 400 }, ... })` makes setTransform writes TARGETS the core
   animates toward every frame (position/scale per lane, rotation along
@@ -408,13 +425,18 @@ the material need that channel) and the pure functions `HEMISPHERE`
 (`hemisphere(n, sky, ground)`), `LAMBERT` (`lambert(n, l)`),
 `BLINN_SPECULAR` (`blinnSpecular(n, v, l, shininess)`), `FRESNEL`
 (`fresnel(n, v, power)`), and the shadow trio composed IN ORDER:
-`SHADOW_SLOTS` (the scene's shadow set: `uShadowMap0..N-1`,
-`uShadowMatrix[N]`, `uShadowCast[N]`, `uShadowBias[N]`,
-`uShadowNormalBias[N]`, slot i = directional light i), `SHADOW`
-(`shadow(map, coord, bias)` - one map's 3x3 PCF factor) and
-`SHADOW_LOOKUP` (`lightShadow(i, worldPos, n)` - light i's factor, 1
-when it does not cast; it hides the if-chain that picks the map, since
-GLSL ES 3.00 forbids dynamic sampler indexing). A receiving fragment
+`SHADOW_SLOTS` (the scene's shadow set: `uShadowAtlas`, per map slot
+`uShadowRect[M]`/`uShadowMatrix[M]`, per directional light
+`uShadowFirst[N]`/`uShadowCount[N]` (its slots; a cascaded light has
+several, tightest first), `uShadowBias[N]`, `uShadowNormalBias[N]`),
+`SHADOW` (`shadowPoint(coord)` - clip to map point, `shadowInside(p)` -
+does the map have it, `shadowSample(map, rect, p, bias)` - one tile's
+3x3 PCF factor, and `shadow(map, rect, coord, bias)` composing the
+three) and `SHADOW_LOOKUP`
+(`lightShadow(i, worldPos, n)` - light i's factor, 1 when it does not
+cast; it walks the light's slots and samples the first map that covers
+the point, which is the cascade select, blended into the next map over
+the outer `SHADOW_BLEND` of the map). A receiving fragment
 multiplies light i's term by `lightShadow(i, ...)`, exactly what `lit`
 composes; a non-receiving one composes none of the three and declares no
 samplers. Lights, colors and exponents are arguments, so

package/examples/README.md

@@ -50,6 +50,14 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   ground and the casters receiving through plain `lit` (the default);
   each shadow camera follows its light's world matrix, each map is
   rendered by an internal view.
+- `cascades.tsx` - cascaded shadow maps: a sun with `shadow: { cascades:
+  3 }` over a field of pillars to the horizon under a slowly flying
+  camera; three maps fitted to slices of the camera frustum, sampled
+  tightest-first, so the shadows are sharp at the camera's feet and still
+  there at the far edge of the ground. A click cycles 1..4 cascades (1 is
+  the plain box widened to cover the field: one map's texels spread over
+  it, blocky everywhere) and the `cascades`/`fly` debug commands set the
+  count and the shadow distance and park the flight.
 - `model.tsx` - a model from a file: `model.glb` (a small rover with
   nested node transforms, a mirrored node, a textured material, a
   transparent dome and a mesh without normals) parsed with `parseGltf`

package/examples/cascades.tsx

@@ -0,0 +1,121 @@
+// Cascaded shadow maps: a field of pillars to the horizon under a slowly
+// flying camera, lit by one casting sun with `shadow: { cascades: 3 }`.
+// A box shadow (`shadow.camera`) is one map over a fixed area: widened to
+// cover this field its 1024 texels spread over 260 world units and every
+// shadow is blocky, kept tight the far field is unshadowed. With cascades
+// the light renders one map per slice of the SCENE camera's frustum
+// (near..far, tightest first), re-fitted every time the camera or the
+// light moves, and a receiver samples the tightest map that has the
+// point: sharp contact shadows at the camera's feet, coarser ones toward
+// the horizon, at the cost of N times the shadow fill. Every map is a
+// tile of the scene's one atlas, so the pass count is unchanged.
+//
+// A click cycles 1..4 cascades (1 = the box, widened over the field).
+// The `cascades` debug command sets the count and the shadow distance
+// (`{ count, distance }`; the range the cascades split, the camera's far
+// by default - pulling it in sharpens every cascade) and `fly` parks the
+// flight (`{ t: seconds }`), so a capture repeats.
+import { createSignal, onFrame, pct, render } from "@solidrt/core"
+import { registerDebug } from "srt:dev"
+import { box, DirectionalLight, HemisphereLight, lit, Mesh, PerspectiveCamera, plane, Scene, sphere } from "@solidrt/3d"
+import type { Geometry, Vec3 } from "@solidrt/3d"
+
+const SIZE = 720
+const FIELD = 260
+const FAR = 200
+// The flight: a circle over the field, looking ahead along it.
+const RADIUS = 50
+const HEIGHT = 5
+const PERIOD = 90
+
+let [cascades, setCascades] = createSignal(3)
+let [distance, setDistance] = createSignal<number | null>(null)
+// The flight clock, in seconds; `parked` holds it.
+let [time, setTime] = createSignal(0)
+let parked: number | null = null
+
+registerDebug("cascades", (args?: Record<string, unknown>) => {
+  if (typeof args?.count === "number") setCascades(args.count)
+  if (typeof args?.distance === "number" || args?.distance === null) setDistance(args.distance)
+  return { cascades: cascades(), distance: distance() }
+})
+registerDebug("fly", (args?: Record<string, unknown>) => {
+  if (typeof args?.t === "number") {
+    parked = args.t
+    setTime(args.t)
+  } else if (args?.t === null) {
+    parked = null
+  }
+  return { t: time(), parked: parked !== null }
+})
+
+// A grid of pillars with a sphere on every third one, heights varying so
+// the shadows differ in length; one geometry per height, shared.
+let pillars: { position: Vec3; height: number; ball: boolean }[] = []
+let step = 16
+for (let i = -7; i <= 7; i++) {
+  for (let j = -7; j <= 7; j++) {
+    let h = 2 + ((i * 7 + j * 3 + 100) % 5)
+    pillars.push({ position: [i * step + (j % 2) * 4, h / 2, j * step + (i % 2) * 5], height: h, ball: (i + j) % 3 === 0 })
+  }
+}
+let boxes = new Map<number, Geometry>()
+let pillar = (height: number): Geometry => {
+  let g = boxes.get(height)
+  if (g === undefined) boxes.set(height, (g = box({ width: 1.2, height, depth: 1.2 })))
+  return g
+}
+let orb = sphere({ radius: 0.9 })
+
+function App() {
+  onFrame(tick => {
+    if (parked === null) setTime(tick / 1000)
+  })
+  let eye = (): Vec3 => {
+    let a = (time() / PERIOD) * Math.PI * 2
+    return [Math.sin(a) * RADIUS, HEIGHT, Math.cos(a) * RADIUS]
+  }
+  let ahead = (): Vec3 => {
+    let a = (time() / PERIOD) * Math.PI * 2 + 0.5
+    return [Math.sin(a) * RADIUS, 1.5, Math.cos(a) * RADIUS]
+  }
+
+  let ground = lit({ color: [0.5, 0.55, 0.45] })
+  let stone = lit({ color: [0.75, 0.7, 0.62] })
+  let ball = lit({ color: [0.85, 0.35, 0.3], specular: 0.4, shininess: 30 })
+
+  return (
+    <window>
+      <view width={pct(100)} height={pct(100)} designSize={[SIZE, SIZE]} onPointerDown={() => setCascades(c => (c % 4) + 1)}>
+        <Scene width={SIZE} height={SIZE} clearColor={[0.6, 0.72, 0.88, 1]} samples={4} label="cascades">
+          <PerspectiveCamera fov={50} near={0.5} far={FAR} position={eye()} lookAt={ahead()} />
+          <HemisphereLight sky={[0.5, 0.58, 0.7]} ground={[0.25, 0.22, 0.18]} />
+          <DirectionalLight
+            color={[1, 0.95, 0.85]}
+            intensity={0.9}
+            position={[40, 90, 30]}
+            direction={[-1, -0.55, -0.4]}
+            castShadow
+            shadow={{
+              mapSize: 1024,
+              normalBias: 0.08,
+              cascades: cascades(),
+              distance: distance(),
+              // The box tier's frustum, when cascades is 1: the whole field.
+              camera: { left: -FIELD / 2, right: FIELD / 2, top: FIELD / 2, bottom: -FIELD / 2, near: 1, far: 400 },
+            }}
+          />
+          <Mesh geometry={plane({ width: FIELD, height: FIELD })} material={ground} rotation={[-Math.PI / 2, 0, 0]} />
+          {pillars.map(p => (
+            <>
+              <Mesh geometry={pillar(p.height)} material={stone} position={p.position} castShadow />
+              {p.ball ? <Mesh geometry={orb} material={ball} position={[p.position[0], p.height + 0.9, p.position[2]]} castShadow /> : null}
+            </>
+          ))}
+        </Scene>
+      </view>
+    </window>
+  )
+}
+
+render(() => <App />)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.52",
+  "version": "0.0.53",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -13,12 +13,12 @@
   },
   "files": [
     "src/",
+    "tools/",
     "examples/",
-    "demos/",
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.1",
-    "@solidrt/core": "0.0.52"
+    "@solidjs/signals": "2.0.0-rc.3",
+    "@solidrt/core": "0.0.53"
   }
 }

package/src/components.tsx

@@ -379,8 +379,8 @@ export type DirectionalLightProps = TransformProps & {
    * each is a pass). Its shadow camera sits at the light's WORLD
    * position, so give a casting light a `position` above the scene. */
   castShadow?: boolean
-  /** Shadow-map options (mapSize, bias, normalBias, camera frustum),
-   * merged key by key. */
+  /** Shadow-map options (mapSize, bias, normalBias, camera frustum,
+   * cascades, distance), merged key by key. */
   shadow?: ShadowOptions
   ref?: (light: DirectionalLightNode) => void
 }

package/src/glsl.ts

@@ -23,6 +23,15 @@ import { glsl } from "@solidrt/core/gpu"
  * the app (see okf/backlog/app-runtime-config.md). */
 export const MAX_LIGHTS = 4
 
+/** The most cascades one casting light splits its shadow into
+ * (`shadow.cascades`, 1..MAX_CASCADES). */
+export const MAX_CASCADES = 4
+
+/** The shadow-map slot count of the scene's shadow set: every casting
+ * light owns `shadow.cascades` consecutive slots (one per map), so this
+ * bounds `uShadowRect`/`uShadowMatrix`. */
+export const MAX_SHADOW_MAPS = MAX_LIGHTS * MAX_CASCADES
+
 /**
  * The standard lit vertex stage: clip position via uViewProj * uModel,
  * with world position, world normal (via `mat3(uNormal)`, correct under
@@ -119,74 +128,120 @@ export const FRESNEL = glsl`
 `
 
 /**
- * The scene's shadow set as a receiving program declares it, one slot per
- * directional light index: `uShadowMap0..N-1` (each light's depth map, a
- * white texel when it does not cast), `uShadowMatrix[N]` (its light-space
- * viewProj), `uShadowCast[N]` (1 when light i casts), `uShadowBias[N]` and
+ * The scene's shadow set as a receiving program declares it: ONE
+ * `uShadowAtlas` (every casting light's depth map is a tile of it, so N
+ * maps render as one pass; a white texel when nothing casts), a MAP slot
+ * set of `MAX_SHADOW_MAPS` - `uShadowRect[M]` (map slot j's tile as x, y,
+ * width, height in atlas 0..1 UV) and `uShadowMatrix[M]` (its light-space
+ * viewProj) - and, per directional light index, `uShadowFirst[N]` /
+ * `uShadowCount[N]` (light i's maps are slots `first .. first + count - 1`;
+ * count 0 = it does not cast; a box light has one map, a cascaded light
+ * `shadow.cascades` of them, tightest first), `uShadowBias[N]` and
  * `uShadowNormalBias[N]`. The scene binds and writes all of it on every
  * target a receiving material can draw into; a custom material composes
  * this, then SHADOW, then SHADOW_LOOKUP (in that order) and multiplies
- * light i's term by `lightShadow(i, worldPos, n)` - `lit` is the shape.
- * A material that does not receive composes none of it, so it declares
- * no samplers for nothing.
+ * light i's term by `lightShadow(i, worldPos, n)` - `lit` is the shape. A
+ * material that does not receive composes none of it, so it declares no
+ * sampler for nothing.
  */
 export const SHADOW_SLOTS = glsl`
-  ${Array.from({ length: MAX_LIGHTS }, (_, i) => `uniform sampler2D uShadowMap${i};`).join("\n  ")}
-  uniform mat4 uShadowMatrix[${MAX_LIGHTS}];
-  uniform int uShadowCast[${MAX_LIGHTS}];
+  uniform sampler2D uShadowAtlas;
+  uniform vec4 uShadowRect[${MAX_SHADOW_MAPS}];
+  uniform mat4 uShadowMatrix[${MAX_SHADOW_MAPS}];
+  uniform int uShadowFirst[${MAX_LIGHTS}];
+  uniform int uShadowCount[${MAX_LIGHTS}];
   uniform float uShadowBias[${MAX_LIGHTS}];
   uniform float uShadowNormalBias[${MAX_LIGHTS}];
 `
 
 /**
- * `float shadow(sampler2D map, vec4 coord, float bias)` - the directional
- * shadow factor (1 lit, 0 shadowed) for a world point carried into a
- * casting light's clip space by its `uShadowMatrix[i]`:
- * `shadow(uShadowMap0, uShadowMatrix[0] * vec4(vWorldPos, 1.0), uShadowBias[0])`.
- * Perspective divide, 0..1 remap, out-of-frustum returns 1 (lit), then a
- * 3x3 PCF over texel neighbours comparing the map's `.r` (a stage-1 depth
- * texture samples nearest, so the softness is this loop, not the sampler).
- * `bias` is subtracted from the point's depth against acne; SHADOW_LOOKUP
- * also offsets the point along its normal by `uShadowNormalBias[i]`
- * before the transform.
+ * The shadow lookup in three steps plus their composition, one map at a
+ * time. `vec3 shadowPoint(vec4 coord)` takes a world point carried into a
+ * casting light's clip space by that map's `uShadowMatrix[j]` to its map
+ * point: xy in 0..1 across the map, z the depth to compare. `bool
+ * shadowInside(vec3 p)` is whether the map has it at all (xy in 0..1, z
+ * not past the far plane) - the cascade select. `float shadowSample(
+ * sampler2D map, vec4 rect, vec3 p, float bias)` is the factor (1 lit, 0
+ * shadowed) of a point the map has: a 3x3 PCF over texel neighbours in
+ * the map's tile `rect` (x, y, width, height in `map`'s 0..1 UV;
+ * `vec4(0, 0, 1, 1)` is a whole map) comparing the map's `.r` (a stage-1
+ * depth texture samples nearest, so the softness is this loop, not the
+ * sampler); every tap is clamped to the tile inset by half a texel, so
+ * no tap reads a neighbouring map's tile; `bias` is subtracted from the
+ * point's depth against acne. `float shadow(sampler2D map, vec4 rect,
+ * vec4 coord, float bias)` composes the three: 1 (lit) outside the map,
+ * else the sample -
+ * `shadow(uShadowAtlas, uShadowRect[0], uShadowMatrix[0] * vec4(vWorldPos, 1.0), uShadowBias[0])`.
+ * SHADOW_LOOKUP uses the steps, so it projects each map once.
  */
 export const SHADOW = glsl`
-  float shadow(sampler2D map, vec4 coord, float bias) {
-    vec3 p = coord.xyz / coord.w * 0.5 + 0.5;
-    if (p.x < 0.0 || p.x > 1.0 || p.y < 0.0 || p.y > 1.0 || p.z > 1.0) return 1.0;
+  vec3 shadowPoint(vec4 coord) {
+    return coord.xyz / coord.w * 0.5 + 0.5;
+  }
+
+  bool shadowInside(vec3 p) {
+    return all(greaterThanEqual(p.xy, vec2(0.0))) && all(lessThanEqual(p, vec3(1.0)));
+  }
+
+  float shadowSample(sampler2D map, vec4 rect, vec3 p, float bias) {
     vec2 texel = 1.0 / vec2(textureSize(map, 0));
+    vec2 lo = rect.xy + 0.5 * texel;
+    vec2 hi = rect.xy + rect.zw - 0.5 * texel;
+    vec2 base = rect.xy + p.xy * rect.zw;
     float lit = 0.0;
     for (int y = -1; y <= 1; y++) {
       for (int x = -1; x <= 1; x++) {
-        float d = texture(map, p.xy + vec2(float(x), float(y)) * texel).r;
+        float d = texture(map, clamp(base + vec2(float(x), float(y)) * texel, lo, hi)).r;
         lit += p.z - bias <= d ? 1.0 : 0.0;
       }
     }
     return lit / 9.0;
   }
+
+  float shadow(sampler2D map, vec4 rect, vec4 coord, float bias) {
+    vec3 p = shadowPoint(coord);
+    return shadowInside(p) ? shadowSample(map, rect, p, bias) : 1.0;
+  }
 `
 
 /**
  * The step from a light index to its shadow factor, over SHADOW_SLOTS and
- * SHADOW (compose both first). `float shadowAt(int i, vec4 coord, float
- * bias)` picks light i's map - an if-chain over the slots, because GLSL
- * ES 3.00 only indexes a sampler array by a constant - and samples it
- * with `shadow`. `float lightShadow(int i, vec3 worldPos, vec3 n)` is
- * the one to call per light: 1 for a light that does not cast, else the
- * factor for `worldPos` pushed along its normal `n` by
- * `uShadowNormalBias[i]` (the acne knob to reach for first) and carried
- * through `uShadowMatrix[i]` with `uShadowBias[i]`. Position and normal
- * are arguments, so no varying name is pinned and a custom vertex stage
- * composes freely.
+ * SHADOW (compose both first). `float lightShadow(int i, vec3 worldPos,
+ * vec3 n)` is the one to call per light: 1 for a light that does not
+ * cast, else the factor for `worldPos` pushed along its normal `n` by
+ * `uShadowNormalBias[i]` (the acne knob to reach for first), looked up in
+ * the FIRST of light i's maps that has the point (a box light has one; a
+ * cascaded light's maps come tightest first, so the sharpest cascade
+ * that has the point wins and a point past the last is lit) with that
+ * map's `uShadowMatrix[j]`, its tile and `uShadowBias[i]`. Inside the
+ * outer SHADOW_BLEND of a map (in map 0..1 units, so 0.1 is its outer
+ * 10% on each side) the factor fades into the next cascade's, so the
+ * hand-over is a band and not a seam; the last map, a box light's only
+ * one, and any rim the next cascade does not reach (the near side, at
+ * the camera's feet) have no band. Position and normal are arguments, so
+ * no varying name is pinned and a custom vertex stage composes freely.
  */
 export const SHADOW_LOOKUP = glsl`
-  float shadowAt(int i, vec4 coord, float bias) {
-    ${Array.from({ length: MAX_LIGHTS }, (_, i) => `if (i == ${i}) return shadow(uShadowMap${i}, coord, bias);`).join("\n    ")}
-    return 1.0;
-  }
+  const float SHADOW_BLEND = 0.1;
 
   float lightShadow(int i, vec3 worldPos, vec3 n) {
-    if (uShadowCast[i] != 1) return 1.0;
-    return shadowAt(i, uShadowMatrix[i] * vec4(worldPos + n * uShadowNormalBias[i], 1.0), uShadowBias[i]);
+    int count = uShadowCount[i];
+    if (count == 0) return 1.0;
+    vec4 w = vec4(worldPos + n * uShadowNormalBias[i], 1.0);
+    float bias = uShadowBias[i];
+    int first = uShadowFirst[i];
+    int last = first + count - 1;
+    for (int j = first; j <= last; j++) {
+      vec3 p = shadowPoint(uShadowMatrix[j] * w);
+      if (!shadowInside(p)) continue;
+      float s = shadowSample(uShadowAtlas, uShadowRect[j], p, bias);
+      if (j == last) return s;
+      float edge = min(min(p.x, 1.0 - p.x), min(p.y, 1.0 - p.y));
+      if (edge >= SHADOW_BLEND) return s;
+      vec3 q = shadowPoint(uShadowMatrix[j + 1] * w);
+      if (!shadowInside(q)) return s;
+      return mix(shadowSample(uShadowAtlas, uShadowRect[j + 1], q, bias), s, edge / SHADOW_BLEND);
+    }
+    return 1.0;
   }
 `

package/src/material.ts

@@ -216,10 +216,11 @@ export type LitOptions = UnlitOptions & {
 // composes by hand, per flag: map x vertexColors x triplanar x shadow x
 // transparent. Lights arrive through the scene's shared params
 // (light nodes); the base color, map and highlight are per entry. The
-// shadow set is shared too and indexed like the lights: slot i is
-// directional light i's map, matrix and biases (target-level, bound by
-// the scene), uShadowCast[i] says whether it casts; SHADOW_LOOKUP turns
-// the index into the factor.
+// shadow set is shared too and indexed like the lights: one atlas sampler,
+// directional light i's maps (one, or its cascades) as map slots
+// uShadowFirst[i] .. + uShadowCount[i] with a tile rect and a matrix
+// each, and its biases (target-level, bound by the scene); uShadowCount
+// 0 means it does not cast; SHADOW_LOOKUP turns the index into the factor.
 function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, shadow: boolean): string {
   return glsl`
     in vec3 vWorldPos;

package/src/math.ts

@@ -648,3 +648,79 @@ export function rayBoxDistance(
   }
   return tFar >= tNear ? tNear : -1
 }
+
+/**
+ * The far bound of slice `index` of `count` when a range near..far is
+ * split for shadow cascades: `lambda` 0 slices it uniformly, 1
+ * logarithmically (equal texel density per unit of view depth, which
+ * starves the far slices), between the two in between. The last slice
+ * ends at `far`; a near of 0 has no logarithm and slices uniformly.
+ */
+export function cascadeSplit(near: number, far: number, index: number, count: number, lambda: number): number {
+  if (index >= count - 1) return far
+  let t = (index + 1) / count
+  let uniform = near + (far - near) * t
+  if (!(near > 0)) return uniform
+  let log = near * Math.pow(far / near, t)
+  return uniform + (log - uniform) * lambda
+}
+
+/** The camera facts a frustum slice depends on: its view matrix (rows are
+ * its right, up and back axes), eye, vertical fov in degrees and, for an
+ * orthographic camera, the extents (fov ignored then). */
+export type FrustumSpec = { view: Mat4; eye: Vec3; fov: number; ortho: { left: number; right: number; top: number; bottom: number } | null }
+
+/**
+ * The bounding sphere of the slice zn..zf of a camera's view frustum
+ * (`aspect` = width / height): writes the centre to `out`, returns the
+ * radius. Perspective: the centre sits on the view axis where the near
+ * and far corner rings are equidistant, clamped into the slice, so it
+ * is the tightest sphere on the axis; orthographic: the slice box's
+ * centre and half-diagonal. A sphere rather than the slice's own corners
+ * so a shadow box fitted to it keeps its size while the camera turns.
+ */
+export function frustumSliceSphere(out: Vec3, cam: FrustumSpec, aspect: number, zn: number, zf: number): number {
+  let v = cam.view
+  let fx = -v[2]
+  let fy = -v[6]
+  let fz = -v[10]
+  let o = cam.ortho
+  if (o === null) {
+    // Corner distance from the axis per unit of depth.
+    let k = Math.tan((cam.fov * Math.PI) / 360) * Math.hypot(1, aspect)
+    let rn = zn * k
+    let rf = zf * k
+    let zc = zf > zn ? Math.min(zf, Math.max(zn, (zf * zf + rf * rf - zn * zn - rn * rn) / (2 * (zf - zn)))) : zn
+    out[0] = cam.eye[0] + fx * zc
+    out[1] = cam.eye[1] + fy * zc
+    out[2] = cam.eye[2] + fz * zc
+    return Math.hypot(zf - zc, rf)
+  }
+  let zc = 0.5 * (zn + zf)
+  let cx = 0.5 * (o.left + o.right)
+  let cy = 0.5 * (o.top + o.bottom)
+  out[0] = cam.eye[0] + fx * zc + v[0] * cx + v[1] * cy
+  out[1] = cam.eye[1] + fy * zc + v[4] * cx + v[5] * cy
+  out[2] = cam.eye[2] + fz * zc + v[8] * cx + v[9] * cy
+  return Math.hypot(0.5 * (o.right - o.left), 0.5 * (o.top - o.bottom), 0.5 * (zf - zn))
+}
+
+/**
+ * Snap `p`'s coordinates along the first two axes of `basis` (a rotation
+ * matrix whose rows are the frame's axes - `lookAt([0, 0, 0], dir, up)`
+ * for a light) to multiples of `step`, leaving the third as it is;
+ * writes to `out`, which may be `p`. A shadow box centred on the result
+ * moves by whole texels only, so its shadows do not swim as the camera
+ * creeps.
+ */
+export function snapToGrid(out: Vec3, p: Vec3, basis: Mat4, step: number): Vec3 {
+  let x = basis[0] * p[0] + basis[4] * p[1] + basis[8] * p[2]
+  let y = basis[1] * p[0] + basis[5] * p[1] + basis[9] * p[2]
+  let z = basis[2] * p[0] + basis[6] * p[1] + basis[10] * p[2]
+  x = Math.round(x / step) * step
+  y = Math.round(y / step) * step
+  out[0] = basis[0] * x + basis[1] * y + basis[2] * z
+  out[1] = basis[4] * x + basis[5] * y + basis[6] * z
+  out[2] = basis[8] * x + basis[9] * y + basis[10] * z
+  return out
+}