@driftengine/core 3.62.0 → 4.0.0

package/src/render/shaders/gpudriven/materialBin.wgsl.ts

@@ -0,0 +1,116 @@
+/**
+ * Binning the frame's pixels by material, in three dispatches.
+ *
+ * **Count, then sum, then scatter**, which is the only arrangement that gives each bin a
+ * contiguous slice without sorting: a pixel cannot know where it belongs until every pixel before
+ * it has been counted, so the count has to finish before the offsets exist and the offsets have to
+ * exist before anything is written.
+ *
+ * **The scatter's order inside a bin is whatever the atomics produced**, and nothing downstream
+ * may depend on it. Shading reads a bin as a set. `scripts/gpu-parity.mjs` compares the bins as
+ * sets for the same reason, and compares the *counts* exactly — which are order-free and are where
+ * a binning defect actually shows.
+ *
+ * **The sentinel test in the count and scatter passes survives perturbation**, and it is kept for
+ * the reason `materialBin.ts` states at length: `VIS_EMPTY`'s cluster field reads as 33,554,431,
+ * so the range test below it refuses the same pixels. The range test is the one a real frame
+ * exercises — a visibility buffer left over from a frame with more geometry in it — and it is
+ * caught.
+ *
+ * Hand-written for the reason `cull.wgsl.ts` gives: WebGL2 has no compute stage, so there is no
+ * GLSL original and nothing this can break by being wrong.
+ */
+
+/** Shared declarations, so the three entry points cannot disagree about the layout. */
+const BIN_PREAMBLE = `
+const VIS_TRIANGLE_BITS: u32 = 7u;
+const VIS_EMPTY: u32 = 0xffffffffu;
+
+/** pixelCount, materialCount, groupSize. */
+@group(0) @binding(0) var<storage, read> settings: array<u32, 4>;
+@group(0) @binding(1) var<storage, read> visibility: array<u32>;
+@group(0) @binding(2) var<storage, read> materialOf: array<u32>;
+`;
+
+/**
+ * Pass one: how many pixels each material owns.
+ *
+ * The counts buffer must be **cleared before this runs**. A count buffer reused across frames
+ * without clearing grows without bound, the offsets then run past the end of the pixel list, and
+ * the shading reads a neighbouring bin — which looks like one material bleeding into another.
+ */
+export const MATERIAL_COUNT_WGSL = `${BIN_PREAMBLE}
+@group(0) @binding(3) var<storage, read_write> counts: array<atomic<u32>>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= settings[0]) { return; }
+  let packed = visibility[id.x];
+  if (packed == VIS_EMPTY) { return; }
+  let cluster = packed >> VIS_TRIANGLE_BITS;
+  if (cluster >= arrayLength(&materialOf)) { return; }
+  let material = materialOf[cluster];
+  if (material >= settings[1]) { return; }
+  atomicAdd(&counts[material], 1u);
+}
+`;
+
+/**
+ * Pass two: the offsets, as an exclusive prefix sum, and the dispatch block for each material.
+ *
+ * **One invocation, deliberately.** A material count is tens, not millions, and a parallel scan
+ * over tens of elements costs more in barriers than the serial loop costs in cycles. The comment
+ * is here because "this is not parallel" reads as an oversight in a compute shader and is a
+ * measurement: the scan would be three barriers against a loop of at most a few hundred adds.
+ *
+ * **Every material gets a block, including an empty one**, whose group count is zero. Dropping it
+ * shifts every later material's arguments and shades the scene with the wrong code. The zero is
+ * the round-up's own answer rather than a branch: a `select` stood here and a perturbation
+ * survived it, because `(0 + n - 1) / n` is already zero.
+ */
+export const MATERIAL_OFFSETS_WGSL = `${BIN_PREAMBLE}
+@group(0) @binding(3) var<storage, read> counts: array<u32>;
+@group(0) @binding(4) var<storage, read_write> offsets: array<u32>;
+@group(0) @binding(5) var<storage, read_write> dispatches: array<u32>;
+
+@compute @workgroup_size(1)
+fn main() {
+  let materials = settings[1];
+  let groupSize = max(1u, settings[2]);
+  var running = 0u;
+  for (var material = 0u; material < materials; material = material + 1u) {
+    offsets[material] = running;
+    let held = counts[material];
+    running = running + held;
+    /* Zero falls out of the division: an empty bin is zero groups with no special case. */
+    let groups = (held + groupSize - 1u) / groupSize;
+    dispatches[material * 3u] = groups;
+    dispatches[material * 3u + 1u] = 1u;
+    dispatches[material * 3u + 2u] = 1u;
+  }
+}
+`;
+
+/**
+ * Pass three: every covered pixel's index into its material's slice.
+ *
+ * `cursors` is a copy of the offsets rather than the offsets themselves, because the offsets have
+ * to survive this pass — they are what tells a shading group where its material's list begins.
+ */
+export const MATERIAL_SCATTER_WGSL = `${BIN_PREAMBLE}
+@group(0) @binding(3) var<storage, read_write> cursors: array<atomic<u32>>;
+@group(0) @binding(4) var<storage, read_write> pixels: array<u32>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= settings[0]) { return; }
+  let packed = visibility[id.x];
+  if (packed == VIS_EMPTY) { return; }
+  let cluster = packed >> VIS_TRIANGLE_BITS;
+  if (cluster >= arrayLength(&materialOf)) { return; }
+  let material = materialOf[cluster];
+  if (material >= settings[1]) { return; }
+  let at = atomicAdd(&cursors[material], 1u);
+  pixels[at] = id.x;
+}
+`;

