reze-engine 0.55.8 → 0.55.10

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.8",
+  "version": "0.55.10",
   "description": "A lightweight WebGPU engine for real-time 3D MMD/PMX model rendering",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/engine.ts

@@ -1278,6 +1278,25 @@ const TEXTURE_EXTENSION_GUESSES = [".png", ".jpg", ".jpeg", ".bmp", ".tga", ".dd
  * below it. The GRID reaches 8 on its own, so it takes the next one up rather
  * than everything else moving to accommodate one mount.
  */
+/**
+ * One parameter's value for the uniform: what the caller passed, or what the
+ * source declared.
+ *
+ * A colour is written `#rrggbb` in the directive and reaches the GPU as three
+ * floats. Plain byte scaling, NOT an sRGB decode — the shader multiplies these
+ * against a texture that is itself sampled as sRGB, so decoding here would
+ * darken every authored colour by the transfer curve twice.
+ */
+function paramValue(p: EffectParamDecl, given: EffectParamValue | undefined): EffectParamValue {
+  if (given !== undefined) return given
+  if (p.kind === "color" && typeof p.value === "string") {
+    const n = parseInt(p.value.slice(1), 16)
+    return { x: ((n >> 16) & 255) / 255, y: ((n >> 8) & 255) / 255, z: (n & 255) / 255 }
+  }
+  if (Array.isArray(p.value)) return { x: p.value[0], y: p.value[1], z: p.value[2] }
+  return typeof p.value === "number" ? p.value : 0
+}
+
 const EFFECT_PARAMS_BINDING = 7
 const EFFECT_PARAMS_BINDING_GRID = 9
 
@@ -1504,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
@@ -1913,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[] = []
@@ -3221,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
   }
 
   /**
@@ -3236,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,
@@ -3259,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" }) },
@@ -3268,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
     }
   }
 
@@ -3627,19 +3734,35 @@ export class Engine {
     // Fields are emitted in declaration order; offsets follow WGSL's natural
     // uniform rules (f32 align 4, vec3f align 16 size 12), computed identically
     // on both sides so no reordering is needed.
-    const entries = Object.entries(params ?? {})
+    //
+    // THE SOURCE DECIDES THE STRUCT, and the caller only supplies values.
+    //
+    // This used to read `Object.entries(params ?? {})`, which made the struct a
+    // property of the CALL rather than of the shader: install the same source
+    // without a params object and every `params.X` in it became an unresolved
+    // identifier. Two callers installing one effect two ways is how an effect
+    // compiled in the scene and failed in the editor that was editing it.
+    //
+    // The directives are already parsed — `d.params` is returned in the result —
+    // so they are what the struct is built from. A value the caller passes wins
+    // over the declared default; a name it passes that the source never declared
+    // is ignored, because a field nothing reads is a binding nothing reads.
+    const entries: [string, EffectParamValue][] = d.params.map((p) => [p.name, paramValue(p, params?.[p.name])])
     const layout = new Map<string, { offset: number; comps: 1 | 3 }>()
     const fields: string[] = []
     let cursor = 0
-    for (const [name, value] of entries) {
-      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
-        return { ok: false, diagnostics: [`invalid param name "${name}" (must be a WGSL identifier)`], mounts, params: d.params, duration: d.duration }
+    for (const p of d.params) {
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(p.name)) {
+        return { ok: false, diagnostics: [`invalid param name "${p.name}" (must be a WGSL identifier)`], mounts, params: d.params, duration: d.duration }
       }
-      const isVec = typeof value !== "number"
+      // KIND comes from the declaration, never from the runtime type of the
+      // value: a caller handing a number to a colour must not silently turn a
+      // vec3f field into an f32 and shift every field after it.
+      const isVec = p.kind !== "float"
       const align = isVec ? 16 : 4
       const offset = Math.ceil(cursor / align) * align
-      layout.set(name, { offset: offset / 4, comps: isVec ? 3 : 1 })
-      fields.push(`  ${name}: ${isVec ? "vec3f" : "f32"},`)
+      layout.set(p.name, { offset: offset / 4, comps: isVec ? 3 : 1 })
+      fields.push(`  ${p.name}: ${isVec ? "vec3f" : "f32"},`)
       cursor = offset + (isVec ? 12 : 4)
     }
     const paramsData = new Float32Array(Math.max(4, Math.ceil(cursor / 16) * 4))
@@ -3675,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 })
@@ -3717,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 },
@@ -3902,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
@@ -4078,6 +4215,7 @@ 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.ensureFilterPage()
     this.rebuildFieldBindGroup()
     this.rebuildCompositeBindGroup()
     this.writeCompositeViewUniforms()
@@ -4701,17 +4839,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
@@ -4720,7 +4872,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.
@@ -4729,6 +4881,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. */
@@ -5716,6 +5885,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
@@ -14216,7 +14390,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;
 }
 `