@solidrt/3d 0.0.52 → 0.0.54

package/src/gltf.ts

@@ -30,11 +30,16 @@ export type ModelMaterial = {
   color: [number, number, number, number]
   /** Index into ModelData.images (the base color texture), or null. */
   map: number | null
-  /** glTF doubleSided. Reported, not applied: the standard materials cull
-   * back faces. */
+  /** glTF doubleSided; createModel's default material draws it with
+   * `cull: "none"`. */
   doubleSided: boolean
-  /** alphaMode BLEND. MASK draws opaque (no alpha test). */
+  /** alphaMode BLEND; createModel's default material blends it. */
   transparent: boolean
+  /** glTF alphaMode as written (default OPAQUE). MASK is a cutout:
+   * createModel's default material draws it with `alphaTest: alphaCutoff`. */
+  alphaMode: "OPAQUE" | "MASK" | "BLEND"
+  /** glTF alphaCutoff (default 0.5); meaningful for MASK only. */
+  alphaCutoff: number
 }
 
 /** One drawable: a mesh node's primitive, vertices in WORLD space. */
@@ -67,10 +72,21 @@ const CHUNK_JSON = 0x4e4f534a
 const CHUNK_BIN = 0x004e4942
 const MODE_TRIANGLES = 4
 
+// The spec's alphaCutoff when a MASK material leaves it out.
+const GLTF_ALPHA_CUTOFF = 0.5
+
 const COMPONENT_BYTES: Record<number, number> = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 }
 const TYPE_ELEMENTS: Record<string, number> = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 }
 
-const DEFAULT_MATERIAL: ModelMaterial = { name: "default", color: [1, 1, 1, 1], map: null, doubleSided: false, transparent: false }
+const DEFAULT_MATERIAL: ModelMaterial = {
+  name: "default",
+  color: [1, 1, 1, 1],
+  map: null,
+  doubleSided: false,
+  transparent: false,
+  alphaMode: "OPAQUE",
+  alphaCutoff: GLTF_ALPHA_CUTOFF,
+}
 
 /** True when the bytes are a .glb container (the "glTF" magic). */
 export function isGlb(bytes: Uint8Array): boolean {
@@ -171,6 +187,8 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       map,
       doubleSided: m.doubleSided === true,
       transparent: m.alphaMode === "BLEND",
+      alphaMode: m.alphaMode === "MASK" || m.alphaMode === "BLEND" ? m.alphaMode : "OPAQUE",
+      alphaCutoff: typeof m.alphaCutoff === "number" ? m.alphaCutoff : GLTF_ALPHA_CUTOFF,
     }
   })
   // Primitives without a material draw the spec's default; it is appended

package/src/material.ts

