reze-engine 0.58.1 → 0.58.3

package/src/engine.ts

@@ -59,6 +59,7 @@ import {
   type SceneFormats,
 } from "./shaders/passes/scene-contract"
 import {
+  LIGHT_GRID_BASE,
   LIGHT_HEADER,
   LIGHT_STRIDE,
   LIGHTS_FLOATS,
@@ -66,6 +67,7 @@ import {
   buildLightEmitShader,
   hasLightEmit,
 } from "./shaders/lights"
+import { buildLightGrid } from "./light-grid"
 import { groundShaderWgsl, GROUND_NOISE_BAKE_WGSL, GROUND_NOISE_SIZE } from "./shaders/passes/ground"
 import { outlineShaderWgsl, RZ_OUTLINE_DISSOLVE_OFFSET } from "./shaders/passes/outline"
 import { transparentDepthPrepassWgsl } from "./shaders/passes/depth-prepass"
@@ -114,9 +116,15 @@ import {
   buildParticleComputeShader,
   buildParticleRenderShader,
   PARTICLE_LIGHT_BINDING,
+  PARTICLE_POINTS_BINDING,
   particleEntryPoints,
+  PARTICLE_INDIRECT_BINDING,
+  PARTICLE_INDIRECT_BYTES,
+  PARTICLE_INDIRECT_DRAW_OFFSET,
   PARTICLE_STRIDE,
 } from "./shaders/passes/particles"
+import { MAX_EFFECT_POINTS, POINTS_FLOATS } from "./shaders/points-api"
+import { bonesWithPrefix, pointsData, writeBonePoint } from "./effect-points"
 import {
   SIM_FORMAT,
   GRID_MAX,
@@ -1446,7 +1454,16 @@ interface EffectParticles {
     computeBinds: [GPUBindGroup, GPUBindGroup]
     renderBinds: [GPUBindGroup, GPUBindGroup]
     mirrorRenderBinds: [GPUBindGroup, GPUBindGroup]
-  }
+    countBinds: [GPUBindGroup, GPUBindGroup] | null
+  }
+  /** `#points`: the bone-name prefix and the buffer its matches are written
+   *  to each frame. Null when the effect declared none — it then reads the
+   *  engine's empty fallback. */
+  points: { prefix: string; buffer: GPUBuffer; data: Float32Array } | null
+  /** `particleCount`: the kernel that writes the frame's live count and the
+   *  indirect arguments it writes them to. Null when the effect declared none —
+   *  the whole pool is then stepped and drawn. */
+  live: { pipeline: GPUComputePipeline; indirect: GPUBuffer; binds: [GPUBindGroup, GPUBindGroup] } | null
 }
 
 /**
@@ -2076,12 +2093,13 @@ export class Engine {
    * prefix sum and readback a compacted draw list would need every frame.
    */
   /** Ceiling for `#particles`. Past this an author is asking for a stall. */
-  // Raised for the lawn: 65536 blades at real density is a 40-unit patch and
-  // an 80-unit one wants four hundred thousand. A cutout pool's cost is
+  // Raised for the lawn: an 80-unit field at 36 blades a unit wants seven
+  // hundred thousand, and a turf one three million. A cutout pool's cost is
   // bounded by the pixels it covers, not by the count — the step is one
-  // compute invocation per slot, the pool buffer is 48 bytes each (24 MB at
-  // the cap), and a culled blade is a degenerate quad the rasteriser drops.
-  private static readonly MAX_PARTICLES = 524288
+  // compute invocation per slot, the pool buffer is 48 bytes each (96 MiB at
+  // the cap, under the 128 MiB a storage binding may be without asking for
+  // more), and a culled blade is a degenerate quad the rasteriser drops.
+  private static readonly MAX_PARTICLES = 2097152
   private particleFrame = 0
   /**
    * The installed effect's persistent grid, or null when it declared none.
@@ -2498,9 +2516,20 @@ export class Engine {
    *  Allocated once at full size and zero-filled, so "no lights" is a count of
    *  zero rather than an absent binding. */
   private lightsBuffer!: GPUBuffer