package/src/render/shaders/gpudriven/materialTable.wgsl.ts

@@ -0,0 +1,46 @@
+/**
+ * The material table's layout, declared once for everything that reads it.
+ *
+ * **Two shaders read this table now and they used to be one.** The shading pass has always read a
+ * material; since the raster gained an alpha test it reads one too, because a pixel learns which
+ * triangle owns it there and a discard any later is a discard after the visibility buffer already
+ * held the leaf. A second copy of the struct would be twenty lanes maintained in two places, which
+ * is the failure `cluster-check.mjs`'s header describes at length: two declarations of one decision
+ * drift invisibly, and the thing that breaks is a scalar read as a program index.
+ *
+ * `gpudriven/materialTable.ts` writes the lanes these fields land on and its own header says why
+ * some of them are written through a `DataView`.
+ */
+
+import { DECODE_NO_PROGRAM } from './decode.wgsl.ts';
+
+/**
+ * How many materials the table holds, and it is a declared ceiling rather than a discovered one.
+ *
+ * A uniform array in WGSL is fixed length, and the table is a uniform rather than a storage buffer
+ * because a compute stage may bind only **eight** storage buffers by default — this pass needed
+ * twelve when it was first written, and the device said so at pipeline creation. Sixty-four
+ * materials is 2 kB of the 64 kB a uniform buffer may hold; a scene wanting more wants a storage
+ * buffer and one of the eight slots back from somewhere.
+ */
+export const MATERIAL_SLOTS = 64;
+
+/** The struct and the sentinel, for any module that binds the table. */
+export const MATERIAL_TABLE_WGSL = /* wgsl */ `
+struct Material {
+  /** rgb is the tint, w is the emissive gain. */
+  tint: vec4<f32>,
+  /** x is the roughness, y the specular reflectance, z the environment's and w the metalness. */
+  surface: vec4<f32>,
+  /** Base colour, normal, ORM and emissive programs; NO_PROGRAM where there is none. */
+  programs: vec4<u32>,
+  /** u scale, v scale, normal strength, occlusion strength. */
+  maps: vec4<f32>,
+  /** Roughness scale, metallic scale, the alpha cutoff, and non-zero where this one blends. */
+  orm: vec4<f32>,
+  /** The blended opacity, and three spare. */
+  extra: vec4<f32>,
+}
+
+const NO_PROGRAM: u32 = ${DECODE_NO_PROGRAM}u;
+`;

package/src/render/shaders/gpudriven/meshTransform.wgsl.ts

