reze-engine 0.43.0 → 0.50.1

package/src/shaders/materials/common.ts

@@ -1,3 +1,8 @@
+import { sceneFsOutWgsl } from "../passes/scene-contract"
+import { lightsApi } from "../lights"
+import { SHADOW_CASCADES } from "../../shadow-cascades"
+import { WORLD_AMBIENT_WGSL } from "../lights"
+
 // Shared WGSL blocks concatenated by every material shader.
 // Splits the boilerplate (uniform structs, bind group layout, skinning VS, PCF shadow)
 // away from the per-material fragment code so each material file only contains what
@@ -37,6 +42,8 @@ struct Light {
 struct LightUniforms {
   ambientColor: vec4f,
   lights: array<Light, 4>,
+  /** Irradiance SH of the HDRI world; [0].w is the on-flag. */
+  sh: array<vec4f, 9>,
 };
 
 // Per-material uniforms. Every material binds this layout even if it ignores fields;
@@ -53,8 +60,15 @@ struct MaterialUniforms {
   // Skeleton index of the 頭 (head) bone, or -1. Lets the eye shader gate
   // the post-alpha-eye stencil by camera-vs-face hemisphere.
   headBoneIndex: f32,
-  _pad0: f32,
-  _pad1: f32,
+  // The draw's identity, for the id attachment: which material, which object.
+  // They ride HERE, in padding this struct already carried, so the buffer's
+  // size and layout are untouched and the indirect-draw path keeps working —
+  // the ids arrive with the same per-draw uniform the material already binds,
+  // rather than needing a channel of their own. Zero while ids are off, and
+  // zero is the reserved "nothing" value, so reading them then is not wrong,
+  // just empty. f32 because the buffer is written as floats; the shader casts.
+  materialId: f32,
+  objectId: f32,
   _pad2: f32,
 };
 
@@ -72,7 +86,9 @@ struct VertexOutput {
   @location(3) restPos: vec3f,
 };
 
-struct LightVP { viewProj: mat4x4f, };
+// One view-projection per shadow cascade, inner to outer — the volumes built
+// by shadow-cascades.ts, in the same order.
+struct LightVP { viewProj: array<mat4x4f, ${SHADOW_CASCADES.length}>, };
 
 @group(0) @binding(0) var<uniform> camera: CameraUniforms;
 @group(0) @binding(1) var<uniform> light: LightUniforms;
@@ -80,6 +96,10 @@ struct LightVP { viewProj: mat4x4f, };
 @group(0) @binding(3) var shadowMap: texture_depth_2d;
 @group(0) @binding(4) var shadowSampler: sampler_comparison;
 @group(0) @binding(5) var<uniform> lightVP: LightVP;
+// The far cascade's map — coarser texels over a much wider box, so the stage
+// keeps its shadows when the crisp near volume ends. Binding 7: 6 is the
+// positional lights, 9 the BRDF LUT.
+@group(0) @binding(7) var shadowMapFar: texture_depth_2d;
 // binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).
 @group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
 @group(2) @binding(0) var diffuseTexture: texture_2d<f32>;
@@ -111,33 +131,62 @@ fn safe_normal(nIn: vec3f) -> vec3f {
 
 `;
 
-// ─── Shadow sampler (3×3 PCF) ───────────────────────────────────────
-// 4096-map (MUST match Engine.SHADOW_MAP_SIZE), normal-bias 0.08, depth-bias
-// 0.001. Unrolled — Safari's Metal backend doesn't unroll nested shadow loops
-// reliably. The texel size was stale at 1/2048 after the map grew to 4096:
-// PCF taps landed TWO texels apart, quantizing self-shadow edges into
-// texel-sized gray/black squares that crawled with the animation.
+// ─── Shadow sampler (3×3 PCF, cascade-selected) ─────────────────────
+// Normal-bias 0.08, depth-bias 0.001 NDC. Unrolled — Safari's Metal backend
+// doesn't unroll nested shadow loops reliably. Texel sizes are interpolated
+// from SHADOW_CASCADES so they cannot go stale the way the hardcoded 1/2048
+// once did (PCF taps landed TWO texels apart after the map grew to 4096,
+// quantizing self-shadow edges into crawling gray squares).
+//
+// Selection: the crisp near cascade wherever its box covers the point — with a
+// margin that keeps the whole PCF kernel inside the map, so selection never
+// mixes maps mid-kernel — else the far cascade, else LIT. Lit is a fix, not
+// merely a default: the old single-volume path clamped, and past the light's
+// far plane the comparison failed against every stored depth, silently
+// shadowing any stage deeper than the box.
+
+const pcf9 = (map: string, ts: string) => /* wgsl */ `
+  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
+  let cmpZ = ndc.z - 0.001;
+  let ts = ${ts};
+  let s00 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);
+  let s10 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);
+  let s20 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts, -ts), cmpZ);
+  let s01 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);
+  let s11 = textureSampleCompareLevel(${map}, shadowSampler, suv, cmpZ);
+  let s21 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);
+  let s02 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);
+  let s12 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);
+  let s22 = textureSampleCompareLevel(${map}, shadowSampler, suv + vec2f( ts,  ts), cmpZ);
+  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
+`
 
-export const SAMPLE_SHADOW_WGSL = /* wgsl */ `
+const SAMPLE_SHADOW_WGSL = /* wgsl */ `
+
+fn sampleShadowNear(ndc: vec3f) -> f32 {
+${pcf9("shadowMap", `1.0 / ${SHADOW_CASCADES[0].mapSize}.0`)}
+}
+
+fn sampleShadowFar(ndc: vec3f) -> f32 {
+${pcf9("shadowMapFar", `1.0 / ${SHADOW_CASCADES[SHADOW_CASCADES.length - 1].mapSize}.0`)}
+}
 
 fn sampleShadow(worldPos: vec3f, n: vec3f) -> f32 {
   if (dot(n, -light.lights[0].direction.xyz) <= 0.0) { return 0.0; }
   let biasedPos = worldPos + n * 0.08;
-  let lclip = lightVP.viewProj * vec4f(biasedPos, 1.0);
-  let ndc = lclip.xyz / max(lclip.w, 1e-6);
-  let suv = vec2f(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
-  let cmpZ = ndc.z - 0.001;
-  let ts = 1.0 / 4096.0;
-  let s00 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, -ts), cmpZ);
-  let s10 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0, -ts), cmpZ);
-  let s20 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, -ts), cmpZ);
-  let s01 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts, 0.0), cmpZ);
-  let s11 = textureSampleCompareLevel(shadowMap, shadowSampler, suv, cmpZ);
-  let s21 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts, 0.0), cmpZ);
-  let s02 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(-ts,  ts), cmpZ);
-  let s12 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f(0.0,  ts), cmpZ);
-  let s22 = textureSampleCompareLevel(shadowMap, shadowSampler, suv + vec2f( ts,  ts), cmpZ);
-  return (s00 + s10 + s20 + s01 + s11 + s21 + s02 + s12 + s22) * (1.0 / 9.0);
+  let c0 = lightVP.viewProj[0] * vec4f(biasedPos, 1.0);
+  let n0 = c0.xyz / max(c0.w, 1e-6);
+  if (all(abs(n0.xy) < vec2f(0.98)) && n0.z > 0.0 && n0.z < 1.0) {
+    return sampleShadowNear(n0);
+  }
+  let c1 = lightVP.viewProj[1] * vec4f(biasedPos, 1.0);
+  let n1 = c1.xyz / max(c1.w, 1e-6);
+  if (all(abs(n1.xy) < vec2f(0.98)) && n1.z > 0.0 && n1.z < 1.0) {
+    return sampleShadowFar(n1);
+  }
+  // Outside every cascade there is no occlusion information; lit is the only
+  // honest answer.
+  return 1.0;
 }
 
 `;
