reze-engine 0.42.3 → 0.50.0

package/src/shaders/passes/id-debug.ts

@@ -0,0 +1,75 @@
+import { GROUND_MATERIAL_ID } from "./ground"
+
+/**
+ * The id attachment, drawn so a person can look at it.
+ *
+ * The id buffer is correct or incorrect in ways nothing else in the frame can
+ * show: with no consumer, a perfect id buffer and a completely wrong one
+ * produce exactly the same picture. This pass exists so that "it works" is
+ * something seen rather than inferred.
+ *
+ * WHAT CORRECT LOOKS LIKE, and what each failure looks like instead:
+ *
+ *   - Every material is ONE FLAT COLOUR, with hard edges. Ids are names, not
+ *     quantities: a gradient anywhere, or fringing along an edge, means
+ *     something is interpolating or resolving them — the two failures the
+ *     no-resolve/no-blend rules exist to prevent.
+ *   - Parts differ from each other. A whole model in one colour means the
+ *     material index never made it into the uniform.
+ *   - The FLOOR is a fixed light grey, the reserved id, and never shares a
+ *     colour with a body part.
+ *   - Where nothing was drawn is BLACK — id 0, the reserved nothing, which is
+ *     also what the attachment clears to. Black *over geometry* means that draw
+ *     wrote no id; colour where the sky should be means the clear is wrong.
+ *
+ * Colours come from a hash of the pair, so neighbouring materials land on
+ * unrelated hues rather than adjacent shades of one — the point is telling them
+ * apart, not ordering them.
+ */
+export const ID_DEBUG_SHADER_WGSL = /* wgsl */ `
+// Multisampled and NEVER resolved, so it is read the way it is written: one
+// sample, by texel. Sample 0 is what every consumer of this attachment reads.
+@group(0) @binding(0) var idTex: texture_multisampled_2d<u32>;
+
+@vertex fn vs(@builtin(vertex_index) vi: u32) -> @builtin(position) vec4f {
+  let x = f32((vi & 1u) << 2u) - 1.0;
+  let y = f32((vi & 2u) << 1u) - 1.0;
+  return vec4f(x, y, 0.0, 1.0);
+}
+
+/** Integer hash → 0..1. Distinct inputs land on unrelated outputs, which is the
+ *  whole requirement: adjacent ids must not read as adjacent colours. */
+fn hashId(x: u32) -> f32 {
+  var h = x * 747796405u + 2891336453u;
+  h = ((h >> ((h >> 28u) + 4u)) ^ h) * 277803737u;
+  return f32((h >> 22u) ^ h) / 4294967295.0;
+}
+
+@fragment fn fs(@builtin(position) fragCoord: vec4f) -> @location(0) vec4f {
+  let ids = textureLoad(idTex, vec2<i32>(fragCoord.xy), 0);
+  let materialId = ids.x;
+  let objectId = ids.y;
+
+  // Nothing drawn here. Black, and it must cover exactly the empty space.
+  if (materialId == 0u && objectId == 0u) {
+    return vec4f(0.0, 0.0, 0.0, 1.0);
+  }
+  // The floor, at the top of the range. Flat light grey so it is unmistakable
+  // and cannot be confused with a hashed colour.
+  if (materialId == ${GROUND_MATERIAL_ID}u) {
+    return vec4f(0.72, 0.72, 0.75, 1.0);
+  }
+  // Hue from the material, brightness from the object, so two models wearing
+  // the same material index still read apart.
+  let h = hashId(materialId * 1973u + 9277u);
+  let shade = 0.55 + 0.45 * hashId(objectId * 6151u + 1u);
+  // Cheap hue ramp: three offset cosines. Saturated on purpose — this is a
+  // diagnostic, not a look.
+  let rgb = vec3f(
+    0.5 + 0.5 * cos(6.28318 * (h + 0.00)),
+    0.5 + 0.5 * cos(6.28318 * (h + 0.33)),
+    0.5 + 0.5 * cos(6.28318 * (h + 0.67)),
+  );
+  return vec4f(rgb * shade, 1.0);
+}
+`

