@driftengine/core 3.63.0 → 4.1.0

package/src/render/gpudriven/ibl.ts

@@ -0,0 +1,147 @@
+/** The split sum's second half, in TypeScript, so the second pipeline's copy has a reference. */
+
+/**
+ * **`flat/lobes.ts` in TypeScript: how much of an environment a surface returns.**
+ *
+ * The convolution decides *what* a surface reflects — a rougher one reads a blurrier level of the
+ * prefiltered chain — and this decides *how much*. Both halves are a fit and an algebraic
+ * compensation, which is to say both are arithmetic nobody can check by looking at a frame: the
+ * failure they exist to prevent was reported twice from consumers as *metals reading opaque*, and
+ * traced to a term that asserts a perfect mirror absorbs 55% of the light once it is roughened.
+ *
+ * **Metalness is a per-material scalar here, not an ORM map.** `flat/main.ts` reads it per texel
+ * from the blue channel of an occlusion-roughness-metallic image, which is a thing this pipeline
+ * has no textures to read; a GPU-driven material carries one number instead. That is a *subset* and
+ * not a second opinion: everywhere a texel could vary, a material is constant, and every expression
+ * below is the forward path's with a uniform standing in for a fetch.
+ *
+ * **What stays collapsed is the environment gain.** `flat/main.ts` scales what a metal reflects by
+ * `uEnvironmentGain`, which exists because a metal has no diffuse behind its reflection and a probe
+ * that under-reports the room leaves it with no other way to be lit. `PassEnvironment` carries no
+ * such control, so the gain is 1 and `mix(1, gain, metal)` is exactly 1 at every metalness — a
+ * collapse that is exact rather than approximate, which is the standard every term here is held to.
+ */
+
+/** A dielectric's normal-incidence reflectance, which is what a material with no metalness is. */
+export const DIELECTRIC_F0 = 0.04;
+
+/**
+ * A surface's normal-incidence reflectance, from its metalness.
+ *
+ * **A metal's Fresnel base is close to its albedo and a dielectric's is four per cent**, and
+ * `flat/main.ts` records what leaving it at 0.04 costs: a smooth metal seen head-on takes a four
+ * per cent reflection and reads as dark paint. The chromatic half of that — a metal's `f0` being
+ * its own colour rather than white — is in `lit.ts`, where the albedo is; this is the scalar the
+ * split sum takes.
+ */
+export function surfaceF0(metalness: number): number {
+  return DIELECTRIC_F0 + (1 - DIELECTRIC_F0) * metalness;
+}
+
+/**
+ * The split sum's second half, as a two-term fit: `dfg.x` scales `f0` and `dfg.y` is added on top.
+ *
+ * **Karis's analytic fit rather than the tabulated integral**, which is a texture this pipeline
+ * would otherwise have to carry and bind. Its published error is around one per cent of the
+ * tabulated term, far below what an eight-bit frame can show. **What would make it wrong** is a
+ * material model with a second lobe — a clearcoat or a sheen carries its own BRDF and its own
+ * integral, and this is Trowbridge-Reitz with Smith masking and nothing else.
+ */
+export function envBrdfApprox(ndv: number, roughness: number, out: Float32Array): Float32Array {
+  const c0 = [-1, -0.0275, -0.572, 0.022];
+  const c1 = [1, 0.0425, 1.04, -0.04];
+  const rx = roughness * (c0[0] as number) + (c1[0] as number);
+  const ry = roughness * (c0[1] as number) + (c1[1] as number);
+  const rz = roughness * (c0[2] as number) + (c1[2] as number);
+  const rw = roughness * (c0[3] as number) + (c1[3] as number);
+  const a004 = Math.min(rx * rx, Math.pow(2, -9.28 * ndv)) * rx + ry;
+  out[0] = -1.04 * a004 + rz;
+  out[1] = 1.04 * a004 + rw;
+  return out;
+}
+
+/**
+ * The same, with the light that bounces more than once inside the microsurface put back.
+ *
+ * **The split sum integrates a *single* scattering event**, so it silently discards every ray that
+ * strikes one microfacet, bounces, and leaves. Roughness scatters light; it does not absorb it, so
+ * a surface with `f0` 1 has to return everything at every roughness — and the bare sum returns
+ * about `1 - 0.55 * roughness`, which is a 44% loss at roughness 0.8.
+ *
+ * Fdez-Agüera's compensation: the missing energy, returned at the surface's average Fresnel over
+ * the hemisphere, summed as a geometric series over repeated bounces. **At `f0` 1 it comes back to
+ * exactly 1.0 at every roughness** — `average` is 1, `multi` is `energy / energy`, and the sum
+ * telescopes — which is the invariant the test beside this file asserts across the whole range.
+ *
+ * **No divide guard, because the denominator cannot reach zero.** `missing` is at most 0.55 and
+ * `average` at most 1, so `1 - missing * average` bottoms out at 0.45 — the worst case in both
+ * variables at once.
+ */
+export function envSpecularEnergy(f0: number, dfgX: number, dfgY: number): number {
+  const single = f0 * dfgX + dfgY;
+  const energy = dfgX + dfgY;
+  const missing = 1 - energy;
+  const average = f0 + (1 - f0) / 21;
+  const multi = (single * average) / (1 - missing * average);
+  return single + multi * missing;
+}
+
+/**
+ * How much of what the surface sees in the mirror direction reaches the frame.
+ *
+ * **Two expressions and a selector, because they answer different questions.** `prefiltered` is 1
+ * where the radiance came from a GGX-convolved chain, and there the split sum is the correct share
+ * of that integral — it carries the angular dependence itself, so it replaces the Fresnel sweep
+ * rather than multiplying it. Where the radiance is anything else, applying it would assert an
+ * integral that was never performed: `flat/main.ts` measured that mistake as the grazing-to-head-on
+ * ratio falling from about 15 to 1 down to 5 to 1, reported twice as a metal going opaque.
+ *
+ * So without a chain this is the engine's own long-standing weight — Schlick's Fresnel times
+ * `reflectivity * (1 - roughness)` — and with one it is the integral. The two are deliberately not
+ * blended into a single formula; a selector that is exactly 0 or exactly 1 is what makes a scene
+ * with no environment arithmetically identical to the frame it already rendered.
+ *
+ * `ndv` is `dot(n, toEye)` clamped at zero, as the caller's own facing term already computes.
+ */
+export function environmentWeight(
+  ndv: number,
+  roughness: number,
+  reflectivity: number,
+  prefiltered: number,
+  /**
+   * 0 is a dielectric and 1 is a metal. **Defaults to 0**, so every caller written before this
+   * argument existed gets the arithmetic it had.
+   */
+  metalness = 0,
+): number {
+  const f0 = surfaceF0(metalness);
+  const facing = 1 - ndv;
+  const fresnel = f0 + (1 - f0) * (facing * facing * facing * facing * facing);
+  /*
+   * **`max(reflectivity * (1 - roughness), metal)`, and both halves of that are repairs.**
+   *
+   * `reflectivity` is a per-material control, and it is zero for exactly the surfaces that carry
+   * their metalness some other way — `flat/main.ts` measured reading it alone as a chromed subject
+   * coming out near black with a baked probe sitting unread, because the whole block was skipped.
+   * So a metal reflects whether or not the material asked for reflections.
+   *
+   * And the `1 - roughness` thinning does not reach the metal. It stands for a polish that
+   * scatters a dielectric's reflection into no image at all; a metal has no diffuse to fall back
+   * on, so scaling it throws away 40% of everything a surface at roughness 0.4 shows and replaces
+   * it with a dark constant. It is also double counting — the level the sample comes from already
+   * *is* the roughness.
+   */
+  const amount = Math.max(reflectivity * (1 - roughness), metalness);
+  const sweep = Math.min(Math.max(fresnel * amount, 0), 1);
+
+  const dfg = new Float32Array(2);
+  envBrdfApprox(ndv, roughness, dfg);
+  const integrated = Math.min(
+    Math.max(
+      envSpecularEnergy(f0, dfg[0] as number, dfg[1] as number) * Math.max(reflectivity, metalness),
+      0,
+    ),
+    1,
+  );
+  return sweep + (integrated - sweep) * prefiltered;
+}

