@driftengine/core 3.63.0 → 4.1.0

package/dist/render/backend/webgpu/linePass.d.ts

@@ -1,4 +1,3 @@
-import type { LineSegments } from '../../linePoints.ts';
 import type { UniformFields } from './scatterPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 /**
@@ -11,10 +10,10 @@ import type { PipelineCache } from './pipelineCache.ts';
  * the extra `uModel` field `LINE_VERT` carries and `BOLT_VERT` does not.
  *
  * The per-frame streams are two positions, not bolt's five — no `along`/`fade`/`seed`/
- * `brightness` to carry, because a line has no envelope. `expandLineSegments` is written here
- * rather than folded into `expandBoltSegments` in `segmentQuads.ts`, for the reason
- * `lineBatch.ts` gives on the WebGL2 side: teaching that function a `LineSegments` shape too
- * would grow a union coupling two renderers that share only a quad.
+ * `brightness` to carry, because a line has no envelope. `expandLineSegments` is its own function
+ * beside `expandBoltSegments` in `segmentQuads.ts` rather than folded into it — teaching that one a
+ * `LineSegments` shape too would grow a union coupling two renderers that share only a quad — and
+ * both backends call it, so the count a batch draws is decided once.
  *
  * **Uniforms are a `UniformRing`, one slot a draw, not a single block like `boltPass.ts`'s.**
  * A bolt pool is drawn once a frame in every scene that has shipped so far, so a single block
@@ -44,15 +43,6 @@ export interface GpuLines {
     dispose(): void;
 }
 export declare function createGpuLines(device: GPUDevice, capacity: number, label: string): GpuLines;
-/**
- * Expand this frame's segments to their four vertices each, into arrays the caller owns.
- *
- * Returns how many segments were written, which is the list's count clamped to the batch's
- * capacity — a caller that overruns loses its tail rather than its frame, the same rule
- * `expandBoltSegments` follows. Reads only `LineSegments.from`/`.to`, the same walk `lineBatch.ts`
- * writes inline in `upload()` on the WebGL2 side.
- */
-export declare function expandLineSegments(data: LineSegments, capacity: number, from: Float32Array, to: Float32Array): number;
 /** `aFrom`, `aTo`, `aCorner` — one buffer each, at the locations `line.ts` declares. No fourth
  * dynamic attribute: unlike a bolt, a line carries no envelope. */
 export declare function lineVertexLayouts(): GPUVertexBufferLayout[];

package/dist/render/backend/webgpu/linePass.js

@@ -13,10 +13,10 @@ import { shaderModule } from './shaderModules.js';
  * the extra `uModel` field `LINE_VERT` carries and `BOLT_VERT` does not.
  *
  * The per-frame streams are two positions, not bolt's five — no `along`/`fade`/`seed`/
- * `brightness` to carry, because a line has no envelope. `expandLineSegments` is written here
- * rather than folded into `expandBoltSegments` in `segmentQuads.ts`, for the reason
- * `lineBatch.ts` gives on the WebGL2 side: teaching that function a `LineSegments` shape too
- * would grow a union coupling two renderers that share only a quad.
+ * `brightness` to carry, because a line has no envelope. `expandLineSegments` is its own function
+ * beside `expandBoltSegments` in `segmentQuads.ts` rather than folded into it — teaching that one a
+ * `LineSegments` shape too would grow a union coupling two renderers that share only a quad — and
+ * both backends call it, so the count a batch draws is decided once.
  *
  * **Uniforms are a `UniformRing`, one slot a draw, not a single block like `boltPass.ts`'s.**
  * A bolt pool is drawn once a frame in every scene that has shipped so far, so a single block
@@ -77,35 +77,6 @@ export function createGpuLines(device, capacity, label) {
         },
     };
 }