-  private lightsData!: Float32Array<ArrayBuffer>
-  /** Just the header, for rewriting the total without touching a record. */
+  /** What a particle effect with no `#points` reads at its points binding: a
+   *  count of zero. One buffer for all of them — nothing ever writes it. */
+  private pointsFallback!: GPUBuffer
+  /** Per model, per prefix, the bones `#points` matched. A rig's bones never
+   *  change after load, so the names are walked once rather than every frame. */
+  private pointBones = new WeakMap<Model, Map<string, number[]>>()
+  /** The CPU copy, from construction rather than init: a host sets a scene's
+   *  lamps as soon as its state exists, which can be before the device. */
+  private lightsData = new Float32Array(LIGHTS_FLOATS)
+  /** The same bytes as words — the grid's lamp bits are u32, not floats. */
+  private lightsWords = new Uint32Array(this.lightsData.buffer)
+  /** Just the header: the counts and the grid's placement. */
   private lightHeader = new Float32Array(LIGHT_HEADER)
+  private lightHeaderWords = new Uint32Array(this.lightHeader.buffer)
   /** How many of the slots belong to the DOCUMENT. Effects get what follows. */
   private docLightCount = 0
   private castData!: Float32Array<ArrayBuffer>
@@ -2634,7 +2663,9 @@ export class Engine {
   // GPU texture can't be read back cheaply, and PMX diffuse alpha is usually 1.0
   // even for see-through cloth: the translucency lives in the texture).
   private textureAlphaCache = new Map<string, { a: Uint8ClampedArray; w: number; h: number } | null>()
-  private mipBlitPipeline: GPURenderPipeline | null = null
+  /** One per format: a render pipeline is bound to its target's format, and
+   *  material textures are sRGB while a group's data maps are not. */
+  private mipBlitPipelines = new Map<GPUTextureFormat, GPURenderPipeline>()
   private mipBlitSampler: GPUSampler | null = null
   private _nextDefaultModelId = 0
 
@@ -4327,6 +4358,7 @@ export class Engine {
         e.particles.computeBinds = b.computeBinds
         e.particles.renderBinds = b.renderBinds
         e.particles.mirrorRenderBinds = b.mirrorRenderBinds
+        if (e.particles.live && b.countBinds) e.particles.live.binds = b.countBinds
       }
       if (e.grid) e.grid.binds = [this.gridBindGroup(e.grid, 0), this.gridBindGroup(e.grid, 1)]
       if (e.lights) e.lights.bind = this.lightEmitBindGroup(e.lights.layout, e.lights.uniform, e.lights.params)
@@ -4864,6 +4896,8 @@ export class Engine {
       paramsBuffer?.destroy()
       particles?.buffer.destroy()
       particles?.uniform.destroy()
+      particles?.points?.buffer.destroy()
+      particles?.live?.indirect.destroy()
       grid?.textures[0].destroy()
       grid?.textures[1].destroy()
       grid?.uniform.destroy()
@@ -5246,8 +5280,20 @@ export class Engine {
       paramsDecl: params.wgsl(EFFECT_PARAMS_BINDING),
       gridSize: grid?.size ?? 0,
       cover: particleEntryPoints(wgsl).cover,
+      live: particleEntryPoints(wgsl).count,
     }
     const prepass = src.blend === "cutout" && src.cover
+    const points = d.points
+      ? {
+          prefix: d.points,
+          buffer: this.device.createBuffer({
+            label: `points "${d.points}"`,
+            size: POINTS_FLOATS * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+          }),
+          data: pointsData(),
+        }
+      : null
     // Sparks want to spawn where a trail is, so the particle stages see the same
     // cast buffer the trail draw reads.
     const cast = {
@@ -5274,9 +5320,15 @@ export class Engine {
     }
 
     const computeModule = await compile(buildParticleComputeShader(src, cast), "particle compute")
-    if (Array.isArray(computeModule)) return { ok: false, diagnostics: computeModule }
+    if (Array.isArray(computeModule)) {
+      points?.buffer.destroy()
+      return { ok: false, diagnostics: computeModule }
+    }
     const renderModule = await compile(buildParticleRenderShader(src, cast), "particle render")
-    if (Array.isArray(renderModule)) return { ok: false, diagnostics: renderModule }
+    if (Array.isArray(renderModule)) {
+      points?.buffer.destroy()
+      return { ok: false, diagnostics: renderModule }
+    }
 
     // COPY_DST so a scheduled effect can empty its pool when its window starts.
     const buffer = this.device.createBuffer({
@@ -5294,6 +5346,16 @@ export class Engine {
     })
     const uniformBytes = new ArrayBuffer(32)
     const uniformView = { floats: new Float32Array(uniformBytes), uints: new Uint32Array(uniformBytes) }
+    // The live count's arguments — written by rzCount, read by the step's
+    // dispatch and the quads' draws. Zero until the first step, so a pool
+    // drawn before it has stepped draws nothing rather than everything.
+    const indirect = src.live
+      ? this.device.createBuffer({
+          label: "particle indirect",
+          size: PARTICLE_INDIRECT_BYTES,
+          usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
+        })
+      : null
 
     // Visibility is per LAYOUT, not shared: a read_write storage buffer may not be
     // visible to the vertex stage at all (WebGPU forbids it — a vertex shader
@@ -5301,7 +5363,7 @@ export class Engine {
     // Declaring one set of flags for both layouts is what made the pipeline
     // layout invalid, and the error surfaces later and unhelpfully as "invalid
     // due to a previous error".
-    const layoutFor = (storage: GPUBufferBindingType, visibility: number, shadow: boolean) =>
+    const layoutFor = (storage: GPUBufferBindingType, visibility: number, shadow: boolean, withIndirect: boolean) =>
       this.device.createBindGroupLayout({
         entries: [
           { binding: 0, visibility, buffer: { type: storage } },
@@ -5321,6 +5383,9 @@ export class Engine {
           // author calls it or not. With no grid it is the 1x1 of zeroes.
           { binding: 8, visibility, texture: { sampleType: "float" as const } },
           { binding: 9, visibility, sampler: { type: "filtering" as const } },
+          // The named points, ALWAYS, for the grid's reason: the accessor is
+          // compiled in whether or not the effect declared #points.
+          { binding: PARTICLE_POINTS_BINDING, visibility, buffer: { type: "read-only-storage" as const } },
           // The scene's light, for rzShadow and rzWorldAmbient — the shading
           // stage only; the compute module compiles the stubs. See
           // scene-light-api.ts.
@@ -5333,13 +5398,21 @@ export class Engine {
                 { binding: PARTICLE_LIGHT_BINDING + 4, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "comparison" as const } },
               ]
             : []),
+          // The live count's arguments, for the COUNT kernel's layout alone. The
+          // step's layout must not carry them: a bound group's entries count
+          // toward a pass's usage whether the shader reads them or not, and a
+          // buffer may not be writable storage and indirect arguments in one
+          // pass.
+          ...(withIndirect
+            ? [{ binding: PARTICLE_INDIRECT_BINDING, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" as const } }]
+            : []),
         ],
       })
     /** One per GRID PARITY, for the reason rebuildFieldBindGroup gives: the grid
      *  alternates which texture is current, and rebuilding a single group every
      *  frame is waste for a change that only ever toggles between two known
      *  states. Both entries are the same view when there is no grid. */
-    const bindFor = (layout: GPUBindGroupLayout, camera: GPUBuffer, shadow: boolean) =>
+    const bindFor = (layout: GPUBindGroupLayout, camera: GPUBuffer, shadow: boolean, withIndirect: boolean) =>
       [0, 1].map((parity) =>
         this.device.createBindGroup({
           layout,
@@ -5354,6 +5427,7 @@ export class Engine {
             ...(params.buffer ? [{ binding: 7, resource: { buffer: params.buffer } }] : []),
             { binding: 8, resource: grid ? grid.read[parity] : this.simFallbackView },
             { binding: 9, resource: this.simSampler },
+            { binding: PARTICLE_POINTS_BINDING, resource: { buffer: points?.buffer ?? this.pointsFallback } },
             ...(shadow
               ? [
                   { binding: PARTICLE_LIGHT_BINDING, resource: { buffer: this.lightUniformBuffer } },
@@ -5363,12 +5437,14 @@ export class Engine {
                   { binding: PARTICLE_LIGHT_BINDING + 4, resource: this.shadowComparisonSampler },
                 ]
               : []),
+            ...(withIndirect && indirect ? [{ binding: PARTICLE_INDIRECT_BINDING, resource: { buffer: indirect } }] : []),
           ],
         }),
       ) as [GPUBindGroup, GPUBindGroup]
 
-    const computeLayout = layoutFor("storage", GPUShaderStage.COMPUTE, false)
-    const renderLayout = layoutFor("read-only-storage", GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, true)
+    const computeLayout = layoutFor("storage", GPUShaderStage.COMPUTE, false, false)
+    const countLayout = indirect ? layoutFor("storage", GPUShaderStage.COMPUTE, false, true) : null
+    const renderLayout = layoutFor("read-only-storage", GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, true, false)
 
     // Additive keeps the destination and adds to it, and leaves alpha alone, so
     // a glow does not claim coverage it never occluded. The MASK sums with it —
@@ -5383,11 +5459,24 @@ export class Engine {
 
     this.device.pushErrorScope("validation")
     try {
+      const computePipelineLayout = this.device.createPipelineLayout({ bindGroupLayouts: [computeLayout] })
       const compute = await this.device.createComputePipelineAsync({
         label: "particle compute pipeline",
-        layout: this.device.createPipelineLayout({ bindGroupLayouts: [computeLayout] }),
+        layout: computePipelineLayout,
         compute: { module: computeModule, entryPoint: "main" },
       })
+      const live =
+        indirect && countLayout
+          ? {
+              pipeline: await this.device.createComputePipelineAsync({
+                label: "particle count pipeline",
+                layout: this.device.createPipelineLayout({ bindGroupLayouts: [countLayout] }),
+                compute: { module: computeModule, entryPoint: "rzCount" },
+              }),
+              indirect,
+              binds: bindFor(countLayout, this.cameraUniformBuffer, false, true),
+            }
+          : null
       const renderLayoutObj = this.device.createPipelineLayout({ bindGroupLayouts: [renderLayout] })
       // The prepass, when the effect gave the cutout a cheap shape: coverage to
       // depth, colour targets at writeMask 0 (the depth-prepass class), and
@@ -5429,6 +5518,8 @@ export class Engine {
       if (scoped) {
         buffer.destroy()
         uniform.destroy()
+        points?.buffer.destroy()
+        indirect?.destroy()
         return { ok: false, diagnostics: [scoped.message] }
       }
       return {
@@ -5444,23 +5535,28 @@ export class Engine {
           counts: uniformView.uints,
           compute,
           computeLayout,
-          computeBinds: bindFor(computeLayout, this.cameraUniformBuffer, false),
+          computeBinds: bindFor(computeLayout, this.cameraUniformBuffer, false, false),
           depth,
           render,
           renderLayout,
-          renderBinds: bindFor(renderLayout, this.cameraUniformBuffer, true),
-          mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer, true),
+          renderBinds: bindFor(renderLayout, this.cameraUniformBuffer, true, false),
+          mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer, true, false),
           rebind: () => ({
-            computeBinds: bindFor(computeLayout, this.cameraUniformBuffer, false),
-            renderBinds: bindFor(renderLayout, this.cameraUniformBuffer, true),
-            mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer, true),
+            computeBinds: bindFor(computeLayout, this.cameraUniformBuffer, false, false),
+            renderBinds: bindFor(renderLayout, this.cameraUniformBuffer, true, false),
+            mirrorRenderBinds: bindFor(renderLayout, this.mirrorCameraBuffer, true, false),
+            countBinds: countLayout ? bindFor(countLayout, this.cameraUniformBuffer, false, true) : null,
           }),
+          points,
+          live,
         },
       }
     } catch (e) {
       await this.device.popErrorScope()
       buffer.destroy()
       uniform.destroy()
+      points?.buffer.destroy()
+      indirect?.destroy()
       return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)] }
     }
   }
@@ -5591,6 +5687,7 @@ export class Engine {
       this.device.queue.writeBuffer(e.lights.uniform, 0, e.lights.data.buffer as ArrayBuffer)
     }
     this.lightHeader[0] = Math.min(next, MAX_LIGHTS)
+    this.lightHeader[1] = this.docLightCount
     this.device.queue.writeBuffer(this.lightsBuffer, 0, this.lightHeader)
   }
 
@@ -5651,14 +5748,56 @@ export class Engine {
       p.counts[2] = p.count
       p.counts[3] = this.particleFrame++
       this.device.queue.writeBuffer(p.uniform, 0, p.data.buffer as ArrayBuffer)
+      if (p.points) this.writePoints(p.points)
+      const bind = p.computeBinds[e.grid?.parity ?? 0]
+      if (p.live) {
+        // The frame's live count first, in a pass of its own: a buffer may
+        // not be written as storage and read as indirect arguments inside one
+        // pass, and a pass is the synchronization scope.
+        const count = encoder.beginComputePass({ label: "particle count" })
+        count.setPipeline(p.live.pipeline)
+        count.setBindGroup(0, p.live.binds[e.grid?.parity ?? 0])
+        count.dispatchWorkgroups(1)
+        count.end()
+      }
       const cp = encoder.beginComputePass({ label: "particles" })
       cp.setPipeline(p.compute)
-      cp.setBindGroup(0, p.computeBinds[e.grid?.parity ?? 0])
-      cp.dispatchWorkgroups(Math.ceil(p.count / 64))
+      cp.setBindGroup(0, bind)
+      if (p.live) cp.dispatchWorkgroupsIndirect(p.live.indirect, 0)
+      else cp.dispatchWorkgroups(Math.ceil(p.count / 64))
       cp.end()
     }
   }
 