@@ -35,7 +35,6 @@ import type {
   ProgramId,
   RenderPipelineId,
   ShaderParams,
-  ShaderStageId,
   TextureBindings,
   TextureId,
   Topology,
@@ -73,18 +72,27 @@ export type Material = {
    * instanced meshes only - createInstancedMesh supplies the record buffer,
    * and createMesh meshes are rejected at add(). */
   instanceAttributes?: VertexAttribute[]
+  /** What a shadow view draws this material's meshes with instead of its
+   * default depth override: the depth pass culling the side this material
+   * culls (Three's shadowSide rule, Godot's shadow pass), so a `cull:
+   * "none"` caster casts from both faces, and for a cutout (lit
+   * alphaTest with a map) the same discard, so a plant casts leaves and
+   * not rectangles. Absent = the default (a back-culling material casts
+   * from its back faces). A shaderMaterial supplies its own through the
+   * instance option of the same name. */
+  shadow?: Material
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
 
-// One vertex stage serves every unlit class: model then view-projection,
-// plus the UV varying. uModel is per-entry (the scene writes it when the
-// mesh moves), uViewProj is target-shared (one write per camera move) - the
-// split is what keeps camera motion O(1) instead of O(meshes), and the
-// extra per-vertex mat4 multiply is free on the GPU. aNormal from the
-// shared layout is deliberately not declared - inactive attributes are
-// skipped and only the stride accounts for them.
-const VERTEX_SRC = glsl`
+// The unlit vertex stage: model then view-projection, plus the UV
+// varying. uModel is per-entry (the scene writes it when the mesh moves),
+// uViewProj is target-shared (one write per camera move) - the split is
+// what keeps camera motion O(1) instead of O(meshes), and the extra
+// per-vertex mat4 multiply is free on the GPU. aNormal from the shared
+// layout is deliberately not declared - inactive attributes are skipped
+// and only the stride accounts for them.
+const UNLIT_VERTEX = glsl`
   in vec3 aPos;
   in vec2 aUV;
   out vec2 vUv;
@@ -97,61 +105,28 @@ const VERTEX_SRC = glsl`
   }
 `
 
-const FRAGMENT_COLOR_SRC = glsl`
-  uniform vec4 uColor;
-  void main() {
-    fragColor = uColor;
-  }
-`
-
-const FRAGMENT_MAP_SRC = glsl`
-  in vec2 vUv;
-  uniform sampler2D uMap;
-  uniform vec4 uColor;
-  void main() {
-    fragColor = texture(uMap, vUv) * uColor;
-  }
-`
-
-let sharedVertex: ShaderStageId | undefined
-let programs: Partial<Record<UnlitClass, ProgramId>> = {}
-let pipelines = new Map<string, RenderPipelineId>()
-
-// One program per unlit CLASS: fragment kind x transparency. Blend state is
-// pipeline state and so is the attribute list, so the pipeline is keyed by
-// class and vertex layout.
-type UnlitClass = "color" | "map" | "color-transparent" | "map-transparent"
-
-function programFor(cls: UnlitClass): ProgramId {
-  let program = programs[cls]
-  if (program === undefined) {
-    if (sharedVertex === undefined) sharedVertex = compileShader("vertex", VERTEX_SRC, { header: true })
-    let fragment = compileShader("fragment", cls.startsWith("color") ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
-      header: true,
-    })
-    program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + cls })
-    programs[cls] = program
-  }
-  return program
+// The unlit fragment (sprites share it): the color, times the map when
+// there is one, with the alphaTest discard when asked for. An opaque
+// class writes alpha 1: the scene target is composited premultiplied, so
+// a leaked texel alpha would punch a hole through an opaque draw.
+function unlitFragment(map: boolean, alphaTest: boolean, transparent: boolean): string {
+  return glsl`
+    ${map ? "in vec2 vUv;" : ""}
+    ${map ? "uniform sampler2D uMap;" : ""}
+    uniform vec4 uColor;
+    ${alphaTest ? "uniform float uAlphaTest;" : ""}
+    void main() {
+      vec4 base = ${map ? "texture(uMap, vUv) * uColor" : "uColor"};
+      ${alphaTest ? "if (base.a < uAlphaTest) discard;" : ""}
+      fragColor = ${transparent ? "base" : "vec4(base.rgb, 1.0)"};
+    }
+  `
 }
 
