reze-engine 0.55.9 → 0.55.11

package/dist/engine.js

@@ -823,6 +823,13 @@ export class Engine {
         this.fieldBgViews = [null, null];
         this.fieldFgTextures = [null, null];
         this.fieldFgViews = [null, null];
+        /** The filter's page: a second full-res pair, so a filter can read the pair
+         *  the other effects drew into while it draws. Held only while a filter is
+         *  installed — see ensureFilterPage. */
+        this.fieldPageBgTexture = null;
+        this.fieldPageFgTexture = null;
+        this.fieldPageBgView = null;
+        this.fieldPageFgView = null;
         /** One per scale: the field shader reconstructs the full-res pixel it stands
          *  in for, so each pass needs its own (w, h, fullW, fullH). */
         this.fieldUniformBuffers = [];
@@ -2169,6 +2176,56 @@ export class Engine {
             this.fieldFgViews[i] = this.fieldFgTextures[i].createView();
             this.device.queue.writeBuffer(this.fieldUniformBuffers[i], 0, new Float32Array([w, h, this.fieldFullW, this.fieldFullH]));
         }
+        this.ensureFilterPage();
+    }
+    /**
+     * The filter's page, held only while a filter is installed.
+     *
+     * A full-res rgba16f pair is real memory — two 16MB targets at 1080p, four
+     * times that at 4K — and most scenes never install a filter. Created here
+     * and on resize, released the moment the last filter goes. Sized off the
+     * full pair, which is what a filter reads and what the composite reads back.
+     */
+    ensureFilterPage() {
+        const wanted = !!this.device && this.fieldFullW > 0 && this.effects.some((e) => e.filter);
+        const w = Math.max(1, this.fieldFullW);
+        const h = Math.max(1, this.fieldFullH);
+        if (wanted && this.fieldPageBgTexture?.width === w && this.fieldPageBgTexture.height === h)
+            return;
+        this.fieldPageBgTexture?.destroy();
+        this.fieldPageFgTexture?.destroy();
+        this.fieldPageBgTexture = null;
+        this.fieldPageFgTexture = null;
+        this.fieldPageBgView = null;
+        this.fieldPageFgView = null;
+        if (!wanted)
+            return;
+        const make = (label) => this.device.createTexture({
+            label,
+            size: [w, h],
+            format: "rgba16float",
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        this.fieldPageBgTexture = make("field layer page (background)");
+        this.fieldPageFgTexture = make("field layer page (foreground)");
+        this.fieldPageBgView = this.fieldPageBgTexture.createView();
+        this.fieldPageFgView = this.fieldPageFgTexture.createView();
+    }
+    /** Filters drawn this frame — the predicate renderFieldPass runs them by,
+     *  shared with the composite uniform that says the half pair was consumed. */
+    filtersDrawn() {
+        if (!this.fieldPageBgView || !this.fieldPageFgView)
+            return 0;
+        let n = 0;
+        for (const e of this.effects)
+            if (e.filter && e.fieldPipeline && e.fieldBindGroups && e.weight > 0)
+                n++;
+        return n;
+    }
+    /** Which of a filter's eight bind groups: the page it reads (0 the plain
+     *  pair, 1 the filter page), whether it absorbs the half pair, grid parity. */
+    static filterBindIndex(readPage, absorbHalf, gridParity) {
+        return (readPage * 2 + (absorbHalf ? 1 : 0)) * 2 + gridParity;
     }
     /**
      * ONE PER GRID PARITY.
@@ -2184,7 +2241,7 @@ export class Engine {
         // Captured, so the null guards above survive into the closure.
         const depth = this.depthReadView;
         const bloom = this.compositeBloomView;
-        const build = (owner, grid) => this.device.createBindGroup({
+        const build = (owner, grid, layers) => this.device.createBindGroup({
             label: "field layer bind group",
             layout: this.fieldBindGroupLayout,
             entries: [
@@ -2206,6 +2263,11 @@ export class Engine {
                 { binding: 26, resource: this.castDistView ?? this.castDistFallbackView },
                 { binding: 27, resource: this.hdrResolveTexture.createView() },
                 { binding: 28, resource: this.simSampler },
+                // The other effects' layers, for rzSceneFrame — see the loop below.
+                { binding: 29, resource: layers[0] },
+                { binding: 30, resource: layers[1] },
+                { binding: 31, resource: layers[2] },
+                { binding: 32, resource: layers[3] },
                 { binding: 2, resource: this.bloomSampler },
                 { binding: 5, resource: this.filmicLutView },
                 { binding: 10, resource: (this.agxLutTexture ?? this.agxFallbackTexture).createView({ dimension: "3d" }) },
@@ -2215,10 +2277,28 @@ export class Engine {
         });
         // Per effect: the params buffer and the grid are both its own, so two
         // effects cannot share a bind group even when everything else matches.
+        // What a filter reads, by variant. A plain effect draws into the pair it
+        // would otherwise read, so it gets the transparent 1x1 at every layer slot
+        // and rzSceneFrame answers the scene alone.
+        const none = this.trailFallbackView;
+        const pairA = [this.fieldBgViews[0] ?? none, this.fieldFgViews[0] ?? none];
+        const page = [this.fieldPageBgView ?? none, this.fieldPageFgView ?? none];
+        const half = [this.fieldBgViews[1] ?? none, this.fieldFgViews[1] ?? none];
         for (const e of this.effects) {
-            e.fieldBindGroups = e.grid
-                ? [build(e, e.grid.read[0]), build(e, e.grid.read[1])]
-                : [build(e, this.simFallbackView), build(e, this.simFallbackView)];
+            const grids = e.grid ? [e.grid.read[0], e.grid.read[1]] : [this.simFallbackView, this.simFallbackView];
+            if (!e.filter) {
+                e.fieldBindGroups = grids.map((g) => build(e, g, [none, none, none, none]));
+                continue;
+            }
+            // Eight, in filterBindIndex order: read page × absorbs half × grid parity.
+            const groups = [];
+            for (const read of [pairA, page]) {
+                for (const h of [[none, none], half]) {
+                    for (const g of grids)
+                        groups.push(build(e, g, [read[0], read[1], h[0], h[1]]));
+                }
+            }
+            e.fieldBindGroups = groups;
         }
     }
     /**
@@ -2615,7 +2695,13 @@ export class Engine {
         const gridSize = gridEntryPoint(wgsl) ? Math.min(d.grid || 256, GRID_MAX) : 0;
         // `alias` goes in: a field effect reads bones through _rzSlot exactly as a
         // particle one does, and it was the only module never handed the mapping.
-        const fieldEffect = hasBackground || hasForeground ? { wgsl, paramsDecl, hasBackground, hasForeground, gridSize, alias, trailCount: anchors.filter((a) => a.trail).length } : null;
+        // A FILTER by what it calls, like every other mount property. rzSceneFrame
+        // answers the frame with the other effects' layers in it, which is only
+        // possible from a pass that runs after theirs — see renderFieldPass.
+        const filter = (hasBackground || hasForeground) && /\brzSceneFrame\s*\(/.test(wgsl);
+        const fieldEffect = hasBackground || hasForeground
+            ? { wgsl, paramsDecl, hasBackground, hasForeground, gridSize, alias, trailCount: anchors.filter((a) => a.trail).length, filter, additiveLayer: d.additiveLayer }
+            : null;
         const source = buildCompositeShader(fieldEffect);
         this.device.pushErrorScope("validation");
         const module = this.device.createShaderModule({ label: "composite shader (effect)", code: source });
@@ -2658,10 +2744,15 @@ export class Engine {
                         // the premultiplication happens here, and the composite reads it
                         // back knowing that. With one effect over a cleared target the
                         // result is identical to the replace it used to do.
-                        targets: [
-                            { format: "rgba16float", blend: layerBlend },
-                            { format: "rgba16float", blend: layerBlend },
-                        ],
+                        // A filter composes over the layers in its own shader and writes
+                        // the result outright: blending would layer it onto a page that
+                        // holds nothing.
+                        targets: filter
+                            ? [{ format: "rgba16float" }, { format: "rgba16float" }]
+                            : [
+                                { format: "rgba16float", blend: layerBlend },
+                                { format: "rgba16float", blend: layerBlend },
+                            ],
                     },
                     primitive: { topology: "triangle-list" },
                     multisample: { count: 1 },
@@ -2842,7 +2933,10 @@ export class Engine {
             // against 4.5ms). It is the right call for a soft additive glow, which
             // upsamples invisibly — and it is now a claim an author makes about
             // their own effect rather than a fate that befalls one.
-            fieldLayer: d.fieldLayer,
+            // A filter holds every other effect's pixels, so it holds them at full
+            // resolution whatever it declared for itself.
+            fieldLayer: filter ? 0 : d.fieldLayer,
+            filter,
             fieldPipeline,
             fieldClock,
             // Filled by rebuildFieldBindGroup below, which needs the instance to
@@ -2881,8 +2975,13 @@ export class Engine {
      */
     async setEffects(list) {
         const noMounts = { background: false, foreground: false };
-        if (!this.device)
+        // Clearing an engine that has nothing yet is already done; only an install
+        // needs the device.
+        if (!this.device) {
+            if (!list || list.length === 0)
+                return [];
             return [{ ok: false, diagnostics: ["setEffects requires init() to have run"], mounts: noMounts, params: [], duration: 0 }];
+        }
         const requested = list ?? [];
         if (requested.length === 0) {
             for (const e of this.effects) {
@@ -3001,8 +3100,14 @@ export class Engine {
         // fieldLayer when the instance is built, and both target pairs exist for
         // the life of the surface. What used to be a scene-wide decision made here
         // is now each effect's own.
-        this.rebuildFieldBindGroup();
-        this.rebuildCompositeBindGroup();
+        this.ensureFilterPage();
+        // EVERY shared buffer, not only the field and composite groups. The mounts
+        // above were built across awaits, and audio, a score or lyrics landing in
+        // one of those gaps replaced its buffer and destroyed the old one — which
+        // the new particle, light, trail and grid groups had been built against,
+        // so the next submit named a destroyed buffer. Rebinding at install closes
+        // the gap from whichever side the asset arrived.
+        this.rebindSharedBuffers();
         this.writeCompositeViewUniforms();
         return results;
     }
@@ -3602,18 +3707,31 @@ export class Engine {
         // The distance field, before anything reads it. Returns immediately when no
         // installed effect names rzCastDistance, which is the common case.
         this.encodeCastDistance(encoder);
+        // FILTERS RUN LAST, each in a pass of its own, because each reads the pair
+        // the others drew into — a texture no pass may sample while drawing into
+        // it. So the full-res pair is two, the plain pair A and the filter's page,
+        // and the passes alternate between them. The composite reads A and is not
+        // rebuilt per frame, so the chain is arranged to END on A: with an odd
+        // number of filters the plain effects draw into the page instead, and the
+        // last filter lands where the composite looks. The half pair is read by
+        // the first filter and consumed — viewU[5].w tells the composite so.
+        const filters = drawn.filter((e) => e.filter);
+        const pageA = [this.fieldBgViews[0], this.fieldFgViews[0]];
+        const pageB = [this.fieldPageBgView, this.fieldPageFgView];
+        const canFilter = filters.length > 0 && !!pageB[0] && !!pageB[1];
+        const plainFull = canFilter && filters.length % 2 === 1 ? pageB : pageA;
+        const attach = (views) => [
+            { view: views[0], clearValue: { r: 0, g: 0, b: 0, a: 0 }, loadOp: "clear", storeOp: "store" },
+            { view: views[1], clearValue: { r: 0, g: 0, b: 0, a: 0 }, loadOp: "clear", storeOp: "store" },
+        ];
         let stamped = false;
         for (let i = 0; i < Engine.FIELD_SCALES.length; i++) {
-            const bg = this.fieldBgViews[i];
-            const fg = this.fieldFgViews[i];
-            if (!bg || !fg || !this.fieldPairUsed(i))
+            const target = i === 0 ? plainFull : [this.fieldBgViews[i], this.fieldFgViews[i]];
+            if (!target[0] || !target[1] || !this.fieldPairUsed(i))
                 continue;
             const pass = encoder.beginRenderPass({
                 label: `field layer (${Engine.FIELD_SCALES[i] === 1 ? "full" : "half"})`,
-                colorAttachments: [
-                    { view: bg, clearValue: { r: 0, g: 0, b: 0, a: 0 }, loadOp: "clear", storeOp: "store" },
-                    { view: fg, clearValue: { r: 0, g: 0, b: 0, a: 0 }, loadOp: "clear", storeOp: "store" },
-                ],
+                colorAttachments: attach(target),
                 // One query pair is reserved for "field", and it goes to the first pair
                 // that actually runs — full res when something declared #fullres, half
                 // otherwise. Pinning it to i === 0 would have measured a pass that, now
@@ -3622,7 +3740,7 @@ export class Engine {
             });
             stamped = true;
             for (const e of drawn) {
-                if (e.fieldLayer !== i)
+                if (e.fieldLayer !== i || e.filter)
                     continue;
                 pass.setPipeline(e.fieldPipeline);
                 // The grid this effect just wrote — after its parity flip, the one at
@@ -3632,6 +3750,21 @@ export class Engine {
             }
             pass.end();
         }
+        if (!canFilter)
+            return;
+        // Each filter reads what the previous pass left and writes the other page.
+        // The half pair goes to the first one, and only when something drew into
+        // it this frame — an unused pair is never cleared and holds stale pixels.
+        let read = plainFull;
+        filters.forEach((e, k) => {
+            const write = read === pageA ? pageB : pageA;
+            const pass = encoder.beginRenderPass({ label: "field layer (filter)", colorAttachments: attach(write) });
+            pass.setPipeline(e.fieldPipeline);
+            pass.setBindGroup(0, e.fieldBindGroups[Engine.filterBindIndex(read === pageA ? 0 : 1, k === 0 && this.fieldPairUsed(1), e.grid?.parity ?? 0)]);
+            pass.draw(3);
+            pass.end();
+            read = write;
+        });
     }
     /** The trail bind group holds the depth view, which a resize recreates. */
     rebindTrails() {
@@ -4570,6 +4703,11 @@ export class Engine {
                 // why it may not borrow the one at 18.
                 { binding: 27, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
                 { binding: 28, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+                // The other effects' layers, for a filter's rzSceneFrame (scene-tap.ts).
+                { binding: 29, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 30, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 31, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 32, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
                 // THE VIEW TRANSFORM'S OWN RESOURCES. viewTransform() lives in the
                 // header both this module and the composite share, but its lookups did
                 // not: an effect calling it compiled and then failed at pipeline
@@ -10175,8 +10313,10 @@ export class Engine {
         if (!inst)
             return;
         const target = this.selectedMaterial.materialName;
-        const draw = inst.drawCalls.find((d) => (d.type === "opaque" || d.type === "transparent") && d.materialName === target);
-        if (!draw || !this.shouldRenderDrawCall(inst, draw))
+        // Every draw under the name — see materialIndexRanges for why there can be
+        // more than one.
+        const draws = inst.drawCalls.filter((d) => (d.type === "opaque" || d.type === "transparent") && d.materialName === target && this.shouldRenderDrawCall(inst, d));
+        if (draws.length === 0)
             return;
         // Mask pass: fill the selected material's projected footprint with 1.0. Depth-always
         // (no depth attachment) so the outline traces complete boundaries even when the
@@ -10189,7 +10329,8 @@ export class Engine {
         mpass.setVertexBuffer(1, inst.jointsBuffer);
         mpass.setVertexBuffer(2, inst.weightsBuffer);
         mpass.setIndexBuffer(inst.indexBuffer, "uint32");
-        mpass.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0);
+        for (const draw of draws)
+            mpass.drawIndexed(draw.count, 1, draw.firstIndex, 0, 0);
         mpass.end();
         // Edge pass: screen-space edge detect on the mask, alpha-blended over swapchain.
         const edgeAttachment = this.selectionEdgePassDescriptor.colorAttachments[0];
@@ -10203,21 +10344,25 @@ export class Engine {
     // Unique edges of the mesh, as a line-list index buffer. Each interior edge is
     // shared by two triangles, so deduplicating halves both the buffer and the
     // draw. Built once per model, on the first frame its wireframe is asked for.
-    /** The index run `material` owns, or the whole list when it is null. Materials
-     *  are consecutive runs in declaration order, so the offset is a prefix sum —
-     *  the same walk the draw list does. Returns null for a name the model does
-     *  not have, which is what a stale selection looks like after a reload. */
-    materialIndexRange(inst, material) {
+    /** The index runs `material` owns — EVERY run, because a PMX may carry
+     *  several materials under one name and a name is how the host asks; taking
+     *  the first left the rest of a hair or a coat out of its own wireframe —
+     *  or the whole list when it is null. Materials are consecutive runs in
+     *  declaration order, so each offset is a prefix sum, the same walk the draw
+     *  list does. Empty for a name the model does not have, which is what a
+     *  stale selection looks like after a reload. */
+    materialIndexRanges(inst, material) {
         const indices = inst.model.getIndices();
         if (!material)
-            return [0, indices.length];
+            return [[0, indices.length]];
+        const runs = [];
         let offset = 0;
         for (const m of inst.model.getMaterials()) {
             if (m.name === material)
-                return [offset, offset + m.vertexCount];
+                runs.push([offset, offset + m.vertexCount]);
             offset += m.vertexCount;
         }
-        return null;
+        return runs;
     }
     /**
      * @param material one material's own edges, or null for the whole mesh
@@ -10263,10 +10408,9 @@ export class Engine {
             }
         }
         else {
-            const range = this.materialIndexRange(inst, material);
-            if (!range)
+            const runs = this.materialIndexRanges(inst, material);
+            if (runs.length === 0)
                 return false;
-            const [start, end] = range;
             const seen = new Set();
             const add = (a, b) => {
                 const lo = a < b ? a : b;
@@ -10277,10 +10421,12 @@ export class Engine {
                 seen.add(k);
                 edges.push(lo, hi);
             };
-            for (let i = start; i + 2 < end; i += 3) {
-                add(indices[i], indices[i + 1]);
-                add(indices[i + 1], indices[i + 2]);
-                add(indices[i + 2], indices[i]);
+            for (const [start, end] of runs) {
+                for (let i = start; i + 2 < end; i += 3) {
+                    add(indices[i], indices[i + 1]);
+                    add(indices[i + 1], indices[i + 2]);
+                    add(indices[i + 2], indices[i]);
+                }
             }
         }
         if (edges.length === 0) {
@@ -10332,8 +10478,8 @@ export class Engine {
         // picked, since only the picked material draws at all then.
         const hm = this.hoverMaterial;
         const hoverName = material === null && hm?.modelName === inst.name ? hm.materialName : null;
-        const hoverRange = hoverName ? this.materialIndexRange(inst, hoverName) : null;
-        const hover = hoverRange && this.ensureEdgeBuffer(inst, hoverName) ? inst.wireEdges.get(hoverName) : null;
+        const hoverRuns = hoverName ? this.materialIndexRanges(inst, hoverName) : [];
+        const hover = hoverRuns.length > 0 && this.ensureEdgeBuffer(inst, hoverName) ? inst.wireEdges.get(hoverName) : null;
         this.wireframeColorData.set(DEFAULT_VERTEX_COLOR);
         this.wireframeColorData[4] = this.canvas.width;
         this.wireframeColorData[5] = this.canvas.height;
@@ -10371,9 +10517,10 @@ export class Engine {
         // before the base mesh below gets a chance to occlude it. The base mesh's
         // depth write further down repeats the SAME geometry for these faces
         // (identical z), so it neither disturbs this nor needs to skip them.
-        if (hover && hoverRange && !xray) {
+        if (hover && !xray) {
             bindMesh();
-            pass.drawIndexed(hoverRange[1] - hoverRange[0], 1, hoverRange[0]);
+            for (const [start, end] of hoverRuns)
+                pass.drawIndexed(end - start, 1, start);
             pass.setBindGroup(0, this.wireframeHoverBindGroup);
             pass.setBindGroup(1, hover.bindGroup);
             pass.setPipeline(this.wireframePipeline);
@@ -10394,11 +10541,12 @@ export class Engine {
         // the coat hide it does not answer that. Its own depth still goes in, so its
         // back faces stay hidden and it reads as an object instead of a haze —
         // which is the difference between this and turning x-ray on.
-        const range = material !== null ? this.materialIndexRange(inst, material) : null;
+        const runs = material !== null ? this.materialIndexRanges(inst, material) : null;
         if (!xray) {
             bindMesh();
-            if (range)
-                pass.drawIndexed(range[1] - range[0], 1, range[0]);
+            if (runs)
+                for (const [start, end] of runs)
+                    pass.drawIndexed(end - start, 1, start);
             else
                 pass.drawIndexed(inst.model.getIndices().length);
         }
@@ -12235,7 +12383,9 @@ export class Engine {
             u[20] = v[2];
             u[21] = v[6];
             u[22] = v[10];
-            u[23] = 0;
+            // A drawn filter consumed the half pair (renderFieldPass); the composite
+            // skips it rather than laying it down a second time.
+            u[23] = this.filtersDrawn() > 0 ? 1 : 0;
             // Effect clock + canvas size (viewU[6]) — written on the same refresh.
             // The effect clock, on the SCENE's time rather than the wall's.
             //

package/dist/shaders/passes/composite.d.ts

@@ -64,6 +64,11 @@ type CompositeEffectSource = {
     hasBackground: boolean;
     /** Defines `fn foreground(...)` — mount over the finished frame. */
     hasForeground: boolean;
+    /** Calls rzSceneFrame — a FILTER, which carries the layers it read forward
+     *  (buildFieldShader) and so draws with blending off. */
+    filter?: boolean;
+    /** `#layer additive`: how a filter's own output joins the layers it carries. */
+    additiveLayer?: boolean;
     /** Grid resolution when the effect declared `#grid`, else 0. */
     gridSize: number;
     /** Whether the scene pass carries the id attachment, so the field module can

package/dist/shaders/passes/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAID,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAEzG,KAAK,qBAAqB,GAAG;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;IACtB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;yEAGqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB;;8EAE0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AA6LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,yqaA+H5B,CAAA;AA6MD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAiFtE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/composite.ts"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAgC+B;AAC/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAAE,CAIhG;AAID,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAEzG,KAAK,qBAAqB,GAAG;IAC3B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAA;IACtB,oEAAoE;IACpE,aAAa,EAAE,OAAO,CAAA;IACtB;6DACyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gFAAgF;IAChF,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB;mFAC+E;IAC/E,GAAG,CAAC,EAAE,OAAO,CAAA;IACb;;;yEAGqE;IACrE,UAAU,EAAE,MAAM,CAAA;IAClB;;8EAE0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CACjB,CAAA;AA8LD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB,yqaA+H5B,CAAA;AA8MD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,MAAM,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAqGtE;AAED,iFAAiF;AACjF,eAAO,MAAM,qBAAqB,QAA6B,CAAA"}

package/dist/shaders/passes/composite.js

@@ -117,7 +117,8 @@ override APPLY_GAMMA: bool = true;
 //            and no on/off uniform either: the pipeline is REBUILT per effect, so
 //            the compiled variant IS the flag.
 // viewU[3] = (camera right, tanHalfFov·aspect); viewU[4] = (camera up, tanHalfFov);
-// viewU[5] = (camera forward, _) — refreshed per frame while skybox/effect active.
+// viewU[5] = (camera forward, half pair consumed by a filter this frame) — refreshed
+//            per frame while skybox/effect active.
 // viewU[6] = (time seconds, view transform id, canvas width, canvas height).
 // viewU[7] = (grade offset.rgb, contrast);  viewU[8] = (grade power.rgb, saturation);
 // viewU[9] = (grade slope.rgb, grade on/off) — see grade() below.
@@ -573,7 +574,8 @@ const BACKGROUND_CALL = /* wgsl */ `
     // straight form it replaced.
     let bgFx = rzFieldMerge(
       clamp(textureSampleLevel(fieldBgTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)),
-      clamp(textureSampleLevel(fieldBgHalfTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)));
+      // The half pair, unless a filter consumed it this frame (viewU[5].w).
+      clamp(textureSampleLevel(fieldBgHalfTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)) * (1.0 - viewU[5].w));
     bgPm = bgFx.rgb + bgPm * (1.0 - bgFx.a);
     bgA = bgFx.a + bgA * (1.0 - bgFx.a);
 `;
@@ -584,7 +586,7 @@ const FOREGROUND_CALL = /* wgsl */ `
   // Premultiplied, as the background layer above — same reason.
   let fgFx = rzFieldMerge(
     clamp(textureSampleLevel(fieldFgTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)),
-    clamp(textureSampleLevel(fieldFgHalfTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)));
+    clamp(textureSampleLevel(fieldFgHalfTex, bloomSamp, fragCoord.xy / fullSz, 0.0), vec4f(0.0), vec4f(1.0)) * (1.0 - viewU[5].w));
   outRgb = fgFx.rgb + outRgb * (1.0 - fgFx.a);
   outA = fgFx.a + outA * (1.0 - fgFx.a);
 `;
@@ -635,6 +637,16 @@ export function buildFieldShader(effect) {
     const fgLine = effect.hasForeground
         ? "out.fg = clamp(foreground(dir, uv, _rzFieldClock.x, linearDepth(vec2<i32>(min(fx, fullSz - 1.0)))), vec4f(0.0), vec4f(1.0));"
         : "";
+    // A FILTER read the other effects' layers through rzSceneFrame and now
+    // carries them: its own output goes over (or adds to) what they drew, and
+    // the pipeline writes the result with blending off. Weight has already
+    // scaled its alpha, so a filter faded to nothing passes the layers through
+    // untouched.
+    const carry = effect.filter
+        ? effect.additiveLayer
+            ? "out.bg = _rzCarryAdd(out.bg, _rzLayerBg(uv));\n  out.fg = _rzCarryAdd(out.fg, _rzLayerFg(uv));"
+            : "out.bg = _rzCarryOver(out.bg, _rzLayerBg(uv));\n  out.fg = _rzCarryOver(out.fg, _rzLayerFg(uv));"
+        : "";
     return (COMPOSITE_HEAD +
         EFFECT_SCENE_API +
         anchorAliasWgsl(effect.alias ?? []) +
@@ -656,7 +668,7 @@ export function buildFieldShader(effect) {
         // texel is CAST_FIELD_DIV of them and the accessor scales on the way out.
         // An author writes the width they mean and never learns how it is built.
         castDistanceApi(0, 26, 18, CAST_FIELD_DIV) +
-        sceneTapApi(0, 27, 28) +
+        sceneTapApi(0, 27, 28, [29, 30, 31, 32]) +
         "\n// ── user effect (setEffect) ──\n" +
         effect.paramsDecl +
         "\n" +
@@ -675,6 +687,15 @@ export function buildFieldShader(effect) {
  */
 @group(0) @binding(22) var<uniform> _rzFieldClock: vec4f;   // (time, weight, _, _)
 
+/** A filter's own straight-alpha output over the premultiplied layers it read
+ *  (the layer blend state, restated) and the additive form of the same. */
+fn _rzCarryOver(own: vec4f, under: vec4f) -> vec4f {
+  return vec4f(own.rgb * own.a + under.rgb * (1.0 - own.a), own.a + under.a * (1.0 - own.a));
+}
+fn _rzCarryAdd(own: vec4f, under: vec4f) -> vec4f {
+  return vec4f(own.rgb * own.a + under.rgb, own.a + under.a);
+}
+
 @vertex fn fieldVs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
   let x = f32((vi & 1u) << 2u) - 1.0;
   let y = f32((vi & 2u) << 1u) - 1.0;
@@ -704,6 +725,7 @@ struct FieldOut {
   // Scaling colour as well would fade as the square.
   out.bg.a *= _rzFieldClock.y;
   out.fg.a *= _rzFieldClock.y;
+  ${carry}
   return out;
 }
 `);

package/dist/shaders/scene-tap.d.ts

@@ -43,7 +43,7 @@
  * Clamp-to-edge is what stops a warped offset wrapping the far side of the
  * screen into the picture.
  */
-export declare function sceneTapApi(group: number, tex: number, samp: number): string;
+export declare function sceneTapApi(group: number, tex: number, samp: number, layers: readonly [number, number, number, number]): string;
 /**
  * The same names, for the modules with no finished scene to give.
  *

package/dist/shaders/scene-tap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-tap.d.ts","sourceRoot":"","sources":["../../src/shaders/scene-tap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAoK5E;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,kjBAW1B,CAAA"}
+{"version":3,"file":"scene-tap.d.ts","sourceRoot":"","sources":["../../src/shaders/scene-tap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAChD,MAAM,CA6MR;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,kjBAW1B,CAAA"}

package/dist/shaders/scene-tap.js

@@ -43,10 +43,36 @@
  * Clamp-to-edge is what stops a warped offset wrapping the far side of the
  * screen into the picture.
  */
-export function sceneTapApi(group, tex, samp) {
+export function sceneTapApi(group, tex, samp, layers) {
     return /* wgsl */ `
 @group(${group}) @binding(${tex}) var _rzSceneTex: texture_2d<f32>;
 @group(${group}) @binding(${samp}) var _rzSceneSamp: sampler;
+// The field layers as the other effects left them — see rzSceneFrame. Bound to
+// the pair the others drew into for a filter, and to a 1x1 transparent for
+// everything else: an effect cannot sample the pair it is drawing into.
+@group(${group}) @binding(${layers[0]}) var _rzLayerBgFull: texture_2d<f32>;
+@group(${group}) @binding(${layers[1]}) var _rzLayerFgFull: texture_2d<f32>;
+@group(${group}) @binding(${layers[2]}) var _rzLayerBgHalf: texture_2d<f32>;
+@group(${group}) @binding(${layers[3]}) var _rzLayerFgHalf: texture_2d<f32>;
+
+/** Premultiplied OVER, top in front — the composite's rzFieldMerge, restated so
+ *  this file keeps importing nothing. A resolution boundary is a layer
+ *  boundary: full res over half, exactly as the composite reads them. */
+fn _rzLayerOver(top: vec4f, bot: vec4f) -> vec4f {
+  return vec4f(top.rgb + bot.rgb * (1.0 - top.a), top.a + bot.a * (1.0 - top.a));
+}
+fn _rzLayerBg(uv: vec2f) -> vec4f {
+  let p = _rzTapUv(uv);
+  return _rzLayerOver(
+    clamp(textureSampleLevel(_rzLayerBgFull, _rzSceneSamp, p, 0.0), vec4f(0.0), vec4f(1.0)),
+    clamp(textureSampleLevel(_rzLayerBgHalf, _rzSceneSamp, p, 0.0), vec4f(0.0), vec4f(1.0)));
+}
+fn _rzLayerFg(uv: vec2f) -> vec4f {
+  let p = _rzTapUv(uv);
+  return _rzLayerOver(
+    clamp(textureSampleLevel(_rzLayerFgFull, _rzSceneSamp, p, 0.0), vec4f(0.0), vec4f(1.0)),
+    clamp(textureSampleLevel(_rzLayerFgHalf, _rzSceneSamp, p, 0.0), vec4f(0.0), vec4f(1.0)));
+}
 
 /** uv as the mount gives it (y=0 at the BOTTOM, the shadertoy convention the
  *  composite documents) turned into a texture coordinate (y=0 at the top).
@@ -175,25 +201,40 @@ fn rzSceneDisplay(uv: vec2f) -> vec3f {
 }
 
 /**
- * The finished pixel: the scene over its background, exactly as the composite
- * would lay it down. One call, and the answer already carries the ground's
- * fade, its opacity, and the background showing through both.
- *
- * This is what a FILTER wants — anything re-rendering the whole frame on a tube
- * or a low-resolution screen. Reaching for rzSceneDisplay and a depth test
- * instead rebuilds this by hand and gets it wrong in one specific way every
- * time: coverage is not a yes or no, and treating it as one turns every soft
- * edge in the scene into a hard one.
- *
- * NOT INCLUDED: depth of field, background effects, and an equirect background
- * (a 360 dome reads as its average rather than its texture). Foregrounds compose
- * after this in any case.
+ * The frame as it stands: the scene over its background, and both layers of
+ * every other field effect, laid down in the order the composite would lay
+ * them. One call, and the answer already carries the ground's fade, its
+ * opacity, the background showing through both, and whatever the other
+ * effects drew — a waveform, a caption, a glow.
+ *
+ * CALLING THIS MAKES THE EFFECT A FILTER. A filter runs after every other
+ * field effect, at full resolution, and what it returns replaces the layers it
+ * read: its own output is composed over them in its pass (buildFieldShader),
+ * so nothing drawn before it is lost and nothing is drawn twice. Two filters
+ * run in document order, each reading the one before. The layers are a
+ * pass-order fact — a filter reads the pair the others drew into while it
+ * draws into a page of its own (renderFieldPass).
+ *
+ * This is what a FILTER wants — anything re-rendering the whole frame on a
+ * tube, a low-resolution screen, or a card. Reaching for rzSceneDisplay and a
+ * depth test instead rebuilds this by hand and gets it wrong in one specific
+ * way every time: coverage is not a yes or no, and treating it as one turns
+ * every soft edge in the scene into a hard one.
+ *
+ * NOT INCLUDED: depth of field, and an equirect background (a 360 dome reads
+ * as its average rather than its texture).
  */
 fn rzSceneFrame(uv: vec2f) -> vec3f {
   let a = clamp(rzSceneAlpha(uv), 0.0, 1.0);
   let bg = viewU[2];
-  let bgRgb = bg.rgb * select(0.0, 1.0, bg.w > 0.5);
-  return rzSceneDisplay(uv) * a + bgRgb * (1.0 - a);
+  let bgA = select(0.0, 1.0, bg.w > 0.5);
+  // The background layer over the base, the scene over both, the foreground
+  // layer over the frame — the composite's own order.
+  let lb = _rzLayerBg(uv);
+  let under = lb.rgb + bg.rgb * bgA * (1.0 - lb.a);
+  let frame = rzSceneDisplay(uv) * a + under * (1.0 - a);
+  let lf = _rzLayerFg(uv);
+  return lf.rgb + frame * (1.0 - lf.a);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reze-engine",
-  "version": "0.55.9",
+  "version": "0.55.11",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",