package/src/shaders/passes/particles.ts

@@ -0,0 +1,340 @@
+import { RZ_LIGHT_STRUCT_WGSL } from "../lights"
+import { audioApi } from "../audio-api"
+import { lyricsApi } from "../lyrics-api"
+import { anchorAliasWgsl } from "../anchor-table"
+import { midiApi } from "../midi-api"
+import { CAST_API } from "../cast-api"
+import { clockApi, EFFECT_MATH_API, PARTICLE_STRUCT_WGSL, trailSlotsApi, viewportApi } from "./hosted-api"
+// GPU particles for user effects: a compute step and an instanced quad draw.
+//
+// Its own shader MODULE rather than more source spliced into composite.ts, for
+// three reasons that all point the same way. Cost: a fullscreen effect pays for
+// every pixel on screen whether it drew anything there or not, so a ribbon walked
+// as a field cost O(pixels × samples) where the same picture as geometry costs
+// O(segments) — the difference between one effect and a scene full of them.
+// Occlusion: geometry drawn inside the scene pass is depth-tested, so a particle
+// behind the character is simply hidden, which a composited field can only fake.
+// And names: separate modules cannot collide, so two effects may both define
+// `hash21` and never meet — which is what makes running several at once safe.
+//
+// The author writes three functions and the engine owns the loop. That split is
+// deliberate: spawning, ageing, recycling, billboarding and sorting are the same
+// in every particle effect ever written, and an author who has to re-derive them
+// gets them subtly wrong in a way that only shows up on someone else's machine.
+
+/** Where the cast/trail history sits in the shared storage buffer. */
+export type CastLayout = {
+  subjects: number
+  samples: number
+  base: number
+  trailBase: number
+  /** The scene's anchor CAP — the address space, not how many asked for trails. */
+  slots: number
+  /** How many of this effect's anchors asked for a trail. AUTHOR-VISIBLE as
+   *  RZ_TRAIL_SLOTS: published effects loop over it, so its meaning is pinned
+   *  even though the address space it used to share is now a separate number. */
+  trailCount: number
+  /** This effect's local slot → scene slot. Identity while one effect exists. */
+  alias: number[]
+}
+
+/**
+ * The trail accessors, in the PARTICLE module.
+ *
+ * Sparks are the reason: the original hand ribbon shed sparks along its path,
+ * and as real particles they need to SPAWN on that path — which means
+ * particleInit reading the same recorded history the trail draws from. One
+ * effect file, two mounts, one buffer.
+ */
+/** Shared with the grid pass, which reads the same buffer for the same reason:
+ *  a kernel that displaces fog has to know where the dancer's feet are. */
+function castApi(cast: CastLayout): string {
+  return (
+    // rzSubjectCount FIRST, because CAST_API is written against it and this
+    // module has no view uniform to read the engine's count out of. Scanning
+    // for a subject whose bounding sphere has a radius is the same answer by a
+    // different route — the seam is named at the top of cast-api.ts.
+    `
+fn rzSubjectCount() -> i32 {
+  var n = 0;
+  for (var i = 0; i < RZ_SUBJECTS; i++) {
+    if (_rzCast[i * 3 + 2].w > 0.0) { n = i + 1; }
+  }
+  return n;
+}
+` +
+    CAST_API +
+    trailSlotsApi(cast.trailCount) +
+    anchorAliasWgsl(cast.alias)
+  )
+}
+
+/** How the author's quads combine with the scene. */
+type ParticleBlend = "alpha" | "additive"
+
+type ParticleSource = {
+  /** The author's WGSL verbatim. */
+  wgsl: string
+  /** Simultaneous particles. Fixed at install; the pool recycles rather than grows. */
+  count: number
+  blend: ParticleBlend
+  /** Feed the bloom pyramid. Off by default — rain should not glow. */
+  bloom: boolean
+}
+
+/** Bytes per particle. Explicitly padded — see the struct below. */
+export const PARTICLE_STRIDE = 48
+
+
+const CAMERA_STRUCT = /* wgsl */ `
+struct CameraU {
+  view: mat4x4f,
+  proj: mat4x4f,
+  camPos: vec3f,
+  targetHeight: f32,
+}
+`
+
+const PARTICLE_UNIFORMS = /* wgsl */ `
+struct ParticleU {
+  time: f32,
+  dt: f32,
+  count: u32,
+  frame: u32,
+}
+`
+
+/**
+ * This module's half of the prelude: the camera, from its own uniform.
+ *
+ * The rest — hashes, noise, falloff, clock, viewport — is shared with every
+ * other module that hosts an effect's source, because an author's helper must
+ * mean the same thing in whichever one it lands in.
+ */
+const PRELUDE =
+  // The hashes, the noise and rzFalloff, identical in every module that hosts an
+  // effect's source; then the clock and the viewport, which cannot be, because
+  // this module keeps both in its own uniforms.
+  EFFECT_MATH_API +
+  clockApi("pu.time", "pu.dt") +
+  viewportApi("cam.targetHeight") +
+  /* wgsl */ `
+${RZ_LIGHT_STRUCT_WGSL}
+fn rzCameraPos() -> vec3f { return cam.camPos; }
+fn rzCameraRight() -> vec3f { return vec3f(cam.view[0][0], cam.view[1][0], cam.view[2][0]); }
+fn rzCameraUp() -> vec3f { return vec3f(cam.view[0][1], cam.view[1][1], cam.view[2][1]); }
+fn rzCameraForward() -> vec3f { return vec3f(cam.view[0][2], cam.view[1][2], cam.view[2][2]); }
+/** World point → (uv, view distance), same contract as the field mounts' rzProject. */
+fn rzProject(p: vec3f) -> vec3f {
+  let clip = cam.proj * cam.view * vec4f(p, 1.0);
+  let w = max(clip.w, 1e-4);
+  return vec3f(clip.xy / w * 0.5 + 0.5, clip.w);
+}
+fn rzCamPos() -> vec3f { return cam.camPos; }
+`
+
+/** `// @particles 4096` — how many live at once. */
+export function parseParticleCount(wgsl: string, max: number): number {
+  const m = /^\s*\/\/\s*@particles\s+(\d+)\s*$/m.exec(wgsl)
+  if (!m) return 0
+  // Clamped rather than rejected: an author asking for a million gets the most
+  // the engine will give and a scene that still runs, which is a better failure
+  // than a compile error naming a number they had no way to know.
+  return Math.max(1, Math.min(max, parseInt(m[1], 10)))
+}
+
+/** `// @bloom` — opt in to the bloom pyramid. Sparks want it; rain does not. */
+export function parseParticleBloom(wgsl: string): boolean {
+  return /^\s*\/\/\s*@bloom\s*$/m.test(wgsl)
+}
+
+/** `// @blend additive` — default is straight alpha. */
+export function parseParticleBlend(wgsl: string): ParticleBlend {
+  return /^\s*\/\/\s*@blend\s+additive\s*$/m.test(wgsl) ? "additive" : "alpha"
+}
+
+/** Does the source define the particle contract? All three are required together. */
+export function particleEntryPoints(wgsl: string): { init: boolean; step: boolean; shade: boolean } {
+  return {
+    init: /\bfn\s+particleInit\s*\(/.test(wgsl),
+    step: /\bfn\s+particleStep\s*\(/.test(wgsl),
+    shade: /\bfn\s+particleShade\s*\(/.test(wgsl),
+  }
+}
+
+/**
+ * Spawn, age, recycle.
+ *
+ * One kernel for both birth and update, because a dead slot and a new particle
+ * are the same write — a pool that recycles has no allocation and therefore no
+ * spawn-rate bookkeeping to get wrong. The cost is that lifetimes are staggered
+ * only by whatever the author randomises in `particleInit`, which for rain and
+ * snow is exactly right, and for a burst is what the age offset is for.
+ */
+export function buildParticleComputeShader(src: ParticleSource, cast: CastLayout): string {
+  return (
+    PARTICLE_STRUCT_WGSL +
+    CAMERA_STRUCT +
+    PARTICLE_UNIFORMS +
+    `
+@group(0) @binding(0) var<storage, read_write> particles: array<Particle>;
+@group(0) @binding(1) var<uniform> pu: ParticleU;
+@group(0) @binding(2) var<uniform> cam: CameraU;
+@group(0) @binding(3) var<storage, read> _rzCast: array<vec4f>;
+` +
+    castApi(cast) +
+    audioApi(0, 4) +
+    midiApi(0, 5) +
+    lyricsApi(0, 6) +
+    PRELUDE +
+    "\n// ── user effect ──\n" +
+    src.wgsl +
+    /* wgsl */ `
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= pu.count) { return; }
+  var p = particles[i];
+  if (p.life <= 0.0 || p.age >= p.life) {
+    // The seed is stable per SLOT and per generation, so a particle looks the
+    // same every time the scene is replayed at the same moment — which is what
+    // keeps an exported video identical to the preview.
+    let generation = floor(pu.time * 0.37) + f32(i) * 0.618;
+    p = particleInit(i, rzHash11(generation));
+    // age is NOT reset here. WGSL zero-initialises a var, so an author who
+    // ignores it starts at zero anyway — while one who sets it to a fraction of
+    // its life staggers the pool, which is the difference between snow and a
+    // pulse of snow arriving all at once every few seconds.
+  } else {
+    p = particleStep(p, pu.dt);
+    p.age = p.age + pu.dt;
+  }
+  particles[i] = p;
+}
+`
+  )
+}
+
+/**
+ * One camera-facing quad per live particle.
+ *
+ * Six vertices, no index or vertex buffer: the corners are derived from
+ * `vertex_index` and the particle is read from storage by `instance_index`, so a
+ * draw is `draw(6, count)` and there is nothing to upload per frame. The billboard
+ * basis comes from the VIEW matrix's rows rather than from a look-at, which keeps
+ * the quad square on screen no matter where the camera rolls.
+ *
+ * A dead particle collapses to a degenerate quad instead of being culled on the
+ * CPU — the alternative is a compacted draw list, which costs a prefix sum and a
+ * readback every frame to save vertices the rasteriser was going to reject anyway.
+ */
+export function buildParticleRenderShader(src: ParticleSource, cast: CastLayout): string {
+  return (
+    `override BLOOM: bool = ${src.bloom ? "true" : "false"};
+override ADDITIVE: bool = ${src.blend === "additive" ? "true" : "false"};\n` +
+    PARTICLE_STRUCT_WGSL +
+    CAMERA_STRUCT +
+    PARTICLE_UNIFORMS +
+    `
+@group(0) @binding(0) var<storage, read> particles: array<Particle>;
+@group(0) @binding(1) var<uniform> pu: ParticleU;
+@group(0) @binding(2) var<uniform> cam: CameraU;
+@group(0) @binding(3) var<storage, read> _rzCast: array<vec4f>;
+` +
+    castApi(cast) +
+    audioApi(0, 4) +
+    midiApi(0, 5) +
+    lyricsApi(0, 6) +
+    PRELUDE +
+    "\n// ── user effect ──\n" +
+    src.wgsl +
+    /* wgsl */ `
+struct VSOut {
+  @builtin(position) clip: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) @interpolate(flat) id: u32,
+}
+
+@vertex
+fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut {
+  var out: VSOut;
+  out.id = ii;
+  let p = particles[ii];
+  // Two triangles, corners in the order 0,1,2, 2,1,3.
+  let quad = array<vec2f, 6>(
+    vec2f(-1.0, -1.0), vec2f(1.0, -1.0), vec2f(-1.0, 1.0),
+    vec2f(-1.0, 1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0),
+  );
+  let c = quad[vi];
+  out.uv = c * 0.5 + 0.5;
+  if (p.life <= 0.0) {
+    // Degenerate: off the near plane, rasterises nothing.
+    out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
+    return out;
+  }
+  let right = vec3f(cam.view[0][0], cam.view[1][0], cam.view[2][0]);
+  let up = vec3f(cam.view[0][1], cam.view[1][1], cam.view[2][1]);
+  let s = sin(p.rot);
+  let k = cos(p.rot);
+  var r = vec2f(c.x * k - c.y * s, c.x * s + c.y * k);
+  // Stretched along the direction of travel ON SCREEN — which is not the world
+  // direction once the camera is off-axis. Rain falling straight down is nearly
+  // a point when viewed from above and a long streak from the side, and taking
+  // the velocity's components in the camera's own basis is what gets both right.
+  // Rotation is ignored while stretched: the velocity IS the orientation.
+  if (p.stretch > 1.0) {
+    let vr = dot(p.vel, right);
+    let vu = dot(p.vel, up);
+    let vlen = length(vec2f(vr, vu));
+    if (vlen > 1e-5) {
+      let d = vec2f(vr, vu) / vlen;
+      r = vec2f(d.y, -d.x) * c.x + d * (c.y * p.stretch);
+    }
+  }
+  let world = p.pos + (right * r.x + up * r.y) * p.size;
+  out.clip = cam.proj * cam.view * vec4f(world, 1.0);
+  return out;
+}
+
+struct FSOut {
+  @location(0) color: vec4f,
+  // The scene's aux target: (bloom mask, coverage). Materials write it, so a
+  // particle that skipped it would punch a hole in the mask of whatever it drew
+  // over.
+  //
+  // vec4f even though the target is rg8unorm and only .rg land: that target's
+  // blend factors reference SrcAlpha, and a fragment with no alpha channel is
+  // rejected outright — "reading alpha but it is missing from fragment output".
+  // The material shaders declare vec4f here for the same reason.
+  @location(1) mask: vec4f,
+}
+
+@fragment
+fn fs(in: VSOut) -> FSOut {
+  let p = particles[in.id];
+  let c = particleShade(p, in.uv);
+  if (c.a <= 0.0) { discard; }
+  var out: FSOut;
+  // PREMULTIPLIED: the scene's colour target blends with srcFactor \"one\", so a
+  // straight-alpha fragment would come out over-bright wherever it is
+  // translucent — which is most of a soft particle.
+  out.color = vec4f(c.rgb * c.a, c.a);
+  // The mask's OPERATOR must match the colour's, or the composite invents bands.
+  //
+  // The composite divides the HDR colour by this coverage to un-premultiply
+  // before tone mapping. An ALPHA effect writes (gate, 1.0) and lets the
+  // src-alpha blend make alpha-over coverage, exactly as the materials do. An
+  // ADDITIVE effect's pipeline blends this target with factor ONE instead, and
+  // writes its values directly — coverage SUMS like the colour does, so
+  // Σ(rgb·a)/Σa returns the true colour even where the effect overlaps itself.
+  // With summed colour over alpha-over coverage, every self-overlap divided into
+  // a bright white bar — visible only over the background, because the model's
+  // own coverage is already 1 there and the divide is a no-op. That mismatch,
+  // not geometry, was the banding that survived every geometry fix.
+  let mg = select(vec2f(select(0.0, 1.0, BLOOM), 1.0), vec2f(select(0.0, c.a, BLOOM), c.a), ADDITIVE);
+  out.mask = vec4f(mg.x, mg.y, 0.0, c.a);
+  return out;
+}
+`
+  )
+}

package/src/shaders/passes/scene-contract.ts

@@ -0,0 +1,266 @@
+/**
+ * The scene pass's attachment contract, in one place.
+ *
+ * Everything drawn INSIDE the scene pass — models, ground, outline hulls,
+ * particles, ribbons, and the transparent depth prepass — shares one set of
+ * attachments, and therefore one set of formats, blends and write masks. That
+ * agreement used to be restated at every pipeline that joins the pass and in
+ * every shader that writes to it, which is why adding an attachment was
+ * dangerous rather than tedious: a class left behind does not fail loudly, it
+ * fails as a validation error naming a pipeline that was never edited.
+ *
+ * So the contract is DATA here, and the pipelines ask for it by render class.
+ * Adding the id attachment (MRT) becomes one edit in this file plus a per-class
+ * decision about whether that class writes it — which is the shape of the
+ * question, and now the shape of the code.
+ *
+ * WHAT IS NOT HERE. Two passes look like they belong and do not:
+ *   - the FIELD pass has its own pair of rgba16float targets, its own blend and
+ *     no MSAA. It is a different pass with a different contract.
+ *   - the gizmo and selection-edge pipelines draw to the SWAPCHAIN in their own
+ *     unmultisampled pass, so the presentation format is the whole of their
+ *     contract. The plan listed gizmo as a scene render class; the code says
+ *     otherwise, and the code is right.
+ */
+
+/** The scene pass's attachments, as the engine has them at init. Passed in
+ *  rather than imported: hdr is chosen per device (rg11b10ufloat where it is
+ *  available and blendable, rgba16float otherwise). */
+export type SceneFormats = {
+  /** The HDR colour attachment, @location(0). */
+  hdr: GPUTextureFormat
+  /** The aux attachment, @location(1) — (bloom mask, coverage). */
+  aux: GPUTextureFormat
+}
+
+/**
+ * The id attachment's format: (material index, object index), one u16 each.
+ *
+ * Two 16-bit channels rather than one 32-bit: 32-bit formats are not
+ * multisamplable, and this attachment is multisampled with the rest of the
+ * pass. Uint targets take no blend at all per spec, which is exactly right —
+ * an averaged id is not an id.
+ */
+export const SCENE_ID_FORMAT: GPUTextureFormat = "rg16uint"
+
+/**
+ * Whether the scene pass carries the id attachment.
+ *
+ * Runtime rather than a compile-time constant, and mutable, because it is not
+ * only a decision — it is a CAPABILITY. Multisampled rg16uint has to be probed
+ * on the device (see the engine's init), and a device that cannot do it must
+ * leave this off. That forces the shaders to be assembled after the probe,
+ * which is why the two shader modules that gain an output stopped being
+ * module-level constants: a string baked at import cannot know what the device
+ * said.
+ *
+ * Set ONCE at init, before any pipeline or shader module is built. Nothing
+ * reads it per frame.
+ */
+let mrtIds = false
+
+/** Called by the engine at init, after probing the device. */
+export function setMrtIds(on: boolean): void {
+  mrtIds = on
+}
+
+export function mrtIdsEnabled(): boolean {
+  return mrtIds
+}
+
+/**
+ * What is being drawn, which is the only thing that varies.
+ *
+ * The classes differ ONLY in blend and write mask; formats are the pass's, not
+ * the draw's. A class here is a thing with a reason, not a pipeline name — two
+ * pipelines that blend the same way share one.
+ */
+type SceneRenderClass =
+  /** Models, opaque and transparent. Straight alpha over. */
+  | "material"
+  /** The shadow-catcher floor. Blends PREMULTIPLIED, not like a material: its
+   *  coverage is a lit surface plus a colourless shadow layer, so it weights
+   *  its own colour before the blend sees it. */
+  | "ground"
+  /** Backface-expanded hulls. Also a material blend — it is geometry. */
+  | "outline"
+  /** Particles and ribbons in their default, non-additive mode. */
+  | "particle"
+  /** Particles declaring `// @blend additive` — LIGHT rather than matter, so
+   *  colour sums and alpha is left alone: a glow must not claim coverage it
+   *  never occluded. The aux target sums with it, which is what lets an
+   *  additive effect reach the bloom gate at all. */
+  | "particle-additive"
+  /** Ribbons. Additive colour like the above, but premultiplied by the
+   *  fragment's own alpha on the way in (src-alpha, one) rather than added
+   *  whole, and an ordinary alpha-over aux so a ribbon's mask does not
+   *  saturate along every overlap. */
+  | "trail"
+  /** The transparent depth prepass: it exists to write DEPTH after the fabric's
+   *  colour blended, so an outline drawn later is occluded behind it. It must
+   *  therefore write no colour at all — the targets exist only to make the
+   *  pipeline compatible with the pass it joins. */
+  | "depth-prepass"
+
+const ALPHA_OVER: GPUBlendState = {
+  color: { srcFactor: "src-alpha", dstFactor: "one-minus-src-alpha", operation: "add" },
+  alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+}
+
+/** Colour sums; alpha is not touched (src zero, dst one). */
+const ADD_KEEP_ALPHA: GPUBlendState = {
+  color: { srcFactor: "one", dstFactor: "one", operation: "add" },
+  alpha: { srcFactor: "zero", dstFactor: "one", operation: "add" },
+}
+
+/** Both channels sum. rg8unorm clamps at 1, which is the saturation alpha-over
+ *  would have reached anyway. */
+const ADD_BOTH: GPUBlendState = {
+  color: { srcFactor: "one", dstFactor: "one", operation: "add" },
+  alpha: { srcFactor: "one", dstFactor: "one", operation: "add" },
+}
+
+/**
+ * OVER for something that arrives ALREADY premultiplied: take the source whole
+ * and let it displace the destination by its own coverage.
+ *
+ * The ground needs this and nothing else does. Every other class writes a
+ * straight colour and an alpha, and the src-alpha factor premultiplies it once
+ * on the way in. The ground cannot: its coverage is the SUM of a lit surface
+ * and a colourless shadow-catcher layer, so it has to weight its own colour by
+ * the surface's share before it gets here. Handed to the src-alpha blend, that
+ * weighting happened a second time.
+ */
+const PREMULTIPLIED_OVER: GPUBlendState = {
+  color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+  alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+}
+
+/** Additive, premultiplied by the fragment's alpha as it writes. */
+const ADD_PREMULTIPLIED: GPUBlendState = {
+  color: { srcFactor: "src-alpha", dstFactor: "one", operation: "add" },
+  alpha: { srcFactor: "zero", dstFactor: "one", operation: "add" },
+}
+
+/**
+ * Which classes actually WRITE an id, and so gain a fragment output for it.
+ *
+ * Everything else keeps its shader exactly as it is and takes the id target at
+ * writeMask 0 — legal, specified, and free. The alternative (leaving the target
+ * off those pipelines) is not available: every pipeline in a pass must agree
+ * with the pass's attachments.
+ *
+ * The ground is in because a mark placed by id needs the floor to have one.
+ * Transparent fabric writes ids too — dissolving a dress needs the dress's own
+ * pixels, and last write wins there, which is a documented choice rather than a
+ * consequence. Outline hulls, particles and ribbons are OUT: they are not
+ * things you would ever address by id, and a hull would overwrite the id of the
+ * body it traces.
+ */
+const WRITES_ID = new Set<SceneRenderClass>(["material", "ground"])
+
+/** The blends each class writes its two attachments with. */
+const BLENDS: Record<Exclude<SceneRenderClass, "depth-prepass">, [GPUBlendState, GPUBlendState]> = {
+  material: [ALPHA_OVER, ALPHA_OVER],
+  // PREMULTIPLIED colour, alone among the classes — see the blend's own note.
+  // The aux is ordinary alpha-over: the ground writes its mask unweighted, like
+  // everything else, and coverage is what the blend applies.
+  ground: [PREMULTIPLIED_OVER, ALPHA_OVER],
+  outline: [ALPHA_OVER, ALPHA_OVER],
+  particle: [ALPHA_OVER, ALPHA_OVER],
+  "particle-additive": [ADD_KEEP_ALPHA, ADD_BOTH],
+  trail: [ADD_PREMULTIPLIED, ALPHA_OVER],
+}
+
+/**
+ * The colour targets a scene-pass pipeline of this class declares, in
+ * attachment order.
+ *
+ * Fresh objects every call, deliberately: a caller that mutated a shared
+ * descriptor would change every pipeline built after it, and the ones built
+ * before would keep the old value — a difference that only shows up as one
+ * pipeline blending unlike its neighbours.
+ */
+export function sceneTargets(cls: SceneRenderClass, formats: SceneFormats): GPUColorTargetState[] {
+  const targets: GPUColorTargetState[] =
+    cls === "depth-prepass"
+      ? // Format only, and writeMask 0. Note the asymmetry this leans on, which
+        // is the same one the id target leans on below: a target the shader has
+        // no output for is legal at writeMask 0 (gpuweb#1918), while an output
+        // with no target is NOT governed (gpuweb#5341). This is the specified
+        // direction, and it is the only one this file ever uses.
+        [
+          { format: formats.hdr, writeMask: 0 },
+          { format: formats.aux, writeMask: 0 },
+        ]
+      : (() => {
+          const [color, aux] = BLENDS[cls]
+          return [
+            { format: formats.hdr, blend: { color: { ...color.color }, alpha: { ...color.alpha } } },
+            { format: formats.aux, blend: { color: { ...aux.color }, alpha: { ...aux.alpha } } },
+          ]
+        })()
+  if (mrtIds) targets.push({ format: SCENE_ID_FORMAT, writeMask: WRITES_ID.has(cls) ? 0xf : 0 })
+  return targets
+}
+
+/**
+ * The pass's colour attachments, in order — for the things that describe the
+ * pass itself rather than a draw within it.
+ *
+ * A render bundle declares the formats it will be replayed into and is rejected
+ * against a pass that does not match, so the bundle encoder has to move in
+ * lockstep with the targets above. It restated the list independently until
+ * this existed, which made it the one consumer an MRT change would have missed
+ * — a bundle is recorded once and replayed, so the failure would have arrived
+ * at replay, naming the bundle rather than the attachment that changed.
+ */
+export function sceneColorFormats(formats: SceneFormats): GPUTextureFormat[] {
+  return mrtIds ? [formats.hdr, formats.aux, SCENE_ID_FORMAT] : [formats.hdr, formats.aux]
+}
+
+/**
+ * The fragment-output struct a scene-pass shader returns.
+ *
+ * Emitted rather than written out per file so that the attachment list has one
+ * author. The struct and the targets above have to agree on count and order,
+ * and they now disagree in one file rather than in five.
+ *
+ * Only the shaders that will GAIN an output take this today — the materials
+ * (hand-written and graph-generated alike, through COMMON_FS_OUT_WGSL) and the
+ * ground. Outline, particles and ribbons keep their own declarations on
+ * purpose: they never write the id, so they would take an `id: false` argument
+ * forever, and their structs carry comments about their own blend that belong
+ * where they are.
+ */
+export function sceneFsOutWgsl(opts?: { name?: string; aux?: string }): string {
+  const name = opts?.name ?? "FSOut"
+  const aux = opts?.aux ?? "mask"
+  // No @interpolate here, deliberately. The plan called for
+  // `@location(2) @interpolate(flat)`, and that attribute is only legal on a
+  // vertex OUTPUT or a fragment INPUT — a fragment output is neither, so it
+  // would not compile. It is also unnecessary: the id is read from the per-draw
+  // uniform, not carried across the triangle as a varying, so there is no
+  // interpolation to suppress. (A varying carrying it WOULD need flat, since an
+  // integer varying must be.)
+  //
+  // vec2u for rg16uint: the output type must be compatible with the format, and
+  // uint targets take no blend, which is what makes last-write-wins the rule.
+  const id = mrtIds ? `  @location(2) id: vec2u,\n` : ""
+  return `struct ${name} {
+  @location(0) color: vec4f,
+  @location(1) ${aux}: vec4f,
+${id}};
+`
+}
+
+/**
+ * The line a fragment shader assigns its id with, or nothing when ids are off.
+ *
+ * Emitted rather than written into each shader for the same reason as the
+ * struct: with ids off there must be no assignment either, and a shader cannot
+ * ask the device what it supports.
+ */
+export function sceneIdWriteWgsl(out: string, material: string, object: string): string {
+  return mrtIds ? `  ${out}.id = vec2u(${material}, ${object});\n` : ""
+}