package/src/render/gpudriven/indirect.ts

@@ -0,0 +1,89 @@
+/**
+ * The arguments a culled frame hands the rasteriser, written by the device and read by it.
+ *
+ * **The whole pipeline exists so that the processor never learns how much there is to draw.** A
+ * cull dispatch writes the count into a buffer and the draw reads it from the same buffer; the
+ * frame is submitted before either number exists. So these are layouts rather than calls: what a
+ * block holds, in what order, and what a caller must have cleared before the dispatch runs.
+ *
+ * **One draw for the whole frame, not one per cluster.** Every surviving cluster is an *instance*
+ * of a fixed 128-triangle draw, which is what `VIS_MAX_TRIANGLES` is for: the index count is the
+ * same for all of them, so there is one block instead of thousands and no multi-draw extension is
+ * needed. A cluster with fewer triangles emits degenerate ones for the remainder — see
+ * `clusterVertexCluster` — and a degenerate triangle covers no pixel, so the picture is unchanged
+ * and the cost is the vertex stage running on indices that produce nothing.
+ *
+ * **What that costs, stated rather than hidden**: a scene whose clusters average 64 triangles runs
+ * the vertex stage twice for every triangle it draws. The alternative is a block per cluster and a
+ * loop of indirect draws on the processor, which is the draw-call bound this pipeline exists to
+ * remove. If a consumer's clusters are persistently half full, the fix is in the *baker* — see
+ * `assets/src/bake/cluster.ts`, whose target is the full 128.
+ */
+
+import { VIS_MAX_TRIANGLES } from './visbuffer.ts';
+
+/** Words in a `drawIndexedIndirect` block: index count, instances, first index, base vertex, first instance. */
+export const INDIRECT_DRAW_WORDS = 5;
+
+/** Words in a `dispatchWorkgroups` block: three group counts. */
+export const INDIRECT_DISPATCH_WORDS = 3;
+
+/** Indices a cluster draw always issues, whatever the cluster actually holds. */
+export const CLUSTER_INDEX_CAP = VIS_MAX_TRIANGLES * 3;
+
+/**
+ * The draw block for a frame that kept `clusters` of them.
+ *
+ * `firstInstance` is zero and the *instance index* is the slot in the kept list rather than the
+ * cluster identifier: the list is compacted, so slot and identifier differ, and the shader reads
+ * the identifier out of the list. Putting the identifier here instead would need a block per
+ * cluster, which is the thing this avoids.
+ */
+export function writeClusterDrawArgs(out: Uint32Array, at: number, clusters: number): void {
+  out[at] = CLUSTER_INDEX_CAP;
+  out[at + 1] = Math.max(0, clusters);
+  out[at + 2] = 0;
+  out[at + 3] = 0;
+  out[at + 4] = 0;
+}
+
+/**
+ * The dispatch block for `count` items at `groupSize` a group.
+ *
+ * **Rounded up, and zero items is zero groups rather than one.** A group that runs with nothing to
+ * do is harmless in this pipeline — every entry point range-checks its own invocation — but a
+ * dispatch of one group over an empty list still reads a buffer that a caller may not have bound,
+ * and "nothing to do" is the case a frame hits before anything has streamed in.
+ *
+ * **Zero falls out of the division rather than out of a special case**, and the special case that
+ * stood here is gone because a perturbation survived it: `ceil(0 / n)` is already 0, so the branch
+ * changed no answer and was a second statement of the rule to keep in step. The behaviour is still
+ * held by a test — what is gone is the code that was not doing the holding.
+ */
+export function writeDispatchArgs(
+  out: Uint32Array,
+  at: number,
+  count: number,
+  groupSize: number,
+): void {
+  const groups = Math.ceil(Math.max(0, count) / Math.max(1, groupSize));
+  out[at] = groups;
+  out[at + 1] = 1;
+  out[at + 2] = 1;
+}
+
+/**
+ * Which slot of the kept list a vertex belongs to, and which triangle of that cluster.
+ *
+ * The vertex stage's whole addressing, on the processor so a test can read it. `vertex` is
+ * `@builtin(vertex_index)` and runs to `CLUSTER_INDEX_CAP`; `instance` is
+ * `@builtin(instance_index)` and is the slot.
+ *
+ * **A triangle past the cluster's own count is reported rather than clamped.** Clamping draws the
+ * last triangle of the cluster over and over, which is a visible sliver on every cluster that is
+ * not exactly full; reporting it lets the shader emit a degenerate triangle, which covers nothing.
+ */
+export function clusterVertexCluster(vertex: number, instance: number, triangleCount: number) {
+  const triangle = Math.floor(vertex / 3);
+  return { slot: instance, triangle, corner: vertex % 3, degenerate: triangle >= triangleCount };
+}

