reze-engine 0.43.0 → 0.50.0

package/dist/shaders/passes/scene-contract.js

@@ -0,0 +1,207 @@
+/**
+ * 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 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 = "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) {
+    mrtIds = on;
+}
+export function mrtIdsEnabled() {
+    return mrtIds;
+}
+const ALPHA_OVER = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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(["material", "ground"]);
+/** The blends each class writes its two attachments with. */
+const BLENDS = {
+    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, formats) {
+    const targets = 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) {
+    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) {
+    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, material, object) {
+    return mrtIds ? `  ${out}.id = vec2u(${material}, ${object});\n` : "";
+}

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

@@ -0,0 +1,34 @@
+import { type CastLayout } from "./particles";
+export declare const SIM_MAX = 1024;
+/** rgba16float, ping-ponged. Two of these is the whole memory cost. */
+export declare const SIM_FORMAT: GPUTextureFormat;
+/** `// @sim 256` — the grid's resolution, in texels per side. */
+export declare function parseSimSize(wgsl: string, max: number): number;
+/** Whether this effect drives a grid at all. */
+export declare function simEntryPoint(wgsl: string): boolean;
+/**
+ * `rzSim(uv)`, for a shader that READS the grid rather than steps it.
+ *
+ * Always compiled in, even for an effect with no grid — it then samples a 1×1
+ * of zeroes. An accessor that exists only sometimes is one an author has to
+ * guard, and a missing function is a compile error rather than a blank result.
+ */
+export declare function simReadApi(group: number, tex: number, samp: number, size: number): string;
+/** `rzTime`/`rzDt`, for a module that has no clock of its own — the field pass.
+ *  Same reason as above: a spliced simStep refers to them. */
+export declare function simClockApi(timeExpr: string): string;
+/**
+ * The step shader: one invocation per texel, once per frame.
+ *
+ * The previous grid is bound as a SAMPLED texture and the next as a storage
+ * texture, which is what makes the two different resources and the whole thing
+ * legal — a shader cannot read and write one texture coherently, and the
+ * ping-pong is not an optimisation but the only correct way to do this.
+ *
+ * Sampled rather than only fetched, because advection needs to read BETWEEN
+ * texels: a semi-Lagrangian step asks "what was at the place this parcel came
+ * from", and that place is almost never a texel centre. Point-sampling it is
+ * what turns smoke into a staircase.
+ */
+export declare function buildSimShader(wgsl: string, size: number, _cast: CastLayout): string;
+//# sourceMappingURL=sim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sim.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/sim.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAgC7C,eAAO,MAAM,OAAO,OAAO,CAAA;AAC3B,uEAAuE;AACvE,eAAO,MAAM,UAAU,EAAE,gBAAgC,CAAA;AAEzD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CA6BzF;AAED;8DAC8D;AAC9D,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKpD;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAwDpF"}

package/dist/shaders/passes/sim.js

