reze-engine 0.58.1 → 0.58.3

package/dist/engine.js

@@ -29,7 +29,8 @@ import { packHalf } from "./hdr";
 import { evalIrradianceSH, projectIrradianceSH, gradientIrradianceSH } from "./ibl";
 import { LYRIC_ATLAS_MAX_H, LYRIC_ATLAS_MAX_W, LYRICS_FLOATS, packLyrics } from "./shaders/lyrics-api";
 import { sceneTargets as sceneTargetsFor, sceneColorFormats, setMrtIds, mrtIdsEnabled, SCENE_ID_FORMAT, } from "./shaders/passes/scene-contract";
-import { LIGHT_HEADER, LIGHT_STRIDE, LIGHTS_FLOATS, MAX_LIGHTS, buildLightEmitShader, hasLightEmit, } from "./shaders/lights";
+import { LIGHT_GRID_BASE, LIGHT_HEADER, LIGHT_STRIDE, LIGHTS_FLOATS, MAX_LIGHTS, 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";
@@ -41,7 +42,9 @@ import { boneOverlay, boneMarkerPositions, buildOverlayShapes, jointOverlay, lin
 import { BLOOM_BLIT_SHADER_WGSL, BLOOM_DOWNSAMPLE_SHADER_WGSL, BLOOM_UPSAMPLE_SHADER_WGSL, } from "./shaders/passes/bloom";
 import { AGX_LUT_GZ, AGX_LUT_SIZE } from "./shaders/agx-lut";
 import { buildCompositeShader, EFFECT_SCENE_API, buildFieldShader, EFFECT_ANCHORS, EFFECT_SUBJECTS, EFFECT_TRAIL_BASE, EFFECT_TRAIL_SAMPLES, } from "./shaders/passes/composite";
-import { buildParticleComputeShader, buildParticleRenderShader, PARTICLE_LIGHT_BINDING, particleEntryPoints, PARTICLE_STRIDE, } from "./shaders/passes/particles";
+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, buildSimShader, gridEntryPoint, } from "./shaders/passes/grid";
 import { buildCastResolveShader, buildCastSeedShader, buildCastStepShader, castDistanceUsed, CAST_COVERAGE_FORMAT, CAST_DIST_FORMAT, CAST_FIELD_DIV, CAST_SEED_FORMAT, } from "./shaders/passes/cast-distance";
 import { buildTrailShader, trailEntryPoints, TRAIL_SUBDIVISIONS } from "./shaders/passes/trails";
@@ -1077,8 +1080,17 @@ export class Engine {
          *  effect is on 今汐" into a bit the shaders can read. */
         this.castSlotOf = new Map();
         this.effects = [];
-        /** Just the header, for rewriting the total without touching a record. */
+        /** 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. */
+        this.pointBones = new WeakMap();
+        /** 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. */
+        this.lightsData = new Float32Array(LIGHTS_FLOATS);
+        /** The same bytes as words — the grid's lamp bits are u32, not floats. */
+        this.lightsWords = new Uint32Array(this.lightsData.buffer);
+        /** Just the header: the counts and the grid's placement. */
         this.lightHeader = new Float32Array(LIGHT_HEADER);
+        this.lightHeaderWords = new Uint32Array(this.lightHeader.buffer);
         /** How many of the slots belong to the DOCUMENT. Effects get what follows. */
         this.docLightCount = 0;
         /** Last frame's anchor world positions, for velocity. Keyed model id → slot. */
@@ -1151,7 +1163,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).
         this.textureAlphaCache = new Map();
-        this.mipBlitPipeline = 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. */
+        this.mipBlitPipelines = new Map();
         this.mipBlitSampler = null;
         this._nextDefaultModelId = 0;
         // IK and physics enabled at engine level (same for all models)
@@ -3044,6 +3058,8 @@ 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)];
@@ -3568,6 +3584,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();
@@ -3921,8 +3939,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 = {
@@ -3948,11 +3978,15 @@ export class Engine {
             return diagnostics.length ? diagnostics : module;
         };
         const computeModule = await compile(buildParticleComputeShader(src, cast), "particle compute");
-        if (Array.isArray(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))
+        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({
             label: "particle pool",
@@ -3969,13 +4003,23 @@ 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
         // that could write memory has no defined ordering against the rasteriser).
         // 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, visibility, shadow) => this.device.createBindGroupLayout({
+        const layoutFor = (storage, visibility, shadow, withIndirect) => this.device.createBindGroupLayout({
             entries: [
                 { binding: 0, visibility, buffer: { type: storage } },
                 { binding: 1, visibility, buffer: { type: "uniform" } },
@@ -3994,6 +4038,9 @@ export class Engine {
                 // author calls it or not. With no grid it is the 1x1 of zeroes.
                 { binding: 8, visibility, texture: { sampleType: "float" } },
                 { binding: 9, visibility, sampler: { type: "filtering" } },
+                // 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" } },
                 // The scene's light, for rzShadow and rzWorldAmbient — the shading
                 // stage only; the compute module compiles the stubs. See
                 // scene-light-api.ts.
@@ -4006,13 +4053,21 @@ export class Engine {
                         { binding: PARTICLE_LIGHT_BINDING + 4, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "comparison" } },
                     ]
                     : []),
+                // 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" } }]
+                    : []),
             ],
         });
         /** 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, camera, shadow) => [0, 1].map((parity) => this.device.createBindGroup({
+        const bindFor = (layout, camera, shadow, withIndirect) => [0, 1].map((parity) => this.device.createBindGroup({
             layout,
             entries: [
                 { binding: 0, resource: { buffer } },
@@ -4025,6 +4080,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 } },
@@ -4034,10 +4090,12 @@ export class Engine {
                         { binding: PARTICLE_LIGHT_BINDING + 4, resource: this.shadowComparisonSampler },
                     ]
                     : []),
+                ...(withIndirect && indirect ? [{ binding: PARTICLE_INDIRECT_BINDING, resource: { buffer: indirect } }] : []),
             ],
         }));
-        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 —
         // otherwise an additive effect could never reach the bloom gate. Both live
@@ -4050,11 +4108,23 @@ export class Engine {
         const cutout = src.blend === "cutout";
         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
@@ -4096,6 +4166,8 @@ export class Engine {
             if (scoped) {
                 buffer.destroy();
                 uniform.destroy();
+                points?.buffer.destroy();
+                indirect?.destroy();
                 return { ok: false, diagnostics: [scoped.message] };
             }
             return {
@@ -4111,17 +4183,20 @@ 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,
                 },
             };
         }
@@ -4129,6 +4204,8 @@ export class Engine {
             await this.device.popErrorScope();
             buffer.destroy();
             uniform.destroy();
+            points?.buffer.destroy();
+            indirect?.destroy();
             return { ok: false, diagnostics: [e instanceof Error ? e.message : String(e)] };
         }
     }
@@ -4249,6 +4326,7 @@ export class Engine {
             this.device.queue.writeBuffer(e.lights.uniform, 0, e.lights.data.buffer);
         }
         this.lightHeader[0] = Math.min(next, MAX_LIGHTS);
+        this.lightHeader[1] = this.docLightCount;
         this.device.queue.writeBuffer(this.lightsBuffer, 0, this.lightHeader);
     }
     /** Run every effect's lightEmit, before the pass that reads the result. */
@@ -4311,13 +4389,62 @@ export class Engine {
             p.counts[2] = p.count;
             p.counts[3] = this.particleFrame++;
             this.device.queue.writeBuffer(p.uniform, 0, p.data.buffer);
+            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.
+     */
+    writePoints(points) {
+        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, 0, (4 + n * 8) * 4);
+    }
     /** Draw the pool. Inside the scene pass, so it is depth-tested and pre-bloom. */
     renderParticles(pass, view) {
         for (const e of this.effects) {
@@ -4326,14 +4453,21 @@ export class Engine {
                 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();
         }
     }
     /**
@@ -4699,6 +4833,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;
         }
     }
@@ -6062,15 +6198,21 @@ export class Engine {
         this.bakeFilmicLut();
         // 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
@@ -8418,10 +8560,23 @@ 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) {
             this.device.queue.writeBuffer(this.lightsBuffer, LIGHT_HEADER * 4, this.lightsData.buffer, LIGHT_HEADER * 4, list.length * LIGHT_STRIDE * 4);
+            this.device.queue.writeBuffer(this.lightsBuffer, LIGHT_GRID_BASE * 4, this.lightsData.buffer, LIGHT_GRID_BASE * 4, grid.cells.byteLength);
         }
         // The effects' bases move when the document's count does; the header —
         // count included — is written there.
@@ -9849,15 +10004,19 @@ 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",
                 usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
             });
             this.device.queue.copyExternalImageToTexture({ source: src }, { texture: tex, premultipliedAlpha: wrapped && entry.premultiplied === true }, [width, height]);
+            if (mipLevelCount > 1)
+                this.generateMipmaps(tex, mipLevelCount);
             return tex;
         });
     }
@@ -12127,31 +12286,35 @@ 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.
     generateMipmaps(texture, mipLevelCount) {
-        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" });
         for (let level = 1; level < mipLevelCount; level++) {
             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 },
@@ -12162,7 +12325,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();
@@ -14987,12 +15150,13 @@ Engine.JIGGLE_DAMPING_SCALE = 0.5;
  * 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.
-Engine.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.
+Engine.MAX_PARTICLES = 2097152;
 /**
  * The field layer: user background/foreground mounts, ONE TARGET PAIR PER
  * RESOLUTION. Index 0 is full, index 1 is half — coarsest last, so the

package/dist/graph/style-group.d.ts

@@ -75,6 +75,13 @@ 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;

package/dist/graph/style-group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"style-group.d.ts","sourceRoot":"","sources":["../../src/graph/style-group.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,MAAM,MAAM,UAAU,GAAG;IACvB,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAA;IACV;2CACuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,sFAAsF;IACtF,KAAK,EAAE,WAAW,CAAA;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,wEAAwE;IACxE,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,CAAC,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAAC,EAAE,CAAA;IACjD;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAAC,EAAE,CAAC,CAAA;CAC5E,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,gBAAgB,GAAG,iBAAiB,CAAA;AAEjF;;;;;;;;;;;;GAYG;AACH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAE9F,MAAM,MAAM,eAAe,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAA;AAEzF,MAAM,MAAM,sBAAsB,GAAG;IACnC,sCAAsC;IACtC,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,kFAAkF;IAClF,SAAS,EAAE,MAAM,EAAE,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAC;IAAC,OAAO,EAAE,SAAS,EAAE,CAAA;CAAE,CAAA"}
+{"version":3,"file":"style-group.d.ts","sourceRoot":"","sources":["../../src/graph/style-group.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C,MAAM,MAAM,UAAU,GAAG;IACvB,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAA;IACV;2CACuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,sFAAsF;IACtF,KAAK,EAAE,WAAW,CAAA;IAClB,uEAAuE;IACvE,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,wEAAwE;IACxE,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,CAAC,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAAC,EAAE,CAAA;IACjD;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAAC,EAAE,CAAC,CAAA;CAC5E,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,gBAAgB,GAAG,iBAAiB,CAAA;AAEjF;;;;;;;;;;;;GAYG;AACH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,gBAAgB,CAAA;IACxB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,CAAA;AAEzF,MAAM,MAAM,sBAAsB,GAAG;IACnC,sCAAsC;IACtC,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,eAAe,EAAE,CAAA;IACzB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,kFAAkF;IAClF,SAAS,EAAE,MAAM,EAAE,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,UAAU,EAAE,CAAC;IAAC,OAAO,EAAE,SAAS,EAAE,CAAA;CAAE,CAAA"}

package/dist/light-grid.d.ts

@@ -0,0 +1,25 @@
+/** One document lamp, as the grid sees it. */
+export type GridLamp = {
+    x: number;
+    y: number;
+    z: number;
+    radius: number;
+    /** Unit aim, away from the lamp. Zero for a point lamp. */
+    ax: number;
+    ay: number;
+    az: number;
+    /** Cosine of the half-angle. -1 for a point lamp, which covers everything. */
+    cosOuter: number;
+};
+export type LightGrid = {
+    origin: [number, number, number];
+    /** Edge length of one cubic cell, world units. */
+    cell: number;
+    dims: [number, number, number];
+    /** The lamps that reach past the box, for fragments outside it. */
+    outside: Uint32Array;
+    /** LIGHT_MASK_WORDS words per cell, x fastest, then y, then z. */
+    cells: Uint32Array;
+};
+export declare function buildLightGrid(lamps: GridLamp[], maxCells?: number): LightGrid;
+//# sourceMappingURL=light-grid.d.ts.map

package/dist/light-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light-grid.d.ts","sourceRoot":"","sources":["../src/light-grid.ts"],"names":[],"mappings":"AA2BA,8CAA8C;AAC9C,MAAM,MAAM,QAAQ,GAAG;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,MAAM,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,mEAAmE;IACnE,OAAO,EAAE,WAAW,CAAA;IACpB,kEAAkE;IAClE,KAAK,EAAE,WAAW,CAAA;CACnB,CAAA;AAMD,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,QAAQ,SAAmB,GAAG,SAAS,CAkFxF"}

package/dist/light-grid.js

@@ -0,0 +1,91 @@
+import { LIGHT_GRID_CELLS, LIGHT_MASK_WORDS } from "./shaders/lights";
+function setBit(words, base, lamp) {
+    words[base + (lamp >> 5)] |= 1 << (lamp & 31);
+}
+export function buildLightGrid(lamps, maxCells = LIGHT_GRID_CELLS) {
+    const outside = new Uint32Array(LIGHT_MASK_WORDS);
+    const live = lamps
+        .map((l, i) => ({ l, i }))
+        .filter(({ l }) => l.radius > 0 && [l.x, l.y, l.z, l.radius].every(Number.isFinite));
+    if (!live.length)
+        return { origin: [0, 0, 0], cell: 1, dims: [0, 0, 0], outside, cells: new Uint32Array(0) };
+    const radii = live.map(({ l }) => l.radius).sort((a, b) => a - b);
+    const pad = radii[radii.length >> 1];
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    for (const { l } of live) {
+        const p = [l.x, l.y, l.z];
+        for (let k = 0; k < 3; k++) {
+            min[k] = Math.min(min[k], p[k] - pad);
+            max[k] = Math.max(max[k], p[k] + pad);
+        }
+    }
+    const extent = [max[0] - min[0], max[1] - min[1], max[2] - min[2]];
+    let cell = Math.cbrt((extent[0] * extent[1] * extent[2]) / maxCells);
+    let dims;
+    // ceil() rounds every axis up, so the first guess can overshoot the budget by
+    // a few percent; widen the cell until it fits.
+    for (;;) {
+        dims = [0, 1, 2].map((k) => Math.max(1, Math.ceil(extent[k] / cell)));
+        if (dims[0] * dims[1] * dims[2] <= maxCells)
+            break;
+        cell *= 1.02;
+    }
+    const cells = new Uint32Array(dims[0] * dims[1] * dims[2] * LIGHT_MASK_WORDS);
+    // Half the cell's diagonal: the sphere a spot's cone is tested against.
+    const halfDiagonal = (cell * Math.sqrt(3)) / 2;
+    for (const { l, i } of live) {
+        // A hair of slack on the reach: the shader finds its cell in f32 from a
+        // reciprocal, the builder in f64 from a division, and a fragment on a cell
+        // face may land in either neighbour.
+        const r = l.radius + cell * 1e-4;
+        const p = [l.x, l.y, l.z];
+        const lo = [0, 0, 0];
+        const hi = [0, 0, 0];
+        let leaves = false;
+        for (let k = 0; k < 3; k++) {
+            const a = Math.floor((p[k] - r - min[k]) / cell);
+            const b = Math.floor((p[k] + r - min[k]) / cell);
+            if (a < 0 || b >= dims[k])
+                leaves = true;
+            lo[k] = Math.max(a, 0);
+            hi[k] = Math.min(b, dims[k] - 1);
+        }
+        if (leaves)
+            setBit(outside, 0, i);
+        if (lo[0] > hi[0] || lo[1] > hi[1] || lo[2] > hi[2])
+            continue;
+        const spot = l.cosOuter > -1;
+        const outer = Math.acos(Math.min(Math.max(l.cosOuter, -1), 1));
+        for (let z = lo[2]; z <= hi[2]; z++) {
+            for (let y = lo[1]; y <= hi[1]; y++) {
+                for (let x = lo[0]; x <= hi[0]; x++) {
+                    const b0 = [min[0] + x * cell, min[1] + y * cell, min[2] + z * cell];
+                    // The sphere against the cell's box: the nearest point of the box.
+                    let d2 = 0;
+                    for (let k = 0; k < 3; k++) {
+                        const q = Math.min(Math.max(p[k], b0[k]), b0[k] + cell);
+                        d2 += (q - p[k]) * (q - p[k]);
+                    }
+                    if (d2 > r * r)
+                        continue;
+                    if (spot) {
+                        // The cone against the cell's bounding sphere: the cell can be lit
+                        // when the angle to its centre is within the cone's half-angle plus
+                        // the angle that sphere subtends.
+                        const v = [b0[0] + cell / 2 - p[0], b0[1] + cell / 2 - p[1], b0[2] + cell / 2 - p[2]];
+                        const len = Math.hypot(v[0], v[1], v[2]);
+                        if (len > halfDiagonal) {
+                            const limit = outer + Math.asin(halfDiagonal / len);
+                            const cos = (v[0] * l.ax + v[1] * l.ay + v[2] * l.az) / len;
+                            if (limit < Math.PI && Math.acos(Math.min(Math.max(cos, -1), 1)) > limit)
+                                continue;
+                        }
+                    }
+                    setBit(cells, ((z * dims[1] + y) * dims[0] + x) * LIGHT_MASK_WORDS, i);
+                }
+            }
+        }
+    }
+    return { origin: [min[0], min[1], min[2]], cell, dims, outside, cells };
+}