@driftengine/core 3.62.0 → 4.0.0

package/dist/render/shaders/gpudriven/shadow.wgsl.d.ts

@@ -0,0 +1,44 @@
+/** The directional shadow lookup for the device, as the text both consumers include. */
+/**
+ * **`gpudriven/shadow.ts` for the device, term for term, with `gpu-parity.mjs` running both.**
+ *
+ * The lesson is a week old and this is the first term written with it in hand: a shading term that
+ * exists only as a shader is a term nothing can disagree with. The lit expression had no reference
+ * until the highlight went in; this one had a reference before it had a shader.
+ *
+ * **The map is read through a function the *including* module defines**, `shadowDepthAt(u, v)`.
+ * The parity entry point reads a storage buffer, because that is what `gpuCompute.mjs` can hand a
+ * check; the shading pass reads a depth texture. What must not differ between them is the
+ * arithmetic around the read, so the arithmetic is here and the read is not.
+ *
+ * Every constant is interpolated from the reference rather than restated. A texel scale that is
+ * 1.35 here and 1.3 there is a shadow with a different softness on each path, and nothing on screen
+ * says which one is the engine's.
+ */
+export declare const SHADE_SHADOW_WGSL: string;
+/** Floats the parity entry point's settings block holds. Matches `ShadowSettings`. */
+export declare const SHADOW_SETTINGS_FLOATS = 12;
+/** Floats a receiver: the light-space clip position, the depth gradient and `n · l`. */
+export declare const SHADOW_RECEIVER_FLOATS = 8;
+/**
+ * An entry point that does nothing but look a shadow up, so `gpu-parity.mjs` can compare the
+ * function above with `gpudriven/shadow.ts` directly.
+ *
+ * It defines `shadowDepthAt` over a storage buffer, which is what a compute harness can be handed;
+ * the shading pass will define it over a depth texture. Nearest, which is what the comparison
+ * assumes — the arithmetic above measures its compensation to the texel centre.
+ */
+export declare const SHADOW_PARITY_WGSL: string;
+/** Floats a case of the receiver-plane check: three corners and the two weight gradients. */
+export declare const RECEIVER_PLANE_FLOATS = 15;
+/**
+ * The gradient assembly alone, as a dispatch, because it is the one piece of the shadow the
+ * shading pass computes for itself.
+ *
+ * The eleventh check hands the solve two derivative vectors. This is the step *before* that one:
+ * turning three light-space corners and two barycentric gradients into those vectors, which is
+ * where a factor of two or a transposed weight lives. Both are invisible in a picture — a gradient
+ * off by two compensates a tap by half of what it should, which is acne on grazing surfaces and
+ * looks like a bias that wants tuning.
+ */
+export declare const RECEIVER_PLANE_PARITY_WGSL = "\n@group(0) @binding(0) var<storage, read> params: array<f32>;\n@group(0) @binding(1) var<storage, read> cases: array<f32>;\n@group(0) @binding(2) var<storage, read_write> planes: array<f32>;\n\nfn receiverPlaneDepthGradient(dx: vec3<f32>, dy: vec3<f32>) -> vec2<f32> {\n  let determinant = dx.x * dy.y - dx.y * dy.x;\n  let conditioning = length(dx.xy) * length(dy.xy);\n  if (abs(determinant) < 1e-4 * conditioning) {\n    return vec2<f32>(0.0, 0.0);\n  }\n  return vec2<f32>(\n    (dx.z * dy.y - dx.y * dy.z) / determinant,\n    (dx.x * dy.z - dx.z * dy.x) / determinant,\n  );\n}\n\nfn receiverPlaneFromWeights(\n  l0: vec3<f32>,\n  l1: vec3<f32>,\n  l2: vec3<f32>,\n  gx: vec3<f32>,\n  gy: vec3<f32>,\n) -> vec2<f32> {\n  let dx = vec3<f32>(\n    (gx.x * l0.x + gx.y * l1.x + gx.z * l2.x) * 0.5,\n    (gx.x * l0.y + gx.y * l1.y + gx.z * l2.y) * 0.5,\n    gx.x * l0.z + gx.y * l1.z + gx.z * l2.z,\n  );\n  let dy = vec3<f32>(\n    (gy.x * l0.x + gy.y * l1.x + gy.z * l2.x) * 0.5,\n    (gy.x * l0.y + gy.y * l1.y + gy.z * l2.y) * 0.5,\n    gy.x * l0.z + gy.y * l1.z + gy.z * l2.z,\n  );\n  return receiverPlaneDepthGradient(dx, dy);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  if (id.x >= u32(params[0])) {\n    return;\n  }\n  let at = id.x * 15u;\n  let plane = receiverPlaneFromWeights(\n    vec3<f32>(cases[at], cases[at + 1u], cases[at + 2u]),\n    vec3<f32>(cases[at + 3u], cases[at + 4u], cases[at + 5u]),\n    vec3<f32>(cases[at + 6u], cases[at + 7u], cases[at + 8u]),\n    vec3<f32>(cases[at + 9u], cases[at + 10u], cases[at + 11u]),\n    vec3<f32>(cases[at + 12u], cases[at + 13u], cases[at + 14u]),\n  );\n  planes[id.x * 2u] = plane.x;\n  planes[id.x * 2u + 1u] = plane.y;\n}\n";