package/src/render/gpudriven/instances.ts

@@ -0,0 +1,234 @@
+/**
+ * Whole meshes out of view, dropped before anything reads their clusters.
+ *
+ * **An instance here is a mesh**: every cluster names one through `meshOf`, and the raster and the
+ * shading both place it by `transforms[mesh]`. A mesh wholly outside the view has nothing to
+ * contribute to the frame, and before this every one of its clusters was still cut, tested against
+ * six planes and a cone, and occlusion-tested in phase two — correct, and the cost this stage
+ * removes.
+ *
+ * **The flag is read by the cut**, `LOD_CUT_WGSL`, because that is the one per-cluster stage with
+ * room for it: the cluster cull binds seven storage buffers and the compaction seven, of the eight a
+ * stage may bind by default, and the lookup needs two more (the flags and the cluster's mesh). A
+ * cluster the cut does not select is one the cluster cull then skips without testing and the
+ * compaction never lists — so a hidden mesh costs a lookup per cluster, and so does every cluster
+ * at a level the cut did not choose, which used to be tested for nothing.
+ *
+ * **The spheres are fitted once, at upload**, from the clusters' world spheres `clusterWorld.ts`
+ * already produced, for the reason that file gives: this pipeline's geometry does not move.
+ */
+import { CLUSTER_CULL_FLOATS } from './cullClusters.ts';
+import { sphereOutsideFrustum } from './frustum.ts';
+import { clusterSelected } from './lodCut.ts';
+
+/** Four floats a mesh: world centre and radius. `CULL_INSTANCES_WGSL` reads this stride. */
+export const INSTANCE_FLOATS = 4;
+
+/** What the instance cull writes for a mesh wholly outside the view. Zero is everything else. */
+export const INSTANCE_HIDDEN = 1;
+
+/** Four words a cluster in the uploaded meta: index offset, index count, identifier, mesh. */
+export const CLUSTER_META_WORDS = 4;
+const META_MESH = 3;
+
+/** Six floats a cluster in the cut's input, as `clusterWorld.ts` lays out `lod`. */
+const LOD_FLOATS = 6;
+
+/**
+ * Each mesh's world bounding sphere, from the world spheres of its clusters.
+ *
+ * **Held to the numbers the device reads.** The centre is the middle of the clusters' box, stored
+ * in single precision first; the radius is then measured from the *stored* centre and rounded up,
+ * never to nearest — a sphere rounded the wrong way is a few parts in ten million short of a
+ * cluster's far edge, and a cull that is not conservative is a hole in the picture.
+ *
+ * A mesh no cluster names is a point at the origin, which draws nothing whatever the cull says. A
+ * cluster naming a mesh past `meshCount` is refused: it would be bounded by nothing and drawn by a
+ * transform that does not exist.
+ */
+export function instanceBounds(
+  cull: Float32Array,
+  meshOf: Uint32Array,
+  count: number,
+  meshCount: number,
+): Float32Array {
+  const low = new Float64Array(meshCount * 3).fill(Infinity);
+  const high = new Float64Array(meshCount * 3).fill(-Infinity);
+  for (let c = 0; c < count; c += 1) {
+    const mesh = meshOf[c] as number;
+    if (!(mesh < meshCount)) {
+      throw new RangeError(
+        `instanceBounds: cluster ${String(c)} names mesh ${String(mesh)} and the scene has ${String(meshCount)} meshes`,
+      );
+    }
+    const at = c * CLUSTER_CULL_FLOATS;
+    const radius = cull[at + 3] as number;
+    for (let axis = 0; axis < 3; axis += 1) {
+      const centre = cull[at + axis] as number;
+      low[mesh * 3 + axis] = Math.min(low[mesh * 3 + axis] as number, centre - radius);
+      high[mesh * 3 + axis] = Math.max(high[mesh * 3 + axis] as number, centre + radius);
+    }
+  }
+
+  const out = new Float32Array(meshCount * INSTANCE_FLOATS);
+  for (let mesh = 0; mesh < meshCount; mesh += 1) {
+    if (!((low[mesh * 3] as number) <= (high[mesh * 3] as number))) continue;
+    for (let axis = 0; axis < 3; axis += 1) {
+      out[mesh * INSTANCE_FLOATS + axis] =
+        ((low[mesh * 3 + axis] as number) + (high[mesh * 3 + axis] as number)) / 2;
+    }
+  }
+
+  const reach = new Float64Array(meshCount);
+  for (let c = 0; c < count; c += 1) {
+    const mesh = meshOf[c] as number;
+    const at = c * CLUSTER_CULL_FLOATS;
+    const from = mesh * INSTANCE_FLOATS;
+    const distance = Math.hypot(
+      (cull[at] as number) - (out[from] as number),
+      (cull[at + 1] as number) - (out[from + 1] as number),
+      (cull[at + 2] as number) - (out[from + 2] as number),
+    );
+    reach[mesh] = Math.max(reach[mesh] as number, distance + (cull[at + 3] as number));
+  }
+  for (let mesh = 0; mesh < meshCount; mesh += 1) {
+    const wanted = reach[mesh] as number;
+    let radius = Math.fround(wanted);
+    /* Up, not to nearest: one step past the rounding is the smallest sphere that still holds. */
+    if (radius < wanted) radius = Math.fround(wanted * (1 + 2 ** -23));
+    out[mesh * INSTANCE_FLOATS + 3] = radius;
+  }
+  return out;
+}
+
+/**
+ * One mesh's bounding sphere, from a contiguous run of its clusters' world bounds.
+ *
+ * **A run rather than a `meshOf` scan, because a streamed mesh's clusters are contiguous by
+ * construction** — the allocator hands out a range — so the scan `instanceBounds` does is work a
+ * streaming caller has already done.
+ *
+ * **A mesh with no clusters gets a sphere of zero radius rather than an empty box's arithmetic.**
+ * `Infinity - (-Infinity)` is `-Infinity`, and every comparison against `NaN` is false, which
+ * reads as a mesh that is never culled rather than one that is never drawn.
+ *
+ * The two forms must agree, and `instances.test.ts` is what holds them to it.
+ */
+export function instanceSphereInto(
+  cull: Float32Array,
+  from: number,
+  count: number,
+  out: Float32Array,
+  at: number,
+): void {
+  const base = at * INSTANCE_FLOATS;
+  if (count <= 0) {
+    out[base] = 0;
+    out[base + 1] = 0;
+    out[base + 2] = 0;
+    out[base + 3] = 0;
+    return;
+  }
+
+  const low = [Infinity, Infinity, Infinity];
+  const high = [-Infinity, -Infinity, -Infinity];
+  for (let c = from; c < from + count; c += 1) {
+    const record = c * CLUSTER_CULL_FLOATS;
+    const radius = cull[record + 3] as number;
+    for (let axis = 0; axis < 3; axis += 1) {
+      const centre = cull[record + axis] as number;
+      low[axis] = Math.min(low[axis] as number, centre - radius);
+      high[axis] = Math.max(high[axis] as number, centre + radius);
+    }
+  }
+  for (let axis = 0; axis < 3; axis += 1) {
+    out[base + axis] = ((low[axis] as number) + (high[axis] as number)) / 2;
+  }
+
+  /* The reach from that centre, which is what makes the sphere hold every cluster rather than
+     every corner of the box — the same second pass `instanceBounds` makes, for the same reason. */
+  let reach = 0;
+  for (let c = from; c < from + count; c += 1) {
+    const record = c * CLUSTER_CULL_FLOATS;
+    const distance = Math.hypot(
+      (cull[record] as number) - (out[base] as number),
+      (cull[record + 1] as number) - (out[base + 1] as number),
+      (cull[record + 2] as number) - (out[base + 2] as number),
+    );
+    reach = Math.max(reach, distance + (cull[record + 3] as number));
+  }
+  let radius = Math.fround(reach);
+  /* Up, not to nearest: one step past the rounding is the smallest sphere that still holds. */
+  if (radius < reach) radius = Math.fround(reach * (1 + 2 ** -23));
+  out[base + 3] = radius;
+}
+
+/**
+ * One flag a mesh: `INSTANCE_HIDDEN` where its sphere is wholly outside the view. Returns how many
+ * are. Mirrors `CULL_INSTANCES_WGSL`, which `gpu-parity.mjs` holds to `sphereOutsideFrustum`.
+ */
+export function cullInstances(
+  planes: Float32Array,
+  spheres: Float32Array,
+  count: number,
+  out: Uint32Array,
+): number {
+  let hidden = 0;
+  for (let i = 0; i < count; i += 1) {
+    const at = i * INSTANCE_FLOATS;
+    const outside = sphereOutsideFrustum(
+      planes,
+      spheres[at] as number,
+      spheres[at + 1] as number,
+      spheres[at + 2] as number,
+      spheres[at + 3] as number,
+    );
+    out[i] = outside ? INSTANCE_HIDDEN : 0;
+    if (outside) hidden += 1;
+  }
+  return hidden;
+}
+
+/**
+ * The cut, over every cluster, with the instance flags applied first: one flag a cluster, and how
+ * many were selected. Mirrors `LOD_CUT_WGSL`.
+ */
+export function selectClusters(
+  lod: Float32Array,
+  meta: Uint32Array,
+  hidden: Uint32Array,
+  screenHeight: number,
+  fovY: number,
+  thresholdPixels: number,
+  eyeX: number,
+  eyeY: number,
+  eyeZ: number,
+  out: Uint32Array,
+): number {
+  const count = Math.floor(lod.length / LOD_FLOATS);
+  let chosen = 0;
+  for (let i = 0; i < count; i += 1) {
+    const mesh = meta[i * CLUSTER_META_WORDS + META_MESH] as number;
+    if ((hidden[mesh] ?? 0) !== 0) {
+      out[i] = 0;
+      continue;
+    }
+    const at = i * LOD_FLOATS;
+    const selected = clusterSelected(
+      lod[at + 4] as number,
+      lod[at + 5] as number,
+      Math.hypot(
+        (lod[at] as number) - eyeX,
+        (lod[at + 1] as number) - eyeY,
+        (lod[at + 2] as number) - eyeZ,
+      ),
+      lod[at + 3] as number,
+      screenHeight,
+      fovY,
+      thresholdPixels,
+    );
+    out[i] = selected ? 1 : 0;
+    if (selected) chosen += 1;
+  }
+  return chosen;
+}