-/**
- * Expand this frame's segments to their four vertices each, into arrays the caller owns.
- *
- * Returns how many segments were written, which is the list's count clamped to the batch's
- * capacity — a caller that overruns loses its tail rather than its frame, the same rule
- * `expandBoltSegments` follows. Reads only `LineSegments.from`/`.to`, the same walk `lineBatch.ts`
- * writes inline in `upload()` on the WebGL2 side.
- */
-export function expandLineSegments(data, capacity, from, to) {
-    const count = Math.min(data.count, capacity);
-    for (let s = 0; s < count; s++) {
-        const fx = data.from[s * 3];
-        const fy = data.from[s * 3 + 1];
-        const fz = data.from[s * 3 + 2];
-        const tx = data.to[s * 3];
-        const ty = data.to[s * 3 + 1];
-        const tz = data.to[s * 3 + 2];
-        for (let c = 0; c < 4; c++) {
-            const v = s * 4 + c;
-            from[v * 3] = fx;
-            from[v * 3 + 1] = fy;
-            from[v * 3 + 2] = fz;
-            to[v * 3] = tx;
-            to[v * 3 + 1] = ty;
-            to[v * 3 + 2] = tz;
-        }
-    }
-    return count;
-}
 /** `aFrom`, `aTo`, `aCorner` — one buffer each, at the locations `line.ts` declares. No fourth
  * dynamic attribute: unlike a bolt, a line carries no envelope. */
 export function lineVertexLayouts() {

package/dist/render/backend/webgpu/probeBake.d.ts

@@ -0,0 +1,148 @@
+/**
+ * A few probes a frame, traced down the GI chain and convolved into the grid the shading samples.
+ *
+ * **The light arrives through `gridIrradiance` and nowhere else**, which is Wave 4A's own
+ * constraint: a second per-pixel irradiance buffer beside the one the shading already mixes into
+ * its ambient is a design failure rather than an optimisation. So this writes the *irradiance level
+ * of the existing probe array* — the same texels a rasterised bake would have written — and the lit
+ * pass changes not at all.
+ *
+ * **Three steps on one encoder, in order.** A compute dispatch traces `PROBE_DIRECTIONS` rays for
+ * each scheduled probe; a second convolves those rays into an octahedral map; a render pass a layer
+ * carries the map into the array. They are separate because the convolution reads every ray of its
+ * probe, so tracing per texel would cast the same rays `edge²` times.
+ *
+ * **The array is sampled by the first step and written by the third, and that is legal.** WebGPU
+ * forbids a texture being read and written inside one pass, not across passes on one encoder. What
+ * it costs is a frame of latency in the bounce, which a probe volume has anyway because it
+ * accumulates — and the accumulation is what makes the solution multi-bounce.
+ *
+ * **The grid does not have to be seeded, and two wrong diagnoses said it did.** A traced probe
+ * gathers radiance from the field it hits and reads what that surface is worth *from the probes* —
+ * the maintainer's answer of 2026-09-17, and what makes the solution converge on several bounces.
+ * Since Task 8 it also evaluates the *sun* at the hit, so it introduces light of its own and a grid
+ * starting at black climbs away from black. It is not a fixed point.
+ *
+ * It looked like one twice. `demo/dev/bounce.html` with no rasterised capture came back at a
+ * uniform 209 of 255, first read as "converges on whatever it started with" and then as undefined
+ * memory in the probe array. It was neither: `flatTextures` resolves `uEnvironment` to a one-texel
+ * **white** stand-in while `probeBaked` is false, and a flat bind group holds whatever texture
+ * existed when it was built — so a renderer whose grid is filled by tracing kept that white for
+ * ever, and 209 is 0.82 (the room's albedo) times 255. `markProbeFilled` rebuilds the groups when
+ * the last layer lands, and the room now measures the same with the capture and without it.
+ *
+ * So `bakeProbeGrid` is an optional head start rather than a requirement, and **the wave's
+ * criterion of "no baked lighting" is met literally**: `scripts/bounce-check.mjs` runs the page
+ * with `?seed=0` and asserts it.
+ *
+ * **A layer nothing has ever rasterised gets its whole chain written once**, because the roughness
+ * levels of an unseeded array hold undefined contents and a reflective surface sampling those is
+ * worse than one sampling a flat colour. A seeded layer keeps the chain it was given and only its
+ * irradiance level is rewritten, which is the level the diffuse term reads.
+ */
+import type { ProbeGrid } from '../../probeGrid.ts';
+import type { PassDistanceField } from '../../pass.ts';
+/**
+ * How many probes are refreshed a frame.
+ *
+ * **Five, and the number is a cost rather than a quality.** Each is `PROBE_DIRECTIONS` marches down
+ * a three-level chain, and what makes a probe converge is the direction set turning between
+ * refreshes rather than any single refresh being final. A 64-probe grid comes all the way round in
+ * thirteen frames, which at sixty a second is a fifth of a second for a light that moved.
+ */
+export declare const PROBES_PER_FRAME = 5;
+export interface ProbeBakeTargets {
+    /** The array the shading samples, whose irradiance level this writes. */
+    readonly array: GPUTexture;
+    /** A view of the whole array, for the dispatches that read what the last frame left. */
+    readonly view: GPUTextureView;
+    readonly sampler: GPUSampler;
+    /** Texels across level 0, gutter included. */
+    readonly edge: number;
+    readonly format: GPUTextureFormat;
+}
+export declare class ProbeBaker {
+    private readonly device;
+    private readonly targets;
+    /** Which mip holds the cosine convolution, and how many texels across it is. */
+    private readonly level;
+    private readonly levelEdge;
+    private readonly texels;
+    private readonly tracePipeline;
+    private readonly convolvePipeline;
+    private readonly blitPipeline;
+    private readonly computeLayout;
+    private readonly marchBuffer;
+    private readonly bakeBuffer;
+    private readonly volumeBuffer;
+    private readonly scheduleBuffer;
+    private readonly rayBuffer;
+    private readonly irradianceBuffer;
+    private readonly blitParams;
+    private readonly blitGroup;
+    /** Rebuilt only when the field it was built against is a different object. */
+    private computeGroup;
+    private boundTo;
+    private readonly marchScratch;
+    private readonly marchInts;
+    private readonly bakeScratch;
+    private readonly volumeScratch;
+    private readonly scheduleScratch;
+    private readonly scheduleUpload;
+    /** One view a layer a level, built when the grid changes rather than in the frame loop. */
+    private views;
+    /** Which layers have had their whole chain written, so the first fill happens once. */
+    private filled;
+    private layers;
+    private frameIndex;
+    /**
+     * The device's own clock around the two dispatches, where it has one.
+     *
+     * **Beside the work it measures, exactly as `FieldComposer`'s is.** Without it the only figure
+     * indirect light could publish was the *composition's*, and the trace — which is the half the
+     * feature is named for — had no cost anyone could quote. The blits are outside the pair
+     * deliberately: they are render passes an encoder interleaves with the frame's own, and a span
+     * that covered them would be measuring the frame rather than the bake.
+     */
+    private readonly queries;
+    private readonly queryResolve;
+    private readonly queryRead;
+    private queryCopied;
+    private queryMapping;
+    private timed;
+    private bakeMsValue;
+    constructor(device: GPUDevice, targets: ProbeBakeTargets);
+    /**
+     * The device milliseconds the last measured bake took, or null where nothing measured it.
+     *
+     * One frame behind, because a timestamp is read back and a readback that blocked would be the
+     * measurement changing what it measures. It covers one refresh — `PROBES_PER_FRAME` probes —
+     * rather than a whole grid, which is what a frame actually pays.
+     */
+    get bakeMs(): number | null;
+    /** Ask for the last frame's figure, once the frame that recorded it has been submitted. */
+    readTimings(): void;
+    private blitOffset;
+    private uniform;
+    private storage;
+    /**
+     * Build the per-layer views a grid needs, and forget which layers were filled.
+     *
+     * Called when the grid changes rather than every frame: a view is cheap and sixty-four of them
+     * are not, and the frame path is the one place this project does not allocate.
+     */
+    setGrid(layers: number): void;
+    /** Whether every layer has had its chain written, which is what makes the array safe to sample. */
+    get complete(): boolean;
+    /**
+     * Refresh this frame's share of the grid.
+     *
+     * Returns how many probes were baked, which is zero when there is nothing to trace against.
+     */
+    bake(encoder: GPUCommandEncoder, field: PassDistanceField, grid: ProbeGrid, seeded: boolean, sun: {
+        readonly direction: ArrayLike<number>;
+        readonly colour: ArrayLike<number>;
+        readonly sky: ArrayLike<number>;
+    }): number;
+    dispose(): void;
+}