package/dist/render/shaders/gpudriven/shadow.wgsl.js

@@ -0,0 +1,308 @@
+/** The directional shadow lookup for the device, as the text both consumers include. */
+import { SHADOW_DEPTH_BIAS, SHADOW_DEPTH_FADE, SHADOW_PCF_OFFSETS, SHADOW_SLOPE_TEXELS, SHADOW_TERMINATOR_BAND, SHADOW_TEXEL_SCALE, } from '../../gpudriven/shadow.js';
+import { DIRECTIONAL_SHADOW_FADE_START, POINT_SHADOW_FADE_START } from '../../renderQuality.js';
+/**
+ * **`gpudriven/shadow.ts` for the device, term for term, with `gpu-parity.mjs` running both.**
+ *
+ * The lesson is a week old and this is the first term written with it in hand: a shading term that
+ * exists only as a shader is a term nothing can disagree with. The lit expression had no reference
+ * until the highlight went in; this one had a reference before it had a shader.
+ *
+ * **The map is read through a function the *including* module defines**, `shadowDepthAt(u, v)`.
+ * The parity entry point reads a storage buffer, because that is what `gpuCompute.mjs` can hand a
+ * check; the shading pass reads a depth texture. What must not differ between them is the
+ * arithmetic around the read, so the arithmetic is here and the read is not.
+ *
+ * Every constant is interpolated from the reference rather than restated. A texel scale that is
+ * 1.35 here and 1.3 there is a shadow with a different softness on each path, and nothing on screen
+ * says which one is the engine's.
+ */
+export const SHADE_SHADOW_WGSL = /* wgsl */ `
+struct ShadowSettings {
+  strength: f32,
+  mapSize: f32,
+  depthSpan: f32,
+  maxDistance: f32,
+  maxSlope: f32,
+  taps: f32,
+  padA: f32,
+  padB: f32,
+  lightDir: vec4<f32>,
+}
+
+const SHADOW_TAPS: array<vec2<f32>, ${SHADOW_PCF_OFFSETS.length}> = array<vec2<f32>, ${SHADOW_PCF_OFFSETS.length}>(
+${SHADOW_PCF_OFFSETS.map(([x, y]) => `  vec2<f32>(${x.toFixed(3)}, ${y.toFixed(3)})`).join(',\n')}
+);
+
+/*
+ * The receiver plane, from the two derivatives of the light-space position.
+ *
+ * Takes them rather than computing them: a fragment shader has dFdx and dFdy and a compute
+ * invocation has neither, so the forward path would pass what the hardware gave it and the second
+ * pipeline passes what it derives from the barycentric gradients it already has. Refused where the
+ * two-by-two system is ill-conditioned — see gpudriven/shadow.ts, which carries the argument.
+ */
+fn receiverPlaneDepthGradient(dx: vec3<f32>, dy: vec3<f32>) -> vec2<f32> {
+  let determinant = dx.x * dy.y - dx.y * dy.x;
+  let conditioning = length(dx.xy) * length(dy.xy);
+  if (abs(determinant) < 1e-4 * conditioning) {
+    return vec2<f32>(0.0, 0.0);
+  }
+  return vec2<f32>(
+    (dx.z * dy.y - dx.y * dy.z) / determinant,
+    (dx.x * dy.z - dx.z * dy.x) / determinant,
+  );
+}
+
+/*
+ * The receiver plane from the barycentric gradients the shading pass already has.
+ *
+ * gpudriven/shadow.ts is the twin and carries the argument: a light-space position is a linear
+ * combination of the three corners, so its derivative is the same combination of the weight
+ * gradients. Exact because a directional light's projection is orthographic.
+ *
+ * The halving on x and y is the remap into the map's 0-to-1 coordinates. Depth is not halved,
+ * because this pipeline's light matrix already emits z in 0..1.
+ */
+fn receiverPlaneFromWeights(
+  l0: vec3<f32>,
+  l1: vec3<f32>,
+  l2: vec3<f32>,
+  gx: vec3<f32>,
+  gy: vec3<f32>,
+) -> vec2<f32> {
+  let dx = vec3<f32>(
+    (gx.x * l0.x + gx.y * l1.x + gx.z * l2.x) * 0.5,
+    (gx.x * l0.y + gx.y * l1.y + gx.z * l2.y) * 0.5,
+    gx.x * l0.z + gx.y * l1.z + gx.z * l2.z,
+  );
+  let dy = vec3<f32>(
+    (gy.x * l0.x + gy.y * l1.x + gy.z * l2.x) * 0.5,
+    (gy.x * l0.y + gy.y * l1.y + gy.z * l2.y) * 0.5,
+    gy.x * l0.z + gy.y * l1.z + gy.z * l2.z,
+  );
+  return receiverPlaneDepthGradient(dx, dy);
+}
+
+/* How much of a shadow survives having been cast this far along the ground. */
+fn shadowReach(distance: f32, maxDistance: f32) -> f32 {
+  return 1.0 - smoothstep(maxDistance * ${POINT_SHADOW_FADE_START.toFixed(2)}, maxDistance, distance);
+}
+
+fn directionalVisibility(
+  receiverDepth: f32,
+  compareDepth: f32,
+  storedDepth: f32,
+  settings: ShadowSettings,
+) -> f32 {
+  if (compareDepth <= storedDepth) {
+    return 1.0;
+  }
+  let rayDistance = max(receiverDepth - storedDepth, 0.0) * settings.depthSpan;
+  let ground = rayDistance * length(settings.lightDir.xz);
+  return 1.0 - shadowReach(ground, settings.maxDistance);
+}
+
+/*
+ * How much light reaches a receiver: 0 in full shadow, 1 in full light.
+ *
+ * Four early-outs, and the reference records that every one is a cost rather than a correctness
+ * guard — the result is a mix by the product of all four fades, so a fade at zero returns one
+ * whether or not the return fires. They stay because each skips twelve reads. The bounds check has
+ * a second job: without it the taps read outside the map.
+ */
+fn shadowFactor(
+  lightPos: vec4<f32>,
+  depthGradient: vec2<f32>,
+  ndl: f32,
+  settings: ShadowSettings,
+) -> f32 {
+  if (settings.strength <= 0.0) {
+    return 1.0;
+  }
+  if (lightPos.w == 0.0) {
+    return 1.0;
+  }
+  /*
+   * x and y are remapped and z is not: WebGPU clips z to 0..1 already, where the GLSL this is
+   * transcribed from clips it to -1..1. See gpudriven/shadow.ts, which carries the argument.
+   */
+  let ndc = lightPos.xyz / lightPos.w;
+  let p = vec3<f32>(ndc.x * 0.5 + 0.5, ndc.y * 0.5 + 0.5, ndc.z);
+
+  let receiverFade = smoothstep(${SHADOW_TERMINATOR_BAND[0].toFixed(2)}, ${SHADOW_TERMINATOR_BAND[1].toFixed(2)}, ndl);
+  if (receiverFade <= 0.0) {
+    return 1.0;
+  }
+  if (p.z > 1.0 || p.x < 0.0 || p.x > 1.0 || p.y < 0.0 || p.y > 1.0) {
+    return 1.0;
+  }
+
+  let fromCentre = max(abs(p.x - 0.5) * 2.0, abs(p.y - 0.5) * 2.0);
+  let edgeFade = (1.0 - smoothstep(0.72, 0.98, fromCentre)) * (1.0 - smoothstep(${SHADOW_DEPTH_FADE[0].toFixed(2)}, ${SHADOW_DEPTH_FADE[1].toFixed(2)}, p.z));
+  if (edgeFade <= 0.0) {
+    return 1.0;
+  }
+
+  let slope = length(settings.lightDir.xz) / max(settings.lightDir.y, 0.001);
+  let lowElevationFade =
+    1.0 - smoothstep(settings.maxSlope * ${DIRECTIONAL_SHADOW_FADE_START.toFixed(2)}, settings.maxSlope, slope);
+  if (lowElevationFade <= 0.0) {
+    return 1.0;
+  }
+
+  let texel = ${SHADOW_TEXEL_SCALE.toFixed(2)} / settings.mapSize;
+  let slopeLimit = ${SHADOW_SLOPE_TEXELS.toFixed(1)} / settings.mapSize;
+  let taps = u32(clamp(settings.taps, 1.0, ${SHADOW_PCF_OFFSETS.length}.0));
+
+  var lit = 0.0;
+  for (var tap = 0u; tap < taps; tap = tap + 1u) {
+    let offset = SHADOW_TAPS[tap] * texel;
+    let u = p.x + offset.x;
+    let v = p.y + offset.y;
+    /*
+     * The fetched depth belongs to the centre of the containing texel, not to the continuous
+     * coordinate — so the plane compensation is measured to that centre. Following the continuous
+     * one leaves half a texel of uncompensated slope, which is the repeating ribs a grazing face
+     * shows.
+     */
+    let centreU = (floor(u * settings.mapSize) + 0.5) / settings.mapSize;
+    let centreV = (floor(v * settings.mapSize) + 0.5) / settings.mapSize;
+    let raw = depthGradient.x * (centreU - p.x) + depthGradient.y * (centreV - p.y);
+    let slopeOffset = clamp(raw, -slopeLimit, slopeLimit);
+    let receiverDepth = p.z + slopeOffset;
+    let compare = receiverDepth - ${SHADOW_DEPTH_BIAS.toFixed(2)} / settings.depthSpan;
+    lit = lit + directionalVisibility(receiverDepth, compare, shadowDepthAt(u, v), settings);
+  }
+  lit = lit / f32(taps);
+
+  let amount = settings.strength * edgeFade * lowElevationFade * receiverFade;
+  return 1.0 + (lit - 1.0) * amount;
+}
+`;
+/** Floats the parity entry point's settings block holds. Matches `ShadowSettings`. */
+export const SHADOW_SETTINGS_FLOATS = 12;
+/** Floats a receiver: the light-space clip position, the depth gradient and `n · l`. */
+export const SHADOW_RECEIVER_FLOATS = 8;
+/**
+ * An entry point that does nothing but look a shadow up, so `gpu-parity.mjs` can compare the
+ * function above with `gpudriven/shadow.ts` directly.
+ *
+ * It defines `shadowDepthAt` over a storage buffer, which is what a compute harness can be handed;
+ * the shading pass will define it over a depth texture. Nearest, which is what the comparison
+ * assumes — the arithmetic above measures its compensation to the texel centre.
+ */
+export const SHADOW_PARITY_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> params: array<f32>;
+@group(0) @binding(1) var<storage, read> settingsBuffer: array<f32>;
+@group(0) @binding(2) var<storage, read> receivers: array<f32>;
+@group(0) @binding(3) var<storage, read> shadowMap: array<f32>;
+@group(0) @binding(4) var<storage, read> gradients: array<f32>;
+@group(0) @binding(5) var<storage, read_write> factors: array<f32>;
+
+fn shadowDepthAt(u: f32, v: f32) -> f32 {
+  let size = settingsBuffer[1];
+  let x = clamp(floor(u * size), 0.0, size - 1.0);
+  let y = clamp(floor(v * size), 0.0, size - 1.0);
+  return shadowMap[u32(y) * u32(size) + u32(x)];
+}
+
+${SHADE_SHADOW_WGSL}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= u32(params[0])) {
+    return;
+  }
+  var settings: ShadowSettings;
+  settings.strength = settingsBuffer[0];
+  settings.mapSize = settingsBuffer[1];
+  settings.depthSpan = settingsBuffer[2];
+  settings.maxDistance = settingsBuffer[3];
+  settings.maxSlope = settingsBuffer[4];
+  settings.taps = settingsBuffer[5];
+  settings.lightDir = vec4<f32>(settingsBuffer[8], settingsBuffer[9], settingsBuffer[10], 0.0);
+
+  let at = id.x * ${SHADOW_RECEIVER_FLOATS}u;
+  /*
+   * The gradient is solved here rather than passed, so the solve is checked too — the corpus feeds
+   * the two derivative vectors and the reference runs the same two-by-two.
+   */
+  let gradient = receiverPlaneDepthGradient(
+    vec3<f32>(gradients[id.x * 6u], gradients[id.x * 6u + 1u], gradients[id.x * 6u + 2u]),
+    vec3<f32>(gradients[id.x * 6u + 3u], gradients[id.x * 6u + 4u], gradients[id.x * 6u + 5u]),
+  );
+  factors[id.x] = shadowFactor(
+    vec4<f32>(receivers[at], receivers[at + 1u], receivers[at + 2u], receivers[at + 3u]),
+    gradient,
+    receivers[at + 6u],
+    settings,
+  );
+}
+`;
+/** Floats a case of the receiver-plane check: three corners and the two weight gradients. */
+export const RECEIVER_PLANE_FLOATS = 15;
+/**
+ * The gradient assembly alone, as a dispatch, because it is the one piece of the shadow the
+ * shading pass computes for itself.
+ *
+ * The eleventh check hands the solve two derivative vectors. This is the step *before* that one:
+ * turning three light-space corners and two barycentric gradients into those vectors, which is
+ * where a factor of two or a transposed weight lives. Both are invisible in a picture — a gradient
+ * off by two compensates a tap by half of what it should, which is acne on grazing surfaces and
+ * looks like a bias that wants tuning.
+ */
+export const RECEIVER_PLANE_PARITY_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> params: array<f32>;
+@group(0) @binding(1) var<storage, read> cases: array<f32>;
+@group(0) @binding(2) var<storage, read_write> planes: array<f32>;
+
+fn receiverPlaneDepthGradient(dx: vec3<f32>, dy: vec3<f32>) -> vec2<f32> {
+  let determinant = dx.x * dy.y - dx.y * dy.x;
+  let conditioning = length(dx.xy) * length(dy.xy);
+  if (abs(determinant) < 1e-4 * conditioning) {
+    return vec2<f32>(0.0, 0.0);
+  }
+  return vec2<f32>(
+    (dx.z * dy.y - dx.y * dy.z) / determinant,
+    (dx.x * dy.z - dx.z * dy.x) / determinant,
+  );
+}
+
+fn receiverPlaneFromWeights(
+  l0: vec3<f32>,
+  l1: vec3<f32>,
+  l2: vec3<f32>,
+  gx: vec3<f32>,
+  gy: vec3<f32>,
+) -> vec2<f32> {
+  let dx = vec3<f32>(
+    (gx.x * l0.x + gx.y * l1.x + gx.z * l2.x) * 0.5,
+    (gx.x * l0.y + gx.y * l1.y + gx.z * l2.y) * 0.5,
+    gx.x * l0.z + gx.y * l1.z + gx.z * l2.z,
+  );
+  let dy = vec3<f32>(
+    (gy.x * l0.x + gy.y * l1.x + gy.z * l2.x) * 0.5,
+    (gy.x * l0.y + gy.y * l1.y + gy.z * l2.y) * 0.5,
+    gy.x * l0.z + gy.y * l1.z + gy.z * l2.z,
+  );
+  return receiverPlaneDepthGradient(dx, dy);
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= u32(params[0])) {
+    return;
+  }
+  let at = id.x * ${RECEIVER_PLANE_FLOATS}u;
+  let plane = receiverPlaneFromWeights(
+    vec3<f32>(cases[at], cases[at + 1u], cases[at + 2u]),
+    vec3<f32>(cases[at + 3u], cases[at + 4u], cases[at + 5u]),
+    vec3<f32>(cases[at + 6u], cases[at + 7u], cases[at + 8u]),
+    vec3<f32>(cases[at + 9u], cases[at + 10u], cases[at + 11u]),
+    vec3<f32>(cases[at + 12u], cases[at + 13u], cases[at + 14u]),
+  );
+  planes[id.x * 2u] = plane.x;
+  planes[id.x * 2u + 1u] = plane.y;
+}
+`;

