@driftengine/core 3.61.0

package/src/render/frame/replay.ts

@@ -0,0 +1,50 @@
+import type { ScheduledPass } from './schedule.ts';
+
+/**
+ * The nodes a schedule kept, in the order they are to be replayed.
+ *
+ * **Separate from the executor because it is the part with an answer to check.** A pass the
+ * scheduler dropped writes something nothing reads, and replaying its nodes anyway is what made
+ * every capture in the verb migration unable to fail — but no real frame drops a pass today, so
+ * the behaviour has nowhere to be observed from inside a renderer test. Here it has.
+ *
+ * Order inside a pass is the caller's order and is never changed, for the reason `schedule`
+ * gives: blending and depth make *after* different from *before*.
+ *
+ * Allocates nothing. `out` is the caller's, sized with the arena, and the return value says how
+ * many of its entries were filled.
+ */
+export function keptNodes(passes: ScheduledPass[], count: number, out: Int32Array): number {
+  let at = 0;
+  for (let i = 0; i < count; i += 1) {
+    const pass = passes[i];
+    if (pass === undefined) break;
+    const end = pass.first + pass.count;
+    for (let node = pass.first; node < end && at < out.length; node += 1) {
+      out[at] = node;
+      at += 1;
+    }
+  }
+  return at;
+}
+
+/**
+ * A scratch array big enough for `needed` nodes, reusing the one given where it already fits.
+ *
+ * **`keptNodes` says the caller's array is "sized with the arena", and this is what makes that
+ * true.** It was not: the renderer sized its scratch with `MAX_DRAWS_PER_FRAME` while the arena
+ * it reads reallocates at twice its capacity whenever a frame outgrows it. `keptNodes` then
+ * stopped at `out.length` and the tail of the frame's passes was never replayed — no warning, no
+ * error, and a plausible picture missing whatever those passes drew.
+ *
+ * It was reachable with the draw ring nowhere near full, because a node is recorded per **verb**
+ * rather than per draw: overlays, scatter, plumes and text each record one.
+ *
+ * **What it costs** is a single allocation on the frame that first outgrows the scratch and none
+ * afterwards, because the caller keeps what comes back. **What would make it wrong** is a caller
+ * that discards the result and calls this again per frame, which is an allocation in a hot path;
+ * the arena's own doubling is what keeps the growth finite rather than per-frame.
+ */
+export function scratchFor(scratch: Int32Array, needed: number): Int32Array {
+  return scratch.length >= needed ? scratch : new Int32Array(needed);
+}

package/src/render/frame/resources.ts

@@ -0,0 +1,61 @@
+/**
+ * Every attachment a frame can read or write, as a fixed table.
+ *
+ * Fixed rather than allocated, because this frame's composition is fixed: the same shadow
+ * cascades, the same scene target, the same bloom chain, every frame. The transient allocator
+ * and resource aliasing a frame graph is famous for would be machinery with no case here to
+ * serve.
+ *
+ * A mask is a `number` and not a bitset object. Thirty-one bits is more than the table needs,
+ * a number compares and combines in one instruction, and the scheduler does this per node.
+ */
+export const FRAME_RESOURCES = [
+  'sceneColor',
+  'sceneDepth',
+  'canvas',
+  'cascade0',
+  'cascade1',
+  'cascade2',
+  /*
+   * The twelve point-shadow cubes are one bit, not twelve. They are baked together and
+   * sampled together, and nothing in the frame reads one without the others, so twelve bits
+   * would be twelve ways to express one fact — and twelve chances for a node to declare a
+   * subset that does not correspond to anything the renderer can actually do.
+   */
+  'pointShadows',
+  'probeCube',
+  'mirrorColor',
+  'mirrorDepth',
+  'bloomChain',
+  'aoTarget',
+  'depthSnapshot',
+  'inset',
+] as const;
+
+export type FrameResource = (typeof FRAME_RESOURCES)[number];
+
+export const RESOURCE_COUNT = FRAME_RESOURCES.length;
+
+const BITS = new Map<string, number>(FRAME_RESOURCES.map((name, i) => [name, 1 << i]));
+
+/** The single bit that stands for one resource. */
+export function resourceBit(name: FrameResource): number {
+  return BITS.get(name) ?? 0;
+}
+
+/** A mask of the named resources, for declaring what a node reads or writes. */
+export function maskOf(...names: FrameResource[]): number {
+  let mask = 0;
+  for (const name of names) mask |= resourceBit(name);
+  return mask;
+}
+
+/**
+ * The resources a mask names.
+ *
+ * For diagnostics and tests rather than for the frame: it allocates an array, so nothing on
+ * the per-frame path may call it.
+ */
+export function namesIn(mask: number): FrameResource[] {
+  return FRAME_RESOURCES.filter((_, i) => (mask & (1 << i)) !== 0);
+}