@@ -0,0 +1,169 @@
+import { audioApi } from "../audio-api";
+import { scoreApi } from "../score-api";
+import { EFFECT_SCENE_API } from "./composite";
+// A persistent grid an effect can step and read: the one thing an effect could
+// not have before, which is MEMORY.
+//
+// Every other mount is a pure function of position and time. A field shader
+// recomputes its noise from scratch every frame; a trail reads history the
+// engine happens to keep. Neither can build on what it produced last frame, and
+// a whole class of effect is nothing but that:
+//
+//   Fog that a dancer walks through does not "look displaced near her" — it IS
+//   displaced, and stays displaced, and creeps back over seconds. Water does not
+//   look rippled where a foot landed; a ripple leaves and propagates and
+//   reflects off the far edge long after the foot is gone. Both are the same
+//   shape of thing — a grid, stepped by its own previous value.
+//
+// It is also the only way to get the LOOK of a fluid, not merely its motion.
+// Advection compounds: each frame's field is the last one pushed sideways, and a
+// few hundred frames of that stretches and folds a smooth field into filaments
+// and vortex sheets finer than the grid storing them. No noise function
+// produces that, at any octave count, because the structure is not a function of
+// position at all — it is a function of history.
+//
+// The engine owns the ping-pong, the dispatch and the sampling. The author owns
+// the KERNEL, which is the part that differs: advection for smoke, the wave
+// equation for water, a decaying stamp for footprints. That split is the same
+// one the particle mounts make, and for the same reason — the loop is identical
+// in every such effect and the physics never is.
+// A megatexel of rgba16float is 8MB, and two of those is the whole cost. What
+// actually bounds this is the STEP: one invocation per texel per frame, each
+// taking a dozen samples, so doubling the side quadruples the work.
+export const SIM_MAX = 1024;
+/** rgba16float, ping-ponged. Two of these is the whole memory cost. */
+export const SIM_FORMAT = "rgba16float";
+/** `// @sim 256` — the grid's resolution, in texels per side. */
+export function parseSimSize(wgsl, max) {
+    const m = /^\s*\/\/\s*@sim\s+(\d+)\s*$/m.exec(wgsl);
+    if (!m)
+        return 0;
+    // Clamped rather than rejected, as the particle count is: an author asking for
+    // 4096 gets the most the engine will give and a scene that still runs.
+    return Math.max(8, Math.min(max, parseInt(m[1], 10)));
+}
+/** Whether this effect drives a grid at all. */
+export function simEntryPoint(wgsl) {
+    return /\bfn\s+simStep\s*\(/.test(wgsl);
+}
+/**
+ * `rzSim(uv)`, for a shader that READS the grid rather than steps it.
+ *
+ * Always compiled in, even for an effect with no grid — it then samples a 1×1
+ * of zeroes. An accessor that exists only sometimes is one an author has to
+ * guard, and a missing function is a compile error rather than a blank result.
+ */
+export function simReadApi(group, tex, samp, size) {
+    return /* wgsl */ `
+const RZ_SIM_SIZE: f32 = ${size > 0 ? size : 1}.0;
+@group(${group}) @binding(${tex}) var _rzSimTex: texture_2d<f32>;
+@group(${group}) @binding(${samp}) var _rzSimSamp: sampler;
+
+/**
+ * The grid, bilinearly sampled. uv is 0..1 across it, and what that MEANS in
+ * the world is the effect's own business — the engine deliberately does not
+ * impose a mapping, because a fog laid over a stage and a ripple field around a
+ * character want different ones and both are two lines of arithmetic.
+ */
+fn rzSim(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzSimTex, _rzSimSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+fn rzSimSize() -> f32 { return RZ_SIM_SIZE; }
+fn rzSimTexel() -> f32 { return 1.0 / RZ_SIM_SIZE; }
+
+// ── The step-only half, defined here too and never called here ──
+//
+// One effect file is spliced into EVERY module it has a mount in, so a file
+// with a grid compiles its simStep inside the field and particle shaders as
+// well — where it is dead code that nothing calls, but still code that has to
+// resolve. Leaving these out is a compile error on a function the author was
+// right to write. rzSimPrev reads the current grid rather than a previous one,
+// which is the honest answer outside the step: there is no previous frame here.
+fn rzSimPrev(uv: vec2f) -> vec4f { return rzSim(uv); }
+fn rzSimFrame() -> i32 { return 1; }
+`;
+}
+/** `rzTime`/`rzDt`, for a module that has no clock of its own — the field pass.
+ *  Same reason as above: a spliced simStep refers to them. */
+export function simClockApi(timeExpr) {
+    return /* wgsl */ `
+fn rzTime() -> f32 { return ${timeExpr}; }
+fn rzDt() -> f32 { return 0.0; }
+`;
+}
+const SIM_UNIFORMS = /* wgsl */ `
+struct SimU {
+  time: f32,
+  dt: f32,
+  size: f32,
+  frame: f32,
+}
+`;
+/**
+ * The step shader: one invocation per texel, once per frame.
+ *
+ * The previous grid is bound as a SAMPLED texture and the next as a storage
+ * texture, which is what makes the two different resources and the whole thing
+ * legal — a shader cannot read and write one texture coherently, and the
+ * ping-pong is not an optimisation but the only correct way to do this.
+ *
+ * Sampled rather than only fetched, because advection needs to read BETWEEN
+ * texels: a semi-Lagrangian step asks "what was at the place this parcel came
+ * from", and that place is almost never a texel centre. Point-sampling it is
+ * what turns smoke into a staircase.
+ */
+export function buildSimShader(wgsl, size, _cast) {
+    return (SIM_UNIFORMS +
+        /* wgsl */ `
+@group(0) @binding(0) var<uniform> su: SimU;
+@group(0) @binding(1) var _rzSimPrevTex: texture_2d<f32>;
+@group(0) @binding(2) var _rzSimSamp: sampler;
+@group(0) @binding(3) var _rzSimOut: texture_storage_2d<${SIM_FORMAT}, write>;
+@group(0) @binding(4) var<storage, read> _rzCast: array<vec4f>;
+// The same view uniform the composite reads, so the scene API below is the real
+// thing here rather than a stub — a kernel can ask where a bone is, and a
+// foreground spliced into this module resolves its camera calls.
+@group(0) @binding(6) var<uniform> viewU: array<vec4<f32>, 15>;
+
+fn rzTime() -> f32 { return su.time; }
+fn rzDt() -> f32 { return su.dt; }
+/** Texels per side. */
+fn rzSimSize() -> f32 { return su.size; }
+/** One texel, in uv — the step a neighbour lookup takes. */
+fn rzSimTexel() -> f32 { return 1.0 / su.size; }
+/**
+ * Steps since this effect was installed. Zero on the very first one, which is
+ * the only chance to seed a grid: everything after it builds on what is there.
+ */
+fn rzSimFrame() -> i32 { return i32(su.frame); }
+
+/** The grid as it was LAST frame, bilinear. The only input a kernel really has. */
+fn rzSimPrev(uv: vec2f) -> vec4f {
+  return textureSampleLevel(_rzSimPrevTex, _rzSimSamp, clamp(uv, vec2f(0.0), vec2f(1.0)), 0.0);
+}
+` +
+        EFFECT_SCENE_API +
+        audioApi(0, 5) +
+        scoreApi(0, 7) +
+        // rzSim itself, so a kernel may read the grid it is writing — through the
+        // PREVIOUS frame's texture, which is the only version of it that exists
+        // while the current one is still being written.
+        /* wgsl */ `
+fn rzSim(uv: vec2f) -> vec4f { return rzSimPrev(uv); }
+` +
+        "\n// ── user effect (setEffect) ──\n" +
+        wgsl +
+        /* wgsl */ `
+
+@compute @workgroup_size(8, 8)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let n = u32(${size});
+  if (gid.x >= n || gid.y >= n) { return; }
+  let xy = vec2i(i32(gid.x), i32(gid.y));
+  // The texel CENTRE, so a kernel that reads its own uv back through rzSimPrev
+  // lands on itself rather than a quarter-texel off.
+  let uv = (vec2f(f32(gid.x), f32(gid.y)) + vec2f(0.5)) / su.size;
+  textureStore(_rzSimOut, xy, simStep(uv, textureLoad(_rzSimPrevTex, xy, 0), su.dt));
+}
+`);
+}

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

@@ -1,8 +1,11 @@
-export type TrailSource = {
+type TrailSource = {
     /** The author's WGSL verbatim. */
     wgsl: string;
-    /** Declared anchors with `trail`, in slot order. */
+    /** How many ribbons to draw — one per trailed anchor. */
     slots: number;
+    /** For each ribbon, the LOCAL anchor slot it belongs to. Identity when every
+     *  anchor is trailed; otherwise it skips the untrailed ones. */
+    ribbonSlots: number[];
     /** Additive, like most glowing ribbons, or straight alpha. */
     blend: "alpha" | "additive";
     bloom: boolean;
@@ -43,5 +46,14 @@ export declare function buildTrailShader(src: TrailSource, cast: {
     samples: number;
     base: number;
     trailBase: number;
+    slots: number;
+    alias: number[];
+    /** Depth convention of the scene buffer this layer tests against. The
+     *  occlusion compare below is MANUAL (the layer has no depth attachment),
+     *  so it does not flip with the pipelines' depthCompare — it has to be
+     *  emitted the right way round at build time. On a reversed-Z device,
+     *  larger z is CLOSER; the unflipped test drew ribbons only when occluded. */
+    reversedZ: boolean;
 }): string;
+export {};
 //# sourceMappingURL=trails.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,WAAW,GAAG;IACxB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAsVvI"}
+{"version":3,"file":"trails.d.ts","sourceRoot":"","sources":["../../../src/shaders/passes/trails.ts"],"names":[],"mappings":"AAwBA,KAAK,WAAW,GAAG;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAA;IACb;oEACgE;IAChE,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,8DAA8D;IAC9D,KAAK,EAAE,OAAO,GAAG,UAAU,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;kFAI8E;IAC9E,SAAS,EAAE,OAAO,CAAA;CACnB,GACA,MAAM,CA6SR"}

package/dist/shaders/passes/trails.js

@@ -1,4 +1,10 @@
+import { RZ_LIGHT_STRUCT_WGSL } from "../lights";
 import { audioApi } from "../audio-api";
+import { lyricsApi } from "../lyrics-api";
+import { anchorAliasWgsl, ribbonSlotWgsl } 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";
 /**
  * Sub-segments drawn between each pair of recorded samples.
  *
@@ -33,60 +39,21 @@ export function trailEntryPoints(wgsl) {
  * of vanishing edge-on where it turns.
  */
 export function buildTrailShader(src, cast) {
-    return (`const RZ_SUBJECTS: i32 = ${cast.subjects};
-const RZ_SAMPLES: i32 = ${cast.samples};
-const RZ_SLOTS: i32 = ${src.slots};
-const RZ_TRAIL_SLOTS: i32 = ${src.slots};
+    return (CAST_API +
+        trailSlotsApi(src.slots) +
+        EFFECT_MATH_API +
+        PARTICLE_STRUCT_WGSL +
+        clockApi("tu.time", "0.0") +
+        viewportApi("cam.targetHeight") +
+        // RZ_SLOTS is this module's alone: how many ribbons to DRAW, which is the
+        // instance loop's bound. RZ_MAX_ANCHORS in CAST_API is the address space the
+        // accessors are bounded by, and the two being one number was the old trail
+        // bug — the comment that said so lived here, so it stays here.
+        `const RZ_SLOTS: i32 = ${src.slots};
+${ribbonSlotWgsl(src.ribbonSlots)}
+${anchorAliasWgsl(cast.alias)}
 const SUB: i32 = ${TRAIL_SUBDIVISIONS};
 
-// The same struct and helpers the particle modules define. The whole effect
-// file is spliced into EVERY module its mounts compile into, so an effect that
-// declares both trails and particles carries its particle functions through
-// this module as dead code — dead code that still has to type-check. Keeping
-// the two preludes' public surface identical is what makes one file, two
-// mounts work.
-struct Particle {
-  pos: vec3f,
-  age: f32,
-  vel: vec3f,
-  life: f32,
-  size: f32,
-  rot: f32,
-  seed: f32,
-  stretch: f32,
-}
-fn rzDt() -> f32 { return 0.0; }
-fn rzHash21(p: vec2f) -> f32 {
-  var p3 = fract(vec3f(p.x, p.y, p.x) * 0.1031);
-  p3 = p3 + dot(p3, p3.yzx + 33.33);
-  return fract((p3.x + p3.y) * p3.z);
-}
-fn rzHash31(p: vec3f) -> f32 {
-  var p3 = fract(p * 0.1031);
-  p3 = p3 + dot(p3, p3.zyx + 31.32);
-  return fract((p3.x + p3.y) * p3.z);
-}
-fn rzHash13(x: f32) -> vec3f {
-  return vec3f(rzHash11(x), rzHash11(x + 17.13), rzHash11(x + 41.71));
-}
-fn rzValueNoise(p: vec3f) -> f32 {
-  let i = floor(p);
-  let f = fract(p);
-  let u = f * f * (3.0 - 2.0 * f);
-  let n000 = rzHash31(i);
-  let n100 = rzHash31(i + vec3f(1.0, 0.0, 0.0));
-  let n010 = rzHash31(i + vec3f(0.0, 1.0, 0.0));
-  let n110 = rzHash31(i + vec3f(1.0, 1.0, 0.0));
-  let n001 = rzHash31(i + vec3f(0.0, 0.0, 1.0));
-  let n101 = rzHash31(i + vec3f(1.0, 0.0, 1.0));
-  let n011 = rzHash31(i + vec3f(0.0, 1.0, 1.0));
-  let n111 = rzHash31(i + vec3f(1.0, 1.0, 1.0));
-  let x00 = mix(n000, n100, u.x);
-  let x10 = mix(n010, n110, u.x);
-  let x01 = mix(n001, n101, u.x);
-  let x11 = mix(n011, n111, u.x);
-  return mix(mix(x00, x10, u.y), mix(x01, x11, u.y), u.z);
-}
 // World units a sample pair must span to count as a FULL contribution — the
 // original's REF_SEG_PX, converted out of pixels.
 //
@@ -114,9 +81,13 @@ struct TrailU {
 @group(0) @binding(0) var<storage, read> _rzCast: array<vec4f>;
 @group(0) @binding(1) var<uniform> tu: TrailU;
 @group(0) @binding(2) var<uniform> cam: CameraU;
-@group(0) @binding(3) var sceneDepth: texture_depth_multisampled_2d;
+// Binding 3 is GONE, and it had to go. Ribbons draw inside the scene pass now,
+// and the depth buffer is that pass's render attachment — binding it for
+// sampling in the same pass is a usage conflict WebGPU rejects outright:
+// "includes writable usage and another usage in the same synchronization
+// scope". The hardware depth test replaced what it was read for.
 
-fn rzTime() -> f32 { return tu.time; }
+${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]); }
@@ -127,7 +98,6 @@ fn rzProject(p: vec3f) -> vec3f {
   let w = max(clip.w, 1e-4);
   return vec3f(clip.xy / w * 0.5 + 0.5, clip.w);
 }
-fn rzViewportHeight() -> f32 { return cam.targetHeight; }
 fn rzCamPos() -> vec3f { return cam.camPos; }
 fn rzSubjectCount() -> i32 {
   var n = 0;
@@ -136,16 +106,6 @@ fn rzSubjectCount() -> i32 {
   }
   return n;
 }
-fn rzTrailCount(subject: i32, slot: i32) -> i32 {
-  if (subject < 0 || subject >= RZ_SUBJECTS || slot < 0 || slot >= RZ_SLOTS) { return 0; }
-  return i32(_rzCast[${cast.base} + (slot * RZ_SUBJECTS + subject) * 3 + 2].w);
-}
-/** Sample i of a path: xyz where it was, w how many seconds ago. i = 0 is now. */
-fn rzTrail(subject: i32, slot: i32, i: i32) -> vec4f {
-  let n = rzTrailCount(subject, slot);
-  if (i < 0 || i >= n) { return vec4f(0.0); }
-  return _rzCast[${cast.trailBase} + (slot * RZ_SUBJECTS + subject) * RZ_SAMPLES + i];
-}
 /** Catmull-Rom through four samples — passes through p1 and p2. */
 fn rzSpline(p0: vec3f, p1: vec3f, p2: vec3f, p3: vec3f, t: f32) -> vec3f {
   let t2 = t * t;
@@ -210,18 +170,10 @@ fn rzTurnRadius(a: vec3f, b: vec3f, c: vec3f) -> f32 {
   if (la < 1e-5 || lb < 1e-5 || cr < 1e-7) { return 1e6; }
   return (la * lb * length(ca)) / (2.0 * cr);
 }
-fn rzFalloff(d: f32, r: f32) -> f32 {
-  let x = clamp(d / max(r, 1e-6), 0.0, 1.0);
-  let f = 1.0 - x;
-  return f * f * f;
-}
-fn rzHash11(x: f32) -> f32 {
-  var p = fract(x * 0.1031);
-  p = p * (p + 33.33);
-  return fract(p * (p + p));
-}
 ` +
         audioApi(0, 4) +
+        midiApi(0, 5) +
+        lyricsApi(0, 6) +
         "\n// ── user effect ──\n" +
         src.wgsl +
         /* wgsl */ `
@@ -244,10 +196,14 @@ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut
   let seg = k / SUB;
   let sub = k % SUB;
   let subject = i32(rest % u32(RZ_SUBJECTS));
-  let slot = i32(rest / u32(RZ_SUBJECTS));
+  // Instance index counts RIBBONS; the cast buffer is addressed by anchor slot.
+  // One ribbon per trailed anchor, so these are the same number only when every
+  // anchor is trailed — _rzRibbonSlot is what bridges them.
+  let ribbon = i32(rest / u32(RZ_SUBJECTS));
+  let slot = _rzRibbonSlot(ribbon);
 
   let n = rzTrailCount(subject, slot);
-  if (slot >= RZ_SLOTS || seg + 1 >= n) {
+  if (ribbon >= RZ_SLOTS || seg + 1 >= n) {
     out.clip = vec4f(0.0, 0.0, -2.0, 1.0);
     out.uv = vec2f(0.0);
     out.age = 0.0;
@@ -354,22 +310,31 @@ fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut
   return out;
 }
 
+struct TrailFSOut {
+  @location(0) color: vec4f,
+  // The scene's aux target: (bloom mask, coverage). Writing mask 1 is what
+  // makes a ribbon BLOOM — it is light, and the gate is what says so.
+  @location(1) aux: vec4f,
+}
+
 @fragment
-fn fs(in: VSOut) -> @location(0) vec4f {
-  // Manual depth test against the scene's own buffer — the layer has no depth
-  // attachment, and a per-fragment compare is exactly what the fullscreen
-  // version did (segZ <= depth). position.z IS this fragment's depth.
-  let sceneD = textureLoad(sceneDepth, vec2i(in.clip.xy), 0);
-  if (in.clip.z > sceneD) { discard; }
+fn fs(in: VSOut) -> TrailFSOut {
+  // No manual depth test any more. This drew into its own attachment-less
+  // layer and compared position.z against the scene's depth texture by hand,
+  // with the direction baked per depth convention. Inside the scene pass the
+  // hardware does it, correctly and for free, and the reversed-Z trap that
+  // needed its own regression test goes with it.
   let c = trailShade(in.uv.x, in.uv.y, in.age, in.weight, i32(in.slot));
   if (c.a <= 0.0) { discard; }
-  // STRAIGHT colour, into a layer that blends with MAX — which is the
-  // original's core-takes-the-max rule turned into a blend mode. Parallel
-  // strands of a circling hand meet as max, so they can never sum into the
-  // doubled bright dashes that additive drew along the path. The layer then
-  // composites over the frame AFTER tone mapping, where the fullscreen ribbon
-  // always ran — so these colours reach the screen verbatim.
-  return vec4f(c.rgb, c.a);
+  var o: TrailFSOut;
+  // STRAIGHT colour into an ADDITIVE target, which reverses the old MAX rule
+  // deliberately: max existed so parallel strands could not double into bright
+  // dashes on a layer composited after tone mapping. In HDR before bloom,
+  // overlapping light SHOULD sum — that is what neon does — and the tone
+  // mapper is what keeps the sum from clipping.
+  o.color = vec4f(c.rgb, c.a);
+  o.aux = vec4f(${src.bloom ? "1.0" : "0.0"}, 1.0, 0.0, c.a);
+  return o;
 }
 `);
 }