-function pipelineFor(cls: UnlitClass, layout: VertexLayout | undefined): RenderPipelineId {
-  let key = cls + "|" + layoutKey(layout)
-  let existing = pipelines.get(key)
-  if (existing !== undefined) return existing
-  let program = programFor(cls)
-  let transparent = cls.endsWith("-transparent")
-  let pipeline = createRenderPipeline(program, {
-    attributes: layoutAttributes(layout),
-    depth: true,
-    depthWrite: transparent ? false : undefined,
-    blend: transparent ? "alpha" : undefined,
-    cull: "back",
-    label: "scene-unlit-" + cls,
-  })
-  pipelines.set(key, pipeline)
-  return pipeline
-}
+// One shaderMaterialClass per unlit option combination (map x transparent
+// x cull x alphaTest), cached for the app's lifetime like lit's; one
+// pipeline per vertex layout inside each.
+let unlitClasses = new Map<string, ShaderMaterialClass>()
 
 export type UnlitOptions = {
   /** Straight [r, g, b] or [r, g, b, a], 0..1. Default white. */
@@ -161,6 +136,18 @@ export type UnlitOptions = {
   /** Blend over what is behind (color alpha and map alpha both count).
    * Without it an alpha below 1 still draws opaque. See Material.transparent. */
   transparent?: boolean
+  /** Which faces to drop; default "back". "none" draws both sides of
+   * single-layer geometry (foliage cards, glass, a mirrored part), and
+   * lit materials then light a back face with its normal flipped, as
+   * Three's DoubleSide and Godot's CULL_DISABLED do. */
+  cull?: CullMode
+  /** Cutout: drop a fragment whose final alpha (color x map, and for lit
+   * the vertex color too) is below this, 0..1 (Three's alphaTest, glTF
+   * alphaMode MASK with its alphaCutoff). Opaque otherwise:
+   * depth-written, not sorted, unlike `transparent`. Foliage cards and
+   * fences want it with `cull: "none"`; a mapped cutout casts its cutout
+   * (Material.shadow). */
+  alphaTest?: number
 }
 
 /**
@@ -172,15 +159,29 @@ export function unlit(opts: UnlitOptions = {}): Material {
   let color = opts.color ?? [1, 1, 1]
   let a = color.length === 4 ? color[3] : 1
   let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  let map = opts.map !== undefined
   let transparent = opts.transparent === true
-  let cls: UnlitClass = opts.map !== undefined ? (transparent ? "map-transparent" : "map") : transparent ? "color-transparent" : "color"
-  return {
-    pipeline: layout => pipelineFor(cls, layout),
-    attributes: () => programAttributes(programFor(cls)),
-    params: { uColor },
-    textures: opts.map !== undefined ? { uMap: opts.map } : undefined,
-    transparent,
+  let cull = opts.cull ?? "back"
+  let alphaTest = opts.alphaTest !== undefined
+  let key = [map, transparent, cull, alphaTest].join("|")
+  let cls = unlitClasses.get(key)
+  if (cls === undefined) {
+    cls = shaderMaterialClass({
+      vertex: UNLIT_VERTEX,
+      fragment: unlitFragment(map, alphaTest, transparent),
+      transparent,
+      cull,
+      label: "scene-unlit-" + key,
+    })
+    unlitClasses.set(key, cls)
   }
+  let params: ShaderParams = { uColor }
+  if (alphaTest) params.uAlphaTest = opts.alphaTest!
+  return cls.instance({
+    params,
+    textures: map ? { uMap: opts.map! } : undefined,
+    shadow: alphaTest && map ? shadowCutoutMaterial(shadowCull(cull), uColor, opts.alphaTest!, opts.map!) : undefined,
+  })
 }
 
 export type LitOptions = UnlitOptions & {
@@ -214,13 +215,37 @@ export type LitOptions = UnlitOptions & {
 
 // The lit fragment is composed from the same exported pieces an app
 // 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.
-function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, shadow: boolean): string {
+// transparent x cull (a class that shows back faces lights them with the
+// normal flipped, else a double-sided leaf's back is black) x alphaTest
+// (the cutoff itself is a per-entry uniform, one class for every value).
+// An opaque class writes alpha 1 (see unlitFragment). 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: 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.
+// The option combination that picks a lit class: the class-cache key is
+// its values in this order, and the fragment builder reads the same
+// object, so the two cannot drift apart.
+type LitClass = {
+  map: boolean
+  vertexColors: boolean
+  triplanar: boolean
+  transparent: boolean
+  shadow: boolean
+  cull: CullMode
+  alphaTest: boolean
+}
+
+function litClassKey(c: LitClass): string {
+  return Object.values(c).join("|")
+}
+
+function litFragment(c: LitClass): string {
+  let { map, vertexColors, triplanar, shadow, alphaTest } = c
+  let backFaces = c.cull !== "back"
   return glsl`
     in vec3 vWorldPos;
     in vec3 vNormal;
@@ -231,6 +256,7 @@ function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, sh
     uniform float uSpecular;
     uniform float uShininess;
     ${triplanar ? "uniform float uTriplanar;" : ""}
+    ${alphaTest ? "uniform float uAlphaTest;" : ""}
     uniform vec3 uCamPos;
     uniform vec3 uHemiSky;
     uniform vec3 uHemiGround;
@@ -250,6 +276,7 @@ function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, sh
 
     void main() {
       vec3 n = normalize(vNormal);
+      ${backFaces ? "if (!gl_FrontFacing) n = -n;" : ""}
       vec4 base = uColor;
       ${
         map
@@ -262,6 +289,7 @@ function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, sh
           : ""
       }
       ${vertexColors ? "base *= vColor;" : ""}
+      ${alphaTest ? "if (base.a < uAlphaTest) discard;" : ""}
       vec3 v = normalize(uCamPos - vWorldPos);
       vec3 light = hemisphere(n, uHemiSky, uHemiGround);
       vec3 spec = vec3(0.0);
@@ -274,7 +302,7 @@ function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, sh
         light += uLightColor[i] * lambert(n, l) * s;
         spec += uLightColor[i] * blinnSpecular(n, v, l, uShininess) * s;
       }
-      fragColor = vec4(base.rgb * light + spec * uSpecular * base.a, base.a);
+      fragColor = vec4(base.rgb * light + spec * uSpecular * base.a, ${c.transparent ? "base.a" : "1.0"});
     }
   `
 }
@@ -284,8 +312,8 @@ let litClasses = new Map<string, ShaderMaterialClass>()
 /**
  * A lit material: hemisphere ambient plus the scene's directional lights
  * (DirectionalLight nodes), Lambert diffuse, optional
- * Blinn-Phong highlight. Same options as unlit (color, map, transparent)
- * plus vertexColors, specular/shininess and triplanar mapping. One program
+ * Blinn-Phong highlight. Same options as unlit (color, map, transparent,
+ * cull, alphaTest) plus vertexColors, specular/shininess and triplanar mapping. One program
  * per option combination, one pipeline per vertex layout met, shared by
  * every instance - a thousand lit meshes still share one pipeline. No
  * lights set means black except for the hemisphere term, which also
@@ -296,26 +324,40 @@ export function lit(opts: LitOptions = {}): Material {
   let a = color.length === 4 ? color[3] : 1
   let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
   let map = opts.map !== undefined
-  let vertexColors = opts.vertexColors === true
   let triplanar = map && opts.triplanar !== undefined
-  let transparent = opts.transparent === true
-  let shadow = opts.receiveShadow !== false
-  let key = [map, vertexColors, triplanar, transparent, shadow].join("|")
+  let alphaTest = opts.alphaTest !== undefined
+  let cull = opts.cull ?? "back"
+  let flags: LitClass = {
+    map,
+    vertexColors: opts.vertexColors === true,
+    triplanar,
+    transparent: opts.transparent === true,
+    shadow: opts.receiveShadow !== false,
+    cull,
+    alphaTest,
+  }
+  let key = litClassKey(flags)
   let cls = litClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
-      vertex: vertexColors ? LIT_VERTEX_COLORED : LIT_VERTEX,
-      fragment: litFragment(map, vertexColors, triplanar, shadow),
-      transparent,
+      vertex: flags.vertexColors ? LIT_VERTEX_COLORED : LIT_VERTEX,
+      fragment: litFragment(flags),
+      transparent: flags.transparent,
+      cull,
       label: "scene-lit-" + key,
     })
     litClasses.set(key, cls)
   }
+  let params: ShaderParams = { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30 }
+  if (triplanar) params.uTriplanar = opts.triplanar!
+  if (alphaTest) params.uAlphaTest = opts.alphaTest!
+  // A UV-mapped cutout casts its cutout; a color-only or triplanar
+  // alphaTest keeps the plain (cull-only) variant.
+  let cutout = alphaTest && map && !triplanar
   let material = cls.instance({
-    params: triplanar
-      ? { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30, uTriplanar: opts.triplanar! }
-      : { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30 },
+    params,
     textures: map ? { uMap: opts.map! } : undefined,
+    shadow: cutout ? shadowCutoutMaterial(shadowCull(cull), uColor, opts.alphaTest!, opts.map!) : undefined,
   })
   return material
 }
@@ -340,20 +382,79 @@ const SHADOW_DEPTH_FRAGMENT = glsl`
   }
 `
 
-let shadowDepth: Material | undefined
+let shadowDepth = new Map<CullMode, Material>()
 
 /** The override material of a scene's shadow view (internal): one class
- * for the app, built on first use. */
-export function shadowDepthMaterial(): Material {
-  if (shadowDepth === undefined) {
-    shadowDepth = shaderMaterialClass({
+ * per cull mode for the app, built on first use. The default, "front",
+ * is the caster's back surface (see above); a material culling
+ * otherwise carries its own variant as Material.shadow. */
+export function shadowDepthMaterial(cull: CullMode = "front"): Material {
+  let material = shadowDepth.get(cull)
+  if (material === undefined) {
+    material = shaderMaterialClass({
       vertex: SHADOW_DEPTH_VERTEX,
       fragment: SHADOW_DEPTH_FRAGMENT,
-      cull: "front",
-      label: "scene-shadow-depth",
+      cull,
+      label: "scene-shadow-depth-" + cull,
     }).instance()
+    shadowDepth.set(cull, material)
   }
-  return shadowDepth
+  return material
+}
+
+/** The shadow pass's cull for a material's cull: the opposite side
+ * (Three's shadowSide default), none stays none. */
+function shadowCull(cull: CullMode): CullMode {
+  return cull === "none" ? "none" : cull === "back" ? "front" : "back"
+}
+
+/** "back" maps to the default depth material, so its variant is
+ * undefined. */
+function shadowVariant(cull: CullMode): Material | undefined {
+  return cull === "back" ? undefined : shadowDepthMaterial(shadowCull(cull))
+}
+
+// The cutout depth pass: the caster's map alpha (times its color alpha)
+// against its alphaTest, the lit fragment's test minus everything else.
+const SHADOW_CUTOUT_VERTEX = glsl`
+  in vec3 aPos;
+  in vec2 aUV;
+  out vec2 vUv;
+  uniform mat4 uModel;
+  uniform mat4 uViewProj;
+  void main() {
+    gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
+    vUv = aUV;
+  }
+`
+
+const SHADOW_CUTOUT_FRAGMENT = glsl`
+  in vec2 vUv;
+  uniform sampler2D uMap;
+  uniform vec4 uColor;
+  uniform float uAlphaTest;
+  void main() {
+    if (texture(uMap, vUv).a * uColor.a < uAlphaTest) discard;
+    fragColor = vec4(1.0);
+  }
+`
+
+let shadowCutout = new Map<CullMode, ShaderMaterialClass>()
+
+/** The shadow variant of a UV-mapped cutout material: one class per
+ * shadow cull mode, an instance per material (its map, color, cutoff). */
+function shadowCutoutMaterial(cull: CullMode, uColor: number[], uAlphaTest: number, uMap: TextureId): Material {
+  let cls = shadowCutout.get(cull)
+  if (cls === undefined) {
+    cls = shaderMaterialClass({
+      vertex: SHADOW_CUTOUT_VERTEX,
+      fragment: SHADOW_CUTOUT_FRAGMENT,
+      cull,
+      label: "scene-shadow-cutout-" + cull,
+    })
+    shadowCutout.set(cull, cls)
+  }
+  return cls.instance({ params: { uColor, uAlphaTest }, textures: { uMap } })
 }
 
 export type SpriteOptions = UnlitOptions & {
@@ -435,7 +536,7 @@ export function sprite(opts: SpriteOptions = {}): Material {
   if (cls === undefined) {
     cls = shaderMaterialClass({
       vertex: fixedY ? SPRITE_FIXED_Y_VERTEX_SRC : SPRITE_VERTEX_SRC,
-      fragment: map ? FRAGMENT_MAP_SRC : FRAGMENT_COLOR_SRC,
+      fragment: unlitFragment(map, false, transparent),
       transparent,
       cull: "none",
       label: "scene-sprite-" + key,
@@ -563,6 +664,10 @@ export type ShaderMaterialInstanceOptions = {
    * setMeshParams. */
   params?: ShaderParams
   textures?: TextureBindings
+  /** The depth variant a shadow view draws this instance with (see
+   * Material.shadow): a cutout's discard, an instanced class's vertex
+   * placement. Default: the depth pass with this class's cull side. */
+  shadow?: Material
 }
 
 export type ShaderMaterialOptions = ShaderMaterialClassOptions & ShaderMaterialInstanceOptions
@@ -609,6 +714,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   let normalMatrix = /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment)
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
   let depth = opts.depth ?? true
+  let cull = opts.cull ?? "back"
   // An empty list declares nothing - same as absent (the engine requires an
   // instance buffer exactly when attributes are declared).
   let instanceAttributes = opts.instanceAttributes?.length ? opts.instanceAttributes.map(a => ({ ...a })) : undefined
@@ -639,7 +745,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
         // only applies when there is one.
         depthWrite: opts.depthWrite ?? (transparent && depth ? false : undefined),
         blend: opts.blend ?? (transparent ? "alpha" : undefined),
-        cull: opts.cull ?? "back",
+        cull,
         topology: opts.topology,
         label: opts.label,
       })
@@ -649,7 +755,20 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   }
   return {
     instance(inst = {}) {
-      return { normalMatrix, attributes, transparent, instanceAttributes, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
+      return {
+        normalMatrix,
+        attributes,
+        transparent,
+        instanceAttributes,
+        pipeline: pipelineFor,
+        params: inst.params ?? {},
+        textures: inst.textures,
+        // Lazy: the depth materials are shaderMaterialClass instances
+        // themselves, so an eager variant would recurse into its own cache.
+        get shadow() {
+          return inst.shadow ?? shadowVariant(cull)
+        },
+      }
     },
     dispose() {
       for (let pipeline of pipelines.values()) destroyRenderPipeline(pipeline)

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
+}

package/src/model.ts

@@ -58,7 +58,13 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       label: label ? label + "-image" + i : undefined,
     })
   })
-  let make = opts.material ?? ((m: ModelMaterial, map: TextureId | null): Material => lit({ color: m.color, map: map ?? undefined, transparent: m.transparent }))
+  let make = opts.material ?? ((m: ModelMaterial, map: TextureId | null): Material => lit({
+        color: m.color,
+        map: map ?? undefined,
+        transparent: m.transparent,
+        cull: m.doubleSided ? "none" : "back",
+        alphaTest: m.alphaMode === "MASK" ? m.alphaCutoff : undefined,
+      }))
   let materials = data.materials.map((m) => make(m, m.map === null ? null : textures[m.map]!))
 
   let model = createGroup() as Model