package/src/render/frame/schedule.ts

@@ -0,0 +1,85 @@
+import type { Arena } from './arena.ts';
+import { nodeCount, nodeReads, nodeWrites } from './arena.ts';
+
+/**
+ * One render pass: a contiguous run of nodes sharing a write-set, and what happens to the
+ * attachments at each end of it.
+ */
+export interface ScheduledPass {
+  /** The resources this pass writes. */
+  writes: number;
+  /** Index of the first node in the run. */
+  first: number;
+  /** How many nodes the run holds. */
+  count: number;
+  /** Resources this pass clears rather than loads. */
+  clear: number;
+  /** Resources safe to discard at the end, because nothing later in the frame reads them. */
+  discard: number;
+}
+
+/**
+ * Group a frame's nodes into passes, and derive what happens to each attachment.
+ *
+ * **The order is the caller's and is never changed.** Blending and depth make *after*
+ * different from *before*, so an immediate-mode API's draw order carries meaning no
+ * dependency analysis may override. All this does is group adjacent compatible nodes and work
+ * out load and store from the reads that follow.
+ *
+ * **`liveOut` is what must survive this schedule**, and it is a parameter rather than a
+ * constant because the scheduler does not necessarily see the whole frame. During the
+ * migration a flush schedules only what has accumulated, so a resource written here may be
+ * read after the next flush — invisible from inside this call. The caller knows what is still
+ * live; this cannot work it out. The canvas belongs in it always, because nothing ever reads
+ * the canvas (it is presented, not sampled) and a purely read-driven rule would conclude it
+ * is safe to throw away.
+ *
+ * Allocates nothing: `out` is supplied by the caller and reused across frames, and the return
+ * value says how many of its entries were filled.
+ */
+export function schedule(
+  arena: Arena,
+  clearMask: number,
+  liveOut: number,
+  out: ScheduledPass[],
+): number {
+  const total = nodeCount(arena);
+  if (total === 0) return 0;
+
+  let passes = 0;
+  let at = 0;
+  let cleared = 0;
+
+  while (at < total) {
+    const writes = nodeWrites(arena, at);
+    let end = at + 1;
+    while (end < total && nodeWrites(arena, end) === writes) end += 1;
+
+    /*
+     * Everything read between the end of this pass and the end of the frame. A resource in
+     * this set has to survive; one outside it does not, and that is the whole derivation.
+     *
+     * Recomputed per pass rather than kept as a suffix scan. This runs over tens of passes
+     * and hundreds of nodes, where the simple version is free and obviously correct. If a
+     * profile ever says otherwise, replace it with a suffix-OR computed once — and put the
+     * measurement in the commit, because this is the calculation the discard rests on.
+     */
+    let readLater = 0;
+    for (let i = end; i < total; i += 1) readLater |= nodeReads(arena, i);
+
+    const unread = (writes & readLater) === 0 && (writes & liveOut) === 0;
+    if (!unread) {
+      const pass = out[passes];
+      if (pass === undefined) return passes;
+      pass.writes = writes;
+      pass.first = at;
+      pass.count = end - at;
+      pass.clear = clearMask & writes & ~cleared;
+      pass.discard = writes & ~readLater & ~liveOut;
+      cleared |= writes;
+      passes += 1;
+    }
+    at = end;
+  }
+  return passes;
+}

package/src/render/frameView.ts

@@ -0,0 +1,20 @@
+import type { Camera } from './camera.ts';
+
+/**
+ * What a drawing path needs from the camera, which is not the camera.
+ *
+ * **The seam reversed depth was waiting on.** WebGPU corrects a projection once a frame, in one
+ * place, at the last moment before drawing. WebGL2 had no such place: the camera's raw matrix was
+ * read directly by the main renderer and by the plume, water, caustics, wind-streak and flock
+ * renderers, each uploading it itself — so reversing depth meant remapping six call sites across
+ * five files and then finding a seventh, which is how three attempts at it went.
+ *
+ * Narrowing the parameter to the three fields those paths actually read is what lets the frame hand
+ * them a *corrected* matrix instead of the camera's own. A real `Camera` satisfies it structurally,
+ * so no caller outside changed, and the correction now lives in one place on this backend too.
+ *
+ * **Derived from `Camera` rather than restated.** Written out by hand, the day a field changes type
+ * this drifts and the mismatch shows up as geometry in the wrong place; picked off the class, it
+ * cannot.
+ */
+export type FrameView = Pick<Camera, 'position' | 'view' | 'viewProjection'>;