reze-engine 0.55.9 → 0.55.11

package/src/engine.ts

@@ -1523,10 +1523,16 @@ interface EffectInstance {
      *  for the same reason `layout` is: `bind` is rebuilt on a buffer swap. */
     params: GPUBuffer | null
   } | null
-  /** The field mount's pipeline and its two parity bind groups, or null when the
-   *  effect declares neither background nor foreground. */
+  /** The field mount's pipeline and its bind groups, or null when the effect
+   *  declares neither background nor foreground. */
   fieldPipeline: GPURenderPipeline | null
-  fieldBindGroups: [GPUBindGroup, GPUBindGroup] | null
+  /** Two for a plain effect, one per grid parity. Eight for a filter — which
+   *  page it reads, whether it absorbs the half pair, grid parity — in
+   *  Engine.filterBindIndex order. */
+  fieldBindGroups: GPUBindGroup[] | null
+  /** Calls rzSceneFrame: runs after every other field effect, at full
+   *  resolution, reading their layers and carrying them forward. */
+  filter: boolean
   /** Which resolution pair this effect draws into: 0 full, 1 half. Its own
    *  declaration, not the scene's — see Engine.FIELD_SCALES. */
   fieldLayer: number
@@ -1932,6 +1938,13 @@ export class Engine {
   private fieldBgViews: (GPUTextureView | null)[] = [null, null]
   private fieldFgTextures: (GPUTexture | null)[] = [null, null]
   private fieldFgViews: (GPUTextureView | null)[] = [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. */
+  private fieldPageBgTexture: GPUTexture | null = null
+  private fieldPageFgTexture: GPUTexture | null = null
+  private fieldPageBgView: GPUTextureView | null = null
+  private fieldPageFgView: GPUTextureView | null = 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). */
   private fieldUniformBuffers: GPUBuffer[] = []
@@ -3240,6 +3253,55 @@ export class Engine {
         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.
+   */
+  private ensureFilterPage(): void {
+    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: string) =>
+      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. */
+  private filtersDrawn(): number {
+    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. */
+  private static filterBindIndex(readPage: 0 | 1, absorbHalf: boolean, gridParity: number): number {
+    return (readPage * 2 + (absorbHalf ? 1 : 0)) * 2 + gridParity
   }
 
   /**
@@ -3255,7 +3317,11 @@ export class Engine {
     // Captured, so the null guards above survive into the closure.
     const depth = this.depthReadView
     const bloom = this.compositeBloomView
-    const build = (owner: EffectInstance, grid: GPUTextureView) =>
+    const build = (
+      owner: EffectInstance,
+      grid: GPUTextureView,
+      layers: readonly [GPUTextureView, GPUTextureView, GPUTextureView, GPUTextureView],
+    ) =>
       this.device.createBindGroup({
         label: "field layer bind group",
         layout: this.fieldBindGroupLayout,
@@ -3278,6 +3344,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" }) },
@@ -3287,10 +3358,27 @@ 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: [GPUTextureView, GPUTextureView] = [this.fieldBgViews[0] ?? none, this.fieldFgViews[0] ?? none]
+    const page: [GPUTextureView, GPUTextureView] = [this.fieldPageBgView ?? none, this.fieldPageFgView ?? none]
+    const half: [GPUTextureView, GPUTextureView] = [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: GPUBindGroup[] = []
+      for (const read of [pairA, page]) {
+        for (const h of [[none, none], half] as [GPUTextureView, GPUTextureView][]) {
+          for (const g of grids) groups.push(build(e, g, [read[0], read[1], h[0], h[1]]))
+        }
+      }
+      e.fieldBindGroups = groups
     }
   }
 
@@ -3710,8 +3798,14 @@ 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.
+    // 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 } : null
+      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 })
@@ -3752,10 +3846,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 },
@@ -3937,7 +4036,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
@@ -3979,7 +4081,12 @@ export class Engine {
     list: { wgsl: string; params?: Record<string, EffectParamValue> }[] | null,
   ): Promise<EffectResult[]> {
     const noMounts = { background: false, foreground: false }
-    if (!this.device) return [{ ok: false, diagnostics: ["setEffects requires init() to have run"], mounts: noMounts, params: [], duration: 0 }]
+    // 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) {
@@ -4113,8 +4220,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
   }
@@ -4736,17 +4849,31 @@ export class Engine {
     // 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: [GPUTextureView | null, GPUTextureView | null] = [this.fieldBgViews[0], this.fieldFgViews[0]]
+    const pageB: [GPUTextureView | null, GPUTextureView | null] = [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: [GPUTextureView | null, GPUTextureView | null]): GPURenderPassColorAttachment[] => [
+      { 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)) continue
+      const target: [GPUTextureView | null, GPUTextureView | null] =
+        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
@@ -4755,7 +4882,7 @@ export class Engine {
       })
       stamped = true
       for (const e of drawn) {
-        if (e.fieldLayer !== i) continue
+        if (e.fieldLayer !== i || e.filter) continue
         pass.setPipeline(e.fieldPipeline!)
         // The grid this effect just wrote — after its parity flip, the one at
         // `parity`. Per effect, so two grids never read each other's frame.
@@ -4764,6 +4891,23 @@ 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. */
@@ -5751,6 +5895,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
@@ -11897,10 +12046,12 @@ export class Engine {
     const inst = this.modelInstances.get(this.selectedMaterial.modelName)
     if (!inst) return
     const target = this.selectedMaterial.materialName
-    const draw = inst.drawCalls.find(
-      (d) => (d.type === "opaque" || d.type === "transparent") && d.materialName === target,
+    // 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 (!draw || !this.shouldRenderDrawCall(inst, draw)) return
+    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
@@ -11913,7 +12064,7 @@ 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.
@@ -11929,19 +12080,23 @@ 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. */
-  private materialIndexRange(inst: ModelInstance, material: string | null): [number, number] | null {
+  /** 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. */
+  private materialIndexRanges(inst: ModelInstance, material: string | null): [number, number][] {
     const indices = inst.model.getIndices()
-    if (!material) return [0, indices.length]
+    if (!material) return [[0, indices.length]]
+    const runs: [number, number][] = []
     let offset = 0
     for (const m of inst.model.getMaterials()) {
-      if (m.name === material) return [offset, offset + m.vertexCount]
+      if (m.name === material) runs.push([offset, offset + m.vertexCount])
       offset += m.vertexCount
     }
-    return null
+    return runs
   }
 
   /** A cache key no material can collide with — a PMX name is never empty and
@@ -11990,9 +12145,8 @@ export class Engine {
         offset = end
       }
     } else {
-      const range = this.materialIndexRange(inst, material)
-      if (!range) return false
-      const [start, end] = range
+      const runs = this.materialIndexRanges(inst, material)
+      if (runs.length === 0) return false
       const seen = new Set<number>()
       const add = (a: number, b: number) => {
         const lo = a < b ? a : b
@@ -12002,10 +12156,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) {
@@ -12058,8 +12214,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
@@ -12100,9 +12256,9 @@ 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)
@@ -12124,10 +12280,10 @@ 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)
     }
 
@@ -14251,7 +14407,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/src/shaders/passes/composite.ts

@@ -96,6 +96,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
@@ -146,7 +151,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.
@@ -605,7 +611,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);
 `
@@ -617,7 +624,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);
 `
@@ -670,6 +677,16 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
   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 +
@@ -692,7 +709,7 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
     // 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" +
@@ -711,6 +728,15 @@ export function buildFieldShader(effect: CompositeEffectSource): string {
  */
 @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;
@@ -740,6 +766,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/src/shaders/scene-tap.ts

@@ -44,10 +44,41 @@
  * Clamp-to-edge is what stops a warped offset wrapping the far side of the
  * screen into the picture.
  */
-export function sceneTapApi(group: number, tex: number, samp: number): string {
+export function sceneTapApi(
+  group: number,
+  tex: number,
+  samp: number,
+  layers: readonly [number, number, number, number],
+): string {
   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).
@@ -176,25 +207,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);
 }
 
 /**