@@ -0,0 +1,37 @@
+/**
+ * Placing a mesh's vertex in the world, for every stage of the pipeline that has to.
+ *
+ * **Three stages do it now and each had its own copy of it.** The visibility raster called it
+ * `transformed`, the shading pass called it `worldOf`, and the two bodies were the same nine
+ * multiplies; the blended raster would have been a third. What the copies would drift about is not
+ * the arithmetic but the *layout* — which four floats are the translation — and a stage that reads
+ * the translation from the wrong column draws a mesh somewhere else entirely while every test that
+ * builds its scene at the origin passes.
+ *
+ * **Column major, so the translation is floats 12 to 14.** `clusterWorld.ts` writes the bounds
+ * through the same convention and `sceneShadowBounds` reads them, which is what keeps a cluster's
+ * bounding sphere over the geometry it bounds.
+ *
+ * The including module declares `transforms` — sixteen floats a mesh — at whichever binding it has
+ * room for.
+ */
+export const MESH_TRANSFORM_WGSL = /* wgsl */ `
+fn worldOf(mesh: u32, p: vec3<f32>) -> vec3<f32> {
+  let m = mesh * 16u;
+  return vec3<f32>(
+    transforms[m] * p.x + transforms[m + 4u] * p.y + transforms[m + 8u] * p.z + transforms[m + 12u],
+    transforms[m + 1u] * p.x + transforms[m + 5u] * p.y + transforms[m + 9u] * p.z + transforms[m + 13u],
+    transforms[m + 2u] * p.x + transforms[m + 6u] * p.y + transforms[m + 10u] * p.z + transforms[m + 14u],
+  );
+}
+
+/* Upper three-by-three only: a direction has no translation. See the header on non-uniform scale. */
+fn rotatedOf(mesh: u32, n: vec3<f32>) -> vec3<f32> {
+  let m = mesh * 16u;
+  return vec3<f32>(
+    transforms[m] * n.x + transforms[m + 4u] * n.y + transforms[m + 8u] * n.z,
+    transforms[m + 1u] * n.x + transforms[m + 5u] * n.y + transforms[m + 9u] * n.z,
+    transforms[m + 2u] * n.x + transforms[m + 6u] * n.y + transforms[m + 10u] * n.z,
+  );
+}
+`;

package/src/render/shaders/gpudriven/present.wgsl.ts