package/dist/render/shaders/gpudriven/visbufferRaster.wgsl.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The raster pass.
+ *
+ * `clusterList` is the compacted output of the cull, `clusterMeta` is four words a cluster — index
+ * offset, index count, cluster identifier, mesh — and `transforms` is sixteen floats a mesh. A
+ * cluster reaches its transform through its mesh rather than carrying one, because a mesh drawn
+ * twice is two instances of one cluster set and a transform per cluster would store it twice.
+ */
+export declare const VISBUFFER_RASTER_WGSL: string;
+/**
+ * The packing alone, as a dispatch, so the layout above can be checked against the reference.
+ *
+ * **A raster pass cannot be compared to a processor-side model and a bit layout can.** What goes
+ * wrong in a visibility buffer is almost never the rasterisation — the hardware does that — it is
+ * one field overflowing into the next, silently, on the one asset whose clusters are full. So the
+ * expression is lifted out and run over generated pairs until it agrees with `packVisibility` and
+ * `unpackVisibility` for every one of them.
+ */
+export declare const VISBUFFER_PACK_WGSL = "\n@group(0) @binding(0) var<storage, read> clusters: array<u32>;\n@group(0) @binding(1) var<storage, read> triangles: array<u32>;\n@group(0) @binding(2) var<storage, read_write> packed: array<u32>;\n@group(0) @binding(3) var<storage, read_write> roundTrip: array<u32>;\n\nconst VIS_TRIANGLE_BITS: u32 = 7u;\nconst VIS_MAX_TRIANGLES: u32 = 128u;\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  if (id.x >= arrayLength(&clusters)) { return; }\n  let value = (clusters[id.x] << VIS_TRIANGLE_BITS) | (triangles[id.x] & (VIS_MAX_TRIANGLES - 1u));\n  packed[id.x] = value;\n  /* Unpacked and re-packed, so a layout that packs consistently and unpacks wrongly is caught\n     as well as one that packs wrongly at all. */\n  let cluster = value >> VIS_TRIANGLE_BITS;\n  let triangle = value & (VIS_MAX_TRIANGLES - 1u);\n  roundTrip[id.x] = select(0u, 1u, cluster == clusters[id.x] && triangle == triangles[id.x]);\n}\n";
+/**
+ * The cutout rule alone, as a dispatch, so it can be checked against `gpudriven/alphaTest.ts`.
+ *
+ * **The same function the raster calls, included rather than copied.** A second spelling of a
+ * four-line comparison is exactly the kind of thing that stays right for a year and then does not,
+ * and the failure it produces — a seam one texel wide around every cutout surface — reads as a
+ * mipmap problem. This shares the declaration, so breaking the rule breaks the check.
+ */
+export declare const VISBUFFER_ALPHA_WGSL = "\n@group(0) @binding(0) var<storage, read> alphas: array<f32>;\n@group(0) @binding(1) var<storage, read> cutoffs: array<f32>;\n@group(0) @binding(2) var<storage, read_write> kept: array<f32>;\n\nfn alphaKept(alpha: f32, cutoff: f32) -> bool {\n  if (!(cutoff > 0.0)) { return true; }\n  return alpha >= cutoff;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  if (id.x >= arrayLength(&alphas)) { return; }\n  kept[id.x] = select(0.0, 1.0, alphaKept(alphas[id.x], cutoffs[id.x]));\n}\n";

package/dist/render/shaders/gpudriven/visbufferRaster.wgsl.js

@@ -0,0 +1,245 @@
+import { GPU_DRIVEN_VERTEX_FLOATS } from '../../gpudriven/sceneUpload.js';
+import { DECODE_WGSL, decodeResourcesWgsl } from './decode.wgsl.js';
+import { MATERIAL_SLOTS, MATERIAL_TABLE_WGSL } from './materialTable.wgsl.js';
+import { MESH_TRANSFORM_WGSL } from './meshTransform.wgsl.js';
+/**
+ * The hardware path: one indirect draw that fills the visibility buffer for the whole frame.
+ *
+ * **Hand-written WGSL, for the reason `cull.wgsl.ts` gives at length**: WebGL2 has no compute
+ * stage and no indirect draw, so there is no GLSL original to generate this from and nothing it
+ * can break by being wrong. What keeps it honest is `scripts/gpu-parity.mjs`, which runs the
+ * packing below against `gpudriven/visbuffer.ts` on a real device.
+ *
+ * **Every surviving cluster is an instance of a fixed 128-triangle draw.** `indirect.ts` carries
+ * the argument layout and the reason: one block for the frame rather than thousands, and a cluster
+ * with fewer triangles emitting degenerate ones for the remainder. The degenerate case is a real
+ * branch here rather than a clamp — clamping draws a cluster's last triangle once per unused slot,
+ * which is a sliver along the edge of every cluster that is not exactly full.
+ *
+ * **The fragment writes an identifier, not a colour.** Depth is the hardware's; what lands in the
+ * target is which triangle of which cluster covered the pixel, and the shading reads it later —
+ * which is the whole point of a visibility buffer. `VIS_EMPTY` is what a caller clears the target
+ * to, because zero is a legal identifier.
+ *
+ * **It binds a material anyway, and only for the alpha test.** That is the one decision a pixel
+ * cannot defer: a cutout leaf that is discarded in the shading pass has already written its
+ * identifier here, so what stood behind it was never rastered and there is nothing left to shade.
+ * So this stage carries the material table and the whole decode machinery to answer one question —
+ * is this texel solid enough to own the pixel — and **a material whose cutoff is zero asks none of
+ * it**, which is what keeps an opaque scene paying nothing. A cluster carries one material, so the
+ * branch is coherent across every fragment of a draw rather than divergent within one.
+ *
+ * **The shadow pass shares this module's vertex stage and has no fragment stage at all**, so a
+ * cutout surface casts the shadow of its whole quad. That is a real limitation rather than an
+ * oversight: giving the depth-only pass a fragment stage would give it the material table and the
+ * decode tables too, and the map is drawn every frame over the whole scene. `docs/IMPROVEMENTS.md`
+ * carries the row.
+ */
+/**
+ * The cutout rule, which is `gpudriven/alphaTest.ts`'s `alphaKept` and must stay it.
+ *
+ * **`>=` rather than `>`** is the boundary every alpha test gets wrong, and getting it wrong shows
+ * as a one-texel seam around every leaf rather than as anything failing. **The guard is a separate
+ * return rather than arithmetic** because a NaN alpha must be discarded when a test was asked for
+ * and kept when it was not, and **it is a negated `>` rather than a `<=`** because a device may
+ * assume NaN never arrives and this is where the reference had to move to meet it. The reference's
+ * header carries both, and `scripts/gpu-parity.mjs` holds the two to each other on a device.
+ */
+const ALPHA_TEST_WGSL = /* wgsl */ `
+fn alphaKept(alpha: f32, cutoff: f32) -> bool {
+  if (!(cutoff > 0.0)) { return true; }
+  return alpha >= cutoff;
+}
+`;
+/**
+ * The footprint-to-level expression, which is `shade.wgsl.ts`'s `surfaceLod` and must stay it.
+ *
+ * **Two stages choose a mip level for one texel now**, and they choose it from different evidence:
+ * this one differences its neighbours, and the shading pass differences barycentric gradients
+ * because a compute invocation has no neighbours. What they must not differ about is what a
+ * footprint means once measured, which is this.
+ */
+const SURFACE_LOD_WGSL = /* wgsl */ `
+fn surfaceLod(gradX: vec2<f32>, gradY: vec2<f32>, size: f32) -> f32 {
+  let footprint = max(length(gradX), length(gradY)) * size;
+  return max(log2(max(footprint, 1e-30)), 0.0);
+}
+`;
+/**
+ * The raster pass.
+ *
+ * `clusterList` is the compacted output of the cull, `clusterMeta` is four words a cluster — index
+ * offset, index count, cluster identifier, mesh — and `transforms` is sixteen floats a mesh. A
+ * cluster reaches its transform through its mesh rather than carrying one, because a mesh drawn
+ * twice is two instances of one cluster set and a transform per cluster would store it twice.
+ */
+export const VISBUFFER_RASTER_WGSL = /* wgsl */ `
+struct Varying {
+  @builtin(position) position: vec4<f32>,
+  @location(0) @interpolate(flat) visibility: u32,
+  /** The cluster's material and this vertex's texture coordinate, for the alpha test. */
+  @location(1) @interpolate(flat) material: u32,
+  @location(2) uv: vec2<f32>,
+}
+
+/** The two numbers the decode machinery needs that nothing else here carries. */
+struct RasterParams {
+  /** x is the simulation time, y the latent layer's edge in texels, and two spare. */
+  values: vec4<f32>,
+}
+
+${MATERIAL_TABLE_WGSL}
+@group(0) @binding(0) var<storage, read> viewProj: array<f32, 16>;
+@group(0) @binding(1) var<storage, read> clusterList: array<u32>;
+@group(0) @binding(2) var<storage, read> clusterMeta: array<u32>;
+@group(0) @binding(3) var<storage, read> indices: array<u32>;
+/** Eleven floats a vertex: position, normal, colour, uv. One buffer, for the shading pass's
+    storage budget — see shade.wgsl.ts. This stage reads the position and the uv. */
+@group(0) @binding(4) var<storage, read> vertices: array<f32>;
+@group(0) @binding(5) var<storage, read> transforms: array<f32>;
+/** One material a cluster, read in the vertex stage and carried flat. */
+@group(0) @binding(6) var<storage, read> materialOf: array<u32>;
+@group(0) @binding(7) var<uniform> materials: array<Material, ${MATERIAL_SLOTS}>;
+@group(0) @binding(8) var<uniform> rasterParams: RasterParams;
+${decodeResourcesWgsl({ group: 0, latents: 9, clampSampler: 10, repeatSampler: 11, nodes: 12, weights: 13 })}
+fn decodeLatentSize() -> f32 {
+  return rasterParams.values.y;
+}
+
+${DECODE_WGSL}
+${SURFACE_LOD_WGSL}
+${ALPHA_TEST_WGSL}
+
+const VIS_TRIANGLE_BITS: u32 = 7u;
+const VIS_MAX_TRIANGLES: u32 = 128u;
+
+/* The same expression as packVisibility in gpudriven/visbuffer.ts, checked against it on the
+   device by scripts/gpu-parity.mjs. Seven bits of triangle, twenty-five of cluster. */
+fn packVisibility(cluster: u32, triangle: u32) -> u32 {
+  return (cluster << VIS_TRIANGLE_BITS) | (triangle & (VIS_MAX_TRIANGLES - 1u));
+}
+
+${MESH_TRANSFORM_WGSL}
+
+@vertex
+fn vertexMain(
+  @builtin(vertex_index) vertex: u32,
+  @builtin(instance_index) slot: u32,
+) -> Varying {
+  var out: Varying;
+  let cluster = clusterList[slot];
+  /* metaAt, because meta is a reserved word in WGSL. A backtick cannot appear in this comment
+     either: it would close the template literal the shader is written in. This shader was
+     committed and read by a generator check for a day before anything compiled it. */
+  let metaAt = cluster * 4u;
+  let indexOffset = clusterMeta[metaAt];
+  let indexCount = clusterMeta[metaAt + 1u];
+  let clusterId = clusterMeta[metaAt + 2u];
+  let mesh = clusterMeta[metaAt + 3u];
+
+  let triangle = vertex / 3u;
+  /* Past this cluster's own triangles: collapse to a point, which covers no pixel. See the
+     header for why this is not a clamp onto the last real triangle. */
+  if (triangle * 3u >= indexCount) {
+    out.position = vec4<f32>(0.0, 0.0, 0.0, 0.0);
+    out.visibility = 0u;
+    out.material = 0u;
+    out.uv = vec2<f32>(0.0);
+    return out;
+  }
+
+  let index = indices[indexOffset + vertex];
+  let at = index * ${GPU_DRIVEN_VERTEX_FLOATS}u;
+  let local = vec3<f32>(vertices[at], vertices[at + 1u], vertices[at + 2u]);
+  let world = worldOf(mesh, local);
+
+  out.position = vec4<f32>(
+    viewProj[0] * world.x + viewProj[4] * world.y + viewProj[8] * world.z + viewProj[12],
+    viewProj[1] * world.x + viewProj[5] * world.y + viewProj[9] * world.z + viewProj[13],
+    viewProj[2] * world.x + viewProj[6] * world.y + viewProj[10] * world.z + viewProj[14],
+    viewProj[3] * world.x + viewProj[7] * world.y + viewProj[11] * world.z + viewProj[15],
+  );
+  out.visibility = packVisibility(clusterId, triangle);
+  /* By the cluster's own record rather than the mesh's, which is where materialOf is indexed. */
+  out.material = materialOf[cluster];
+  out.uv = vec2<f32>(vertices[at + 9u], vertices[at + 10u]);
+  return out;
+}
+
+@fragment
+fn fragmentMain(in: Varying) -> @location(0) u32 {
+  let entry = materials[min(in.material, ${MATERIAL_SLOTS - 1}u)];
+  let cutoff = entry.orm.z;
+  /*
+   * **A cutoff of zero skips the fetch outright**, and with it the whole decode interpreter. That
+   * branch is on a value read from a uniform by a flat-interpolated index that is constant across
+   * the draw, so it is coherent — every fragment of a cluster takes the same side of it.
+   *
+   * **The derivatives are taken before the branch**, because a texture level derived inside
+   * non-uniform control flow is what the language forbids and a discard below makes the rest of
+   * this function non-uniform anyway. shade.wgsl.ts computes the same footprint from barycentric
+   * gradients instead, having no neighbouring invocations to difference against.
+   */
+  let uv = in.uv * entry.maps.xy;
+  let lod = surfaceLod(dpdx(uv), dpdy(uv), rasterParams.values.y);
+  /*
+   * **This branch duplicates alphaKept's own guard and is not redundant**: alphaKept answers what
+   * the picture is and this decides what the frame pays. A material with no cutout skips the
+   * decode interpreter entirely, which is the whole of why the raster can carry it at all.
+   */
+  if (cutoff > 0.0 && entry.programs.x != NO_PROGRAM) {
+    let alpha = decodeProgram(entry.programs.x, uv, lod, rasterParams.values.x).w;
+    if (!alphaKept(alpha, cutoff)) { discard; }
+  }
+  return in.visibility;
+}
+`;
+/**
+ * The packing alone, as a dispatch, so the layout above can be checked against the reference.
+ *
+ * **A raster pass cannot be compared to a processor-side model and a bit layout can.** What goes
+ * wrong in a visibility buffer is almost never the rasterisation — the hardware does that — it is
+ * one field overflowing into the next, silently, on the one asset whose clusters are full. So the
+ * expression is lifted out and run over generated pairs until it agrees with `packVisibility` and
+ * `unpackVisibility` for every one of them.
+ */
+export const VISBUFFER_PACK_WGSL = `
+@group(0) @binding(0) var<storage, read> clusters: array<u32>;
+@group(0) @binding(1) var<storage, read> triangles: array<u32>;
+@group(0) @binding(2) var<storage, read_write> packed: array<u32>;
+@group(0) @binding(3) var<storage, read_write> roundTrip: array<u32>;
+
+const VIS_TRIANGLE_BITS: u32 = 7u;
+const VIS_MAX_TRIANGLES: u32 = 128u;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= arrayLength(&clusters)) { return; }
+  let value = (clusters[id.x] << VIS_TRIANGLE_BITS) | (triangles[id.x] & (VIS_MAX_TRIANGLES - 1u));
+  packed[id.x] = value;
+  /* Unpacked and re-packed, so a layout that packs consistently and unpacks wrongly is caught
+     as well as one that packs wrongly at all. */
+  let cluster = value >> VIS_TRIANGLE_BITS;
+  let triangle = value & (VIS_MAX_TRIANGLES - 1u);
+  roundTrip[id.x] = select(0u, 1u, cluster == clusters[id.x] && triangle == triangles[id.x]);
+}
+`;
+/**
+ * The cutout rule alone, as a dispatch, so it can be checked against `gpudriven/alphaTest.ts`.
+ *
+ * **The same function the raster calls, included rather than copied.** A second spelling of a
+ * four-line comparison is exactly the kind of thing that stays right for a year and then does not,
+ * and the failure it produces — a seam one texel wide around every cutout surface — reads as a
+ * mipmap problem. This shares the declaration, so breaking the rule breaks the check.
+ */
+export const VISBUFFER_ALPHA_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> alphas: array<f32>;
+@group(0) @binding(1) var<storage, read> cutoffs: array<f32>;
+@group(0) @binding(2) var<storage, read_write> kept: array<f32>;
+${ALPHA_TEST_WGSL}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= arrayLength(&alphas)) { return; }
+  kept[id.x] = select(0.0, 1.0, alphaKept(alphas[id.x], cutoffs[id.x]));
+}
+`;