+  /**
+   * Every bone matching an effect's `#points` prefix, on every visible model,
+   * posed and placed this frame. Every frame rather than on load: a candle a
+   * character carries moves with the hand, and a stage can be moved.
+   *
+   * The order is the models' order, then rig order — stable while nothing is
+   * added or removed, so particle i stays on point i and a flame does not
+   * jump to another wick between frames.
+   */
+  private writePoints(points: { prefix: string; buffer: GPUBuffer; data: Float32Array }): void {
+    let n = 0
+    for (const inst of this.modelInstances.values()) {
+      const m = inst.model
+      if (!m.visible) continue
+      let byPrefix = this.pointBones.get(m)
+      if (!byPrefix) this.pointBones.set(m, (byPrefix = new Map()))
+      let bones = byPrefix.get(points.prefix)
+      const rig = m.getSkeleton().bones
+      if (!bones) byPrefix.set(points.prefix, (bones = bonesWithPrefix(rig, points.prefix)))
+      for (const i of bones) {
+        if (n >= MAX_EFFECT_POINTS) break
+        const world = m.getBoneWorldMatrixAt(i)
+        if (world) writeBonePoint(points.data, n++, world, rig[i].tail, m)
+      }
+    }
+    points.data[0] = n
+    this.device.queue.writeBuffer(points.buffer, 0, points.data.buffer as ArrayBuffer, 0, (4 + n * 8) * 4)
+  }
+
   /** Draw the pool. Inside the scene pass, so it is depth-tested and pre-bloom. */
   private renderParticles(pass: GPURenderPassEncoder, view: "camera" | "mirror"): void {
     for (const e of this.effects) {
@@ -5666,14 +5805,19 @@ export class Engine {
       if (!p || e.weight === 0) continue
       const parity = e.grid?.parity ?? 0
       const bind = view === "mirror" ? p.mirrorRenderBinds[parity] : p.renderBinds[parity]
+      // The live count's quads when the effect declared one, else the pool's.
+      const draw = () => {
+        if (p.live) pass.drawIndirect(p.live.indirect, PARTICLE_INDIRECT_DRAW_OFFSET)
+        else pass.draw(6, p.count)
+      }
       if (p.depth) {
         pass.setPipeline(p.depth)
         pass.setBindGroup(0, bind)
-        pass.draw(6, p.count)
+        draw()
       }
       pass.setPipeline(p.render)
       pass.setBindGroup(0, bind)
-      pass.draw(6, p.count)
+      draw()
     }
   }
 
@@ -6051,6 +6195,8 @@ export class Engine {
     for (const e of this.effects) {
       e.particles?.buffer.destroy()
       e.particles?.uniform.destroy()
+      e.particles?.points?.buffer.destroy()
+      e.particles?.live?.indirect.destroy()
       e.particles = null
     }
   }
@@ -7488,15 +7634,21 @@ export class Engine {
 
     // BEFORE the bind group below, which binds it. Full size from the start:
     // every material pipeline binds this, so sizing it to the light count would
-    // mean rebuilding bind groups whenever a scene gained a lamp. Zero-filled,
-    // and float 0 is a count of 0.
-    this.lightsData = new Float32Array(LIGHTS_FLOATS)
+    // mean rebuilding bind groups whenever a scene gained a lamp. Uploaded from
+    // the CPU copy, which holds any lamps set before the device existed; the
+    // header after it, from the one writer that owns it.
     this.lightsBuffer = this.device.createBuffer({
       label: "positional lights",
       size: this.lightsData.byteLength,
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
     })
     this.device.queue.writeBuffer(this.lightsBuffer, 0, this.lightsData)
+    this.allocateLightSlots()
+    this.pointsFallback = this.device.createBuffer({
+      label: "no points",
+      size: 16,
+      usage: GPUBufferUsage.STORAGE,
+    })
     // BEFORE the per-frame groups, which bind it. The composite needs this 1x1
     // stand-in too, and it used to be created with the composite's own
     // resources further down — far enough down that a material group built up
@@ -10047,6 +10199,20 @@ export class Engine {
       this.lightsData[b + 14] = 0
       this.lightsData[b + 15] = 0
     }
+    // The grid, from the records as STORED — normalised aim, clamped reach, the
+    // cosines in f32 — so it indexes exactly what the shader will evaluate.
+    const grid = buildLightGrid(
+      list.map((_, i) => {
+        const b = LIGHT_HEADER + i * LIGHT_STRIDE
+        const d = this.lightsData
+        return { x: d[b], y: d[b + 1], z: d[b + 2], radius: d[b + 3], ax: d[b + 8], ay: d[b + 9], az: d[b + 10], cosOuter: d[b + 11] }
+      }),
+    )
+    this.lightHeader.set(grid.origin, 4)
+    this.lightHeader[7] = 1 / grid.cell
+    this.lightHeaderWords.set(grid.dims, 8)
+    this.lightHeaderWords.set(grid.outside, 12)
+    this.lightsWords.set(grid.cells, LIGHT_GRID_BASE)
     // The CPU copy is written either way; only the upload needs a device. A
     // scene whose lamps arrive before init keeps them, and init uploads them.
     if (list.length && this.device && this.lightsBuffer) {
@@ -10057,6 +10223,13 @@ export class Engine {
         LIGHT_HEADER * 4,
         list.length * LIGHT_STRIDE * 4,
       )
+      this.device.queue.writeBuffer(
+        this.lightsBuffer,
+        LIGHT_GRID_BASE * 4,
+        this.lightsData.buffer as ArrayBuffer,
+        LIGHT_GRID_BASE * 4,
+        grid.cells.byteLength,
+      )
     }
     // The effects' bases move when the document's count does; the header —
     // count included — is written there.
@@ -11621,9 +11794,11 @@ export class Engine {
       const src = wrapped ? entry.source : entry
       const width = Math.max(1, "naturalWidth" in src ? src.naturalWidth : src.width)
       const height = Math.max(1, "naturalHeight" in src ? src.naturalHeight : src.height)
+      const mipLevelCount = wrapped && entry.mipmaps ? Math.floor(Math.log2(Math.max(width, height))) + 1 : 1
       const tex = this.device.createTexture({
         label: `group map: ${group.id}`,
         size: [width, height],
+        mipLevelCount,
         // Colour maps decode to linear on sample, the way material textures do;
         // data maps must not, or every threshold packed in their channels moves.
         format: wrapped && entry.srgb ? "rgba8unorm-srgb" : "rgba8unorm",
@@ -11634,6 +11809,7 @@ export class Engine {
         { texture: tex, premultipliedAlpha: wrapped && entry.premultiplied === true },
         [width, height],
       )
+      if (mipLevelCount > 1) this.generateMipmaps(tex, mipLevelCount)
       return tex
     })
   }
@@ -14137,24 +14313,28 @@ export class Engine {
   // Bilinear box-filter downsample per level. Reads srgb view (hardware linearizes on sample,
   // re-encodes on write), so intensities are filtered in linear space — matching EEVEE/Blender.
   private generateMipmaps(texture: GPUTexture, mipLevelCount: number) {
-    if (!this.mipBlitPipeline || !this.mipBlitSampler) {
+    if (!this.mipBlitSampler) {
       this.mipBlitSampler = this.device.createSampler({
         magFilter: "linear",
         minFilter: "linear",
         addressModeU: "clamp-to-edge",
         addressModeV: "clamp-to-edge",
       })
+    }
+    let pipeline = this.mipBlitPipelines.get(texture.format)
+    if (!pipeline) {
       const module = this.device.createShaderModule({
         label: "mipmap blit",
         code: MIPMAP_BLIT_SHADER_WGSL,
       })
-      this.mipBlitPipeline = this.device.createRenderPipeline({
-        label: "mipmap blit pipeline",
+      pipeline = this.device.createRenderPipeline({
+        label: `mipmap blit pipeline (${texture.format})`,
         layout: "auto",
         vertex: { module, entryPoint: "vs" },
-        fragment: { module, entryPoint: "fs", targets: [{ format: "rgba8unorm-srgb" }] },
+        fragment: { module, entryPoint: "fs", targets: [{ format: texture.format }] },
         primitive: { topology: "triangle-list" },
       })
+      this.mipBlitPipelines.set(texture.format, pipeline)
     }
 
     const encoder = this.device.createCommandEncoder({ label: "mipgen" })
@@ -14162,7 +14342,7 @@ export class Engine {
       const srcView = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 })
       const dstView = texture.createView({ baseMipLevel: level, mipLevelCount: 1 })
       const bindGroup = this.device.createBindGroup({
-        layout: this.mipBlitPipeline.getBindGroupLayout(0),
+        layout: pipeline.getBindGroupLayout(0),
         entries: [
           { binding: 0, resource: srcView },
           { binding: 1, resource: this.mipBlitSampler },
@@ -14173,7 +14353,7 @@ export class Engine {
           { view: dstView, clearValue: { r: 0, g: 0, b: 0, a: 0 }, loadOp: "clear", storeOp: "store" },
         ],
       })
-      pass.setPipeline(this.mipBlitPipeline)
+      pass.setPipeline(pipeline)
       pass.setBindGroup(0, bindGroup)
       pass.draw(3)
       pass.end()

package/src/graph/style-group.ts

@@ -80,7 +80,18 @@ export type GroupImageSource = ImageBitmap | HTMLImageElement | HTMLCanvasElemen
  * converts to the destination's tagged alpha mode, so a premultiplied ImageBitmap
  * copied into an untagged texture is un-premultiplied again on the way in.
  */
-export type GroupImage = { source: GroupImageSource; srgb?: boolean; premultiplied?: boolean }
+export type GroupImage = {
+  source: GroupImageSource
+  srgb?: boolean
+  premultiplied?: boolean
+  /**
+   * Give it a mip chain. For a map TILED across a surface — a relief map, a
+   * water's ripples — whose far tiles otherwise shrink to a pixel each and
+   * sample as noise that sparkles with every camera move. Off by default: a
+   * ramp read at a computed coordinate would blur at its own terminator.
+   */
+  mipmaps?: boolean
+}
 
 export type GroupDiagnostic = { groupId: string; diagnostics: Diagnostic[]; ok: boolean }