@@ -0,0 +1,129 @@
+/**
+ * Putting the GPU-driven pipeline's colour into the frame it was invited to draw in.
+ *
+ * **A contributed pass cannot write into the frame's attachment directly and should not want
+ * to.** `pass.ts` refuses a declared write-set for a reason it states at length; what a pass gets
+ * instead is a target of its own and a draw call at the point the caller put it. So the pipeline
+ * fills a storage texture in `prepare` and this puts it on the screen in `draw` — one triangle, no
+ * sampler, and `textureLoad` at the fragment's own pixel.
+ *
+ * **`textureLoad` rather than a sampler, because there is nothing to filter.** The target is the
+ * frame's own size and the mapping is one texel to one pixel; a sampler would add a filtering mode
+ * to choose and a half-pixel offset to get wrong, in exchange for nothing. It also means the
+ * texture needs no `filterable` sample type, which `rgba16float` has but which a future `r32float`
+ * would not.
+ *
+ * **It writes linear light.** The output transform is the composite's, for the reason
+ * `PassContext` gives: with a composite the resolve grades and a pass that also graded would apply
+ * the curve twice. A frame without one is refused in words rather than papered over — see the
+ * pass's `draw`.
+ */
+
+export const GPU_DRIVEN_BLIT_WGSL = `
+struct Varying {
+  @builtin(position) position: vec4<f32>,
+}
+
+@group(0) @binding(0) var source: texture_2d<f32>;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) vertex: u32) -> Varying {
+  /* One triangle covering the frame rather than two: no shared edge, no diagonal seam, and the
+     third of the area outside the viewport costs nothing. */
+  var corners = array<vec2<f32>, 3>(
+    vec2<f32>(-1.0, -1.0),
+    vec2<f32>(3.0, -1.0),
+    vec2<f32>(-1.0, 3.0),
+  );
+  var out: Varying;
+  out.position = vec4<f32>(corners[vertex], 0.0, 1.0);
+  return out;
+}
+
+@fragment
+fn fragmentMain(in: Varying) -> @location(0) vec4<f32> {
+  /* The fragment's own pixel. Clamped rather than trusted: a frame larger than the pass's target
+     is a caller that did not resize, and reading out of bounds is a zero this would draw as a
+     black band nobody could place. */
+  let size = textureDimensions(source);
+  let at = min(vec2<u32>(in.position.xy), size - vec2<u32>(1u, 1u));
+  let texel = textureLoad(source, at, 0);
+  /*
+   * **Nothing was drawn here, so nothing is written — and that is a cost, not a correctness
+   * guard.** The target is cleared to zero and a zero laid over anything premultiplied is that
+   * thing, so the pixel would come out the same either way; this spares every pixel the pipeline
+   * did not cover a blend. Removing it left "depth-share-check.mjs" green on 2026-09-18, which is
+   * what says so. Alpha is the coverage: the shading writes one and a blended surface adds its own.
+   *
+   * **Returned as it is, premultiplied, and the pipeline blends it over.** Where the visibility
+   * buffer covered the pixel the coverage is one and over is a plain write. Where only a pane did,
+   * it is the pane's coverage, and the frame behind it — the sky — has to show through by the rest.
+   * This used to discard below a half and write the colour as opaque, which painted a heavy pane
+   * over black and dropped a light one altogether.
+   */
+  if (texel.a <= 0.0) { discard; }
+  return texel;
+}
+`;
+
+/**
+ * The same blit, handing the frame the pass's depth as well as its colour.
+ *
+ * **Two pipelines in one frame need one depth buffer.** The blit above presents colour and nothing
+ * else, which is right for a consumer whose whole scene is this pipeline — and wrong for one that
+ * draws its own geometry beside it, because then a forward-path mesh behind GPU-driven geometry has
+ * nothing to be hidden by. No ordering fixes that: drawn before the blit it is painted over, drawn
+ * after it floats in front of a hill.
+ *
+ * **The formats already agree.** The pass's depth texture and the frame's both take `DEPTH_FORMAT`
+ * and `DEPTH_COMPARE` from `depthConvention.ts`, so this is the same format and the same reversed
+ * convention and there is no conversion to get wrong. `gpuDrivenPass.ts` asserts that rather than
+ * trusting it, because a backend that ever differed would produce a depth test that is silently
+ * inverted instead of one that fails.
+ *
+ * **A pixel the pipeline did not cover is discarded before it writes**, exactly as above, so the
+ * sky keeps the depth the frame already had rather than being pushed to the near plane. A pixel
+ * only a pane covered writes the depth the pass cleared to, which is the frame's own clear — the
+ * pipeline compares "or equal" so that it passes over the sky, and what it writes there is the
+ * value already there.
+ */
+export const GPU_DRIVEN_BLIT_DEPTH_WGSL = /* wgsl */ `
+struct Varying {
+  @builtin(position) position: vec4<f32>,
+}
+
+struct Presented {
+  @location(0) colour: vec4<f32>,
+  @builtin(frag_depth) depth: f32,
+}
+
+@group(0) @binding(0) var source: texture_2d<f32>;
+@group(0) @binding(1) var sourceDepth: texture_depth_2d;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) vertex: u32) -> Varying {
+  var corners = array<vec2<f32>, 3>(
+    vec2<f32>(-1.0, -1.0),
+    vec2<f32>(3.0, -1.0),
+    vec2<f32>(-1.0, 3.0),
+  );
+  var out: Varying;
+  out.position = vec4<f32>(corners[vertex], 0.0, 1.0);
+  return out;
+}
+
+@fragment
+fn fragmentMain(in: Varying) -> Presented {
+  let size = textureDimensions(source);
+  let at = min(vec2<u32>(in.position.xy), size - vec2<u32>(1u, 1u));
+  let texel = textureLoad(source, at, 0);
+  /* A cost here too: the depth the pass cleared to passes only where the frame holds that same
+     clear, so the write would change nothing. The colour blit above says how that was measured. */
+  if (texel.a <= 0.0) { discard; }
+  var out: Presented;
+  out.colour = texel;
+  /* The depth this pixel was rastered at, so the frame tests against the surface it can see. */
+  out.depth = textureLoad(sourceDepth, at, 0);
+  return out;
+}
+`;