@@ -148,7 +197,7 @@ fn sampleShadow(worldPos: vec3f, n: vec3f) -> f32 {
 // VS normalize on the outgoing normal is skipped — interpolation denormalizes it
 // anyway and every fragment shader does `normalize(input.normal)` as its first line.
 
-export const COMMON_VS_WGSL = /* wgsl */ `
+const COMMON_VS_WGSL = /* wgsl */ `
 
 @vertex fn vs(
   @location(0) position: vec3f,
@@ -200,18 +249,23 @@ export const COMMON_VS_WGSL = /* wgsl */ `
 //   out.r = mask_r · src.a + dst.r · (1-src.a)   (bloom mask, weighted by alpha)
 //   out.g = 1.0    · src.a + dst.g · (1-src.a)   (canonical premultiplied alpha-over)
 
-export const COMMON_FS_OUT_WGSL = /* wgsl */ `
-
-struct FSOut {
-  @location(0) color: vec4f,
-  @location(1) mask: vec4f,
-};
-
-`;
+// The struct itself comes from scene-contract, which owns what the scene pass's
+// attachments ARE — this is one of the two shaders that gains an output when
+// one is added, and the graph generator emits against this same declaration.
+//
+// A FUNCTION, and no longer part of the prelude constant below, because the id
+// attachment is a device capability probed at init: a struct baked at import
+// time would be built before the answer exists. The graph appends it where the
+// constant used to end, so the assembled module is unchanged.
+export function commonFsOutWgsl(): string {
+  return `\n\n${sceneFsOutWgsl()}\n`;
+}
 
 // ─── Convenience: full shared prelude ───────────────────────────────
 // Material files compose this as `${NODES_WGSL}${COMMON_MATERIAL_PRELUDE_WGSL}` to
 // pull in everything structural. Each material then adds its own constants + fs().
 
+// The FSOut struct is NOT in here any more — see commonFsOutWgsl above. Every
+// consumer of this constant appends it immediately, which is where it was.
 export const COMMON_MATERIAL_PRELUDE_WGSL =
-  COMMON_BINDINGS_WGSL + SAMPLE_SHADOW_WGSL + COMMON_VS_WGSL + COMMON_FS_OUT_WGSL
+  COMMON_BINDINGS_WGSL + WORLD_AMBIENT_WGSL + lightsApi(0, 6) + SAMPLE_SHADOW_WGSL + COMMON_VS_WGSL

package/src/shaders/midi-api.ts

@@ -0,0 +1,116 @@
+// The score data interface, as WGSL — shared verbatim by every effect module.
+//
+// The sibling of the audio interface, and precomputed for the same reason: an
+// export steps the engine frame by frame rather than playing in real time, so
+// anything read live from a player would render empty into the exported video.
+// A note list is inherently precomputed, so it cannot even be tempted.
+//
+// WHY THIS EXISTS BESIDE rzAudio* RATHER THAN INSTEAD OF IT. The audio interface
+// answers "how loud is the bass right now" — a spectrum, smeared across
+// frequency and time. That is the right shape for a reactive backdrop and the
+// wrong shape for a note: you cannot recover a discrete onset, a pitch and a
+// duration from band energy, and the crispness of a falling note is the whole
+// point of the look. The two are complementary — a scene can pulse its fog on
+// rzAudioOnset while its notes fall on rzNoteAge.
+//
+// LAYOUT. An 8-float header, then a 128-float live key map, then the notes at 4
+// floats each (start, duration, pitch, velocity). `time` and `playing` are
+// rewritten every frame by whoever owns playback, exactly as the audio header
+// is, so "now" is always the clock actually running.
+//
+// THE KEY MAP IS THE POINT OF THE DESIGN. Falling notes index the note list
+// directly — one particle per note, which is what makes the geometry trivial.
+// But a keyboard glow asks the opposite question, per pixel: is anything
+// sounding at THIS pitch? Answering that by scanning the note list would be
+// thousands of iterations per fragment. So the engine keeps a 128-entry
+// per-pitch energy map, updated once per frame on the CPU, and the glow becomes
+// one lookup — the same trade the audio interface makes by precomputing onset
+// so "a beat-triggered effect is one comparison instead of a per-pixel history
+// scan".
+
+/** Floats before the key map: count, pitch range, clock, duration, release. */
+export const MIDI_HEADER = 8
+/** One energy slot per MIDI pitch. 128 is the MIDI range, not a cap we chose. */
+export const MIDI_KEYS = 128
+/** Where the note records begin. */
+export const MIDI_NOTES = MIDI_HEADER + MIDI_KEYS
+/** Floats per note: start, duration, pitch, velocity. */
+export const MIDI_STRIDE = 4
+
+/** The rzNote*/ /* rzKey* accessors, with the buffer declared at the given binding. */
+export function midiApi(group: number, binding: number): string {
+  return /* wgsl */ `
+@group(${group}) @binding(${binding}) var<storage, read> _rzMidi: array<f32>;
+
+/** Notes in the score; 0 when none is loaded, which every accessor below
+ *  tolerates by returning zero rather than reading past the end. */
+fn rzNoteCount() -> i32 { return i32(_rzMidi[0]); }
+/** Where the score is NOW, in seconds — the clock every age below hangs from. */
+fn rzMidiTime() -> f32 { return _rzMidi[3]; }
+/** 1 while the score is advancing, 0 paused or absent. */
+fn rzMidiPlaying() -> f32 { return select(0.0, _rzMidi[4], i32(_rzMidi[0]) > 0); }
+/** Last note-off, in seconds — the length of the piece. */
+fn rzMidiDuration() -> f32 { return _rzMidi[5]; }
+/** Lowest and highest pitch the score actually uses. Lay a keyboard out against
+ *  these rather than against 0..127 and a piano piece fills the screen instead
+ *  of occupying its middle third. */
+fn rzPitchLow() -> f32 { return _rzMidi[1]; }
+fn rzPitchHigh() -> f32 { return _rzMidi[2]; }
+
+fn _rzNoteAt(i: i32, field: i32) -> f32 {
+  if (i < 0 || i >= i32(_rzMidi[0])) { return 0.0; }
+  return _rzMidi[${MIDI_NOTES} + i * ${MIDI_STRIDE} + field];
+}
+
+/** When note i begins, in seconds. */
+fn rzNoteStart(i: i32) -> f32 { return _rzNoteAt(i, 0); }
+/** How long note i sounds, in seconds. */
+fn rzNoteLength(i: i32) -> f32 { return _rzNoteAt(i, 1); }
+/** MIDI pitch of note i — 60 is middle C. */
+fn rzNotePitch(i: i32) -> f32 { return _rzNoteAt(i, 2); }
+/** How hard note i was struck, 0..1. */
+fn rzNoteVelocity(i: i32) -> f32 { return _rzNoteAt(i, 3); }
+
+/**
+ * Seconds since note i began — NEGATIVE before it does.
+ *
+ * The falling-note function, and the sign is the whole of it: a note's height is
+ * -rzNoteAge(i) * speed, so a note not yet played sits above the keyboard at a
+ * distance proportional to how long is left, crosses zero exactly as it sounds,
+ * and keeps going. One expression, no state, no spawning — which is why one
+ * particle per note is the natural mapping and the pool index IS the note index.
+ */
+fn rzNoteAge(i: i32) -> f32 { return _rzMidi[3] - rzNoteStart(i); }
+
+/** 1 while note i is sounding, 0 either side of it. */
+fn rzNoteHeld(i: i32) -> f32 {
+  let age = rzNoteAge(i);
+  return select(0.0, 1.0, age >= 0.0 && age < rzNoteLength(i));
+}
+
+/**
+ * Energy at a MIDI pitch right now: 1 the instant it is struck, holding while
+ * sounding, then falling away over the release set at install time.
+ *
+ * Per PITCH rather than per note, because that is the question a keyboard asks
+ * and a note list cannot answer cheaply — see the header. Fractional pitches
+ * read the nearest key, so a caller can hand this a continuous x across the
+ * keyboard without rounding first.
+ */
+fn rzKeyEnergy(pitch: f32) -> f32 {
+  let k = i32(round(pitch));
+  if (k < 0 || k >= ${MIDI_KEYS}) { return 0.0; }
+  return _rzMidi[${MIDI_HEADER} + k];
+}
+
+/**
+ * A pitch's place across the score's own range, 0..1 — the x of a falling note
+ * and of the key it lands on, which have to agree or the effect is nonsense.
+ */
+fn rzPitchX(pitch: f32) -> f32 {
+  let lo = _rzMidi[1];
+  let hi = _rzMidi[2];
+  return select(0.5, (pitch - lo) / max(hi - lo, 1.0), hi > lo);
+}
+`
+}