@driftengine/core 3.62.0 → 4.0.0

package/dist/render/gpudriven/materialBin.js

@@ -0,0 +1,108 @@
+/**
+ * Grouping the frame's pixels by the material that has to shade them.
+ *
+ * **A visibility buffer defers the shading and does not organise it.** Neighbouring pixels can
+ * hold triangles from different meshes with different materials, so shading it in place means
+ * every invocation branching on a material it cannot know until it has read the buffer — which on
+ * a wide machine is every lane in a group taking every branch. Binning first turns that into one
+ * dispatch per material, each of which shades pixels that all want the same code.
+ *
+ * **A material with no pixels gets a zero-length bin and a zero-workgroup dispatch, never an
+ * absent one.** The arguments are indexed by material identifier, so dropping an empty one shifts
+ * every later material's block and the scene shades with the wrong code — a picture that is
+ * plausible, entirely wrong, and correlates with nothing a consumer changed. `binsPresent` is the
+ * separate question of how many materials actually appear, which is a number to report rather
+ * than a length to index by.
+ *
+ * **Offsets are a prefix sum and the cursors are a copy of it.** The scatter needs somewhere to
+ * count from that is not the offsets themselves, or the second pixel of a bin overwrites the
+ * first's offset and every later bin starts in the wrong place.
+ */
+import { INDIRECT_DISPATCH_WORDS, writeDispatchArgs } from './indirect.js';
+import { VIS_TRIANGLE_BITS, visibilityCovered } from './visbuffer.js';
+/** Invocations a shading group covers. One pixel each; the bins are lists, not rectangles. */
+export const BIN_GROUP_SIZE = 64;
+/** Words in one material's dispatch block, so a caller can size the buffer. */
+export const BIN_DISPATCH_WORDS = INDIRECT_DISPATCH_WORDS;
+/**
+ * Which material a pixel wants, or -1 where nothing covered it.
+ *
+ * **The sentinel test survives perturbation and is kept**, which is worth the sentence because it
+ * looks like the load-bearing line and is not. `VIS_EMPTY` is `0xffffffff`, so its cluster field
+ * reads as 33,554,431 — and the range test one line down refuses any cluster past the table, which
+ * every real table is far smaller than. Deleting either check alone therefore changes no answer
+ * this repository can produce. What the sentinel test decides is a table sized to the full
+ * twenty-five bits, which is 134 MB and nothing allocates; what the range test decides is a
+ * visibility buffer left over from a frame with more geometry in it, which is a real case and is
+ * the one `gpu-parity.mjs` generates. Both are kept because they answer different questions and
+ * one of them is cheap insurance against the other's assumption.
+ */
+export function materialAt(visibility, materialOf, pixel) {
+    const packed = visibility[pixel];
+    if (!visibilityCovered(packed))
+        return -1;
+    const cluster = packed >>> VIS_TRIANGLE_BITS;
+    const material = materialOf[cluster];
+    return material === undefined ? -1 : material;
+}
+/**
+ * How many pixels each material owns, and how many pixels were covered at all.
+ *
+ * `counts` is cleared here rather than by the caller, because a count buffer reused across frames
+ * without clearing grows without bound and the bins then run off the end of the pixel list —
+ * which appears as the shading reading a neighbouring bin's pixels.
+ */
+export function countBins(visibility, materialOf, counts) {
+    counts.fill(0);
+    let covered = 0;
+    for (let pixel = 0; pixel < visibility.length; pixel += 1) {
+        const material = materialAt(visibility, materialOf, pixel);
+        if (material < 0 || material >= counts.length)
+            continue;
+        counts[material] = counts[material] + 1;
+        covered += 1;
+    }
+    return covered;
+}
+/** Where each material's pixels begin: the exclusive prefix sum of the counts. */
+export function binOffsets(counts, offsets) {
+    let running = 0;
+    for (let material = 0; material < counts.length; material += 1) {
+        offsets[material] = running;
+        running += counts[material];
+    }
+    return running;
+}
+/**
+ * Write every covered pixel's index into its material's slice of `pixels`.
+ *
+ * `cursors` starts as a copy of `offsets` and is advanced as the scatter runs, so `offsets` stays
+ * readable afterwards — which the shading dispatch needs, because it is what tells a group where
+ * its material's list starts.
+ */
+export function fillBins(visibility, materialOf, offsets, cursors, pixels) {
+    cursors.set(offsets);
+    for (let pixel = 0; pixel < visibility.length; pixel += 1) {
+        const material = materialAt(visibility, materialOf, pixel);
+        if (material < 0 || material >= offsets.length)
+            continue;
+        const at = cursors[material];
+        pixels[at] = pixel;
+        cursors[material] = at + 1;
+    }
+}
+/** One dispatch block per **declared** material, zero groups where the bin is empty. */
+export function binDispatchArgs(counts, out, groupSize = BIN_GROUP_SIZE) {
+    for (let material = 0; material < counts.length; material += 1) {
+        writeDispatchArgs(out, material * BIN_DISPATCH_WORDS, counts[material], groupSize);
+    }
+}
+/** How many materials the frame actually contains, which is not how many it declares. */
+export function binsPresent(counts) {
+    let present = 0;
+    for (let material = 0; material < counts.length; material += 1) {
+        if (counts[material] > 0)
+            present += 1;
+    }
+    return present;
+}

package/dist/render/gpudriven/materialTable.d.ts

@@ -0,0 +1,88 @@
+/** A GPU-driven material as the shading pass reads it: five blocks, one of them integers. */
+import type { GpuDrivenMaterial } from '../backend/webgpu/gpuDrivenPass.ts';
+import type { GpuDrivenProgram } from './decodeTables.ts';
+/**
+ * **The forward path's maps, as decode programs.** `SurfaceMaterial` binds an albedo, a normal and
+ * an occlusion-roughness-metallic image, and its scales and strengths mean what they mean there —
+ * the ORM map *replaces* roughness and the scale gives the scaling back, and occlusion strength is
+ * a mix from one rather than a multiply. Defaults are `SurfaceMaterial`'s.
+ */
+export interface GpuDrivenTextures {
+    readonly baseColour?: GpuDrivenProgram;
+    readonly normal?: GpuDrivenProgram;
+    /** Occlusion in R, roughness in G, metallic in B — glTF's packing, as `SurfaceMaterial.orm`. */
+    readonly orm?: GpuDrivenProgram;
+    /**
+     * Where the surface glows, in colour, as `SurfaceMaterial.emissive`'s map: the glow is the albedo
+     * times this times the material's `emissive`, so a black texel glows nowhere and the scalar
+     * still says how brightly the rest does. **glTF's rule and flat/main.ts's**, which the facade of
+     * a city at dusk needed — lit windows in a wall that does not glow — and the pipeline could not
+     * say until 2026-09-18.
+     */
+    readonly emissive?: GpuDrivenProgram;
+    readonly uScale?: number;
+    readonly vScale?: number;
+    /** Defaults to 1 when a `normal` program is given and 0 when it is not. */
+    readonly normalStrength?: number;
+    readonly roughnessScale?: number;
+    readonly metallicScale?: number;
+    readonly occlusionStrength?: number;
+}
+/**
+ * Words a material entry: tint and emissive, the surface scalars, four program indices, the UV
+ * scale and two strengths, the two ORM scales with the cutout and blend flags, and
+ * the opacity with three spare.
+ *
+ * **It was eight until 2026-09-17**, and metalness took its last spare lane the same day, so the
+ * programs and the scales needed three more blocks rather than squeezing into what was left. It
+ * became twenty-four on 2026-09-18, when transparency arrived and there was nowhere left to put an
+ * opacity: the cutout took lane 18 and the blend flag took 19, and lane 11 is a reserved program
+ * slot rather than a gap. A sixteen-byte block is 1 kB across the whole table, against the 64 kB a
+ * uniform buffer may hold.
+ */
+export declare const GPU_DRIVEN_MATERIAL_FLOATS = 24;
+/**
+ * Below this base-colour alpha the raster discards a fragment. Zero means no test.
+ *
+ * **Lane 18 rather than lane 11**, which looks spare and is not: the loop below initialises lanes
+ * 8 to 11 to `DECODE_NO_PROGRAM`, so eleven is a fourth program slot somebody reserved rather than
+ * a gap, and a scalar written there would be read back as a program index. Taking 18 leaves the
+ * reservation alone and leaves 19 after it.
+ */
+export declare const MATERIAL_ALPHA_CUTOFF = 18;
+/**
+ * Non-zero where this material's clusters are drawn blended rather than into the visibility buffer.
+ *
+ * **The last spare lane of twenty**, and a flag rather than an opacity because the opacity is the
+ * tint's fourth component. What this selects is which of the two halves of the frame a cluster
+ * belongs to, which the cut asks once per cluster.
+ */
+export declare const MATERIAL_BLEND = 19;
+/**
+ * How much of a blended surface is its own colour rather than what is behind it. One is opaque.
+ *
+ * **It is not the tint's fourth component**, which is the emissive gain and has been since the
+ * table was eight floats, and it is not `alphaCutoff`, which decides whether a fragment exists at
+ * all. A material that does not blend never reads this.
+ */
+export declare const MATERIAL_OPACITY = 20;
+/**
+ * Where a material's emissive program is: the fourth program lane, which the table reserved and
+ * initialised to none before anything used it.
+ */
+export declare const MATERIAL_EMISSIVE_PROGRAM = 11;
+export interface MaterialPrograms {
+    readonly programs: readonly GpuDrivenProgram[];
+    /** Four a material — base colour, normal, ORM, emissive — each an index into `programs` or none. */
+    readonly indices: Uint32Array;
+}
+/** Every program the materials name, once each by identity, and where each material's are. */
+export declare function collectPrograms(materials: readonly GpuDrivenMaterial[]): MaterialPrograms;
+/**
+ * The table, `slots` entries long.
+ *
+ * **Written through a `DataView` because one block is integers.** A program index written as a
+ * float would be read by `vec4<u32>` as the float's bits, which names a program four billion
+ * places away and draws nothing — or, clamped, the last program in the table.
+ */
+export declare function writeMaterialTable(materials: readonly GpuDrivenMaterial[], indices: Uint32Array, slots: number): ArrayBuffer;

package/dist/render/gpudriven/materialTable.js

@@ -0,0 +1,115 @@
+/** A GPU-driven material as the shading pass reads it: five blocks, one of them integers. */
+import { DECODE_NO_PROGRAM } from '../shaders/gpudriven/decode.wgsl.js';
+/**
+ * Words a material entry: tint and emissive, the surface scalars, four program indices, the UV
+ * scale and two strengths, the two ORM scales with the cutout and blend flags, and
+ * the opacity with three spare.
+ *
+ * **It was eight until 2026-09-17**, and metalness took its last spare lane the same day, so the
+ * programs and the scales needed three more blocks rather than squeezing into what was left. It
+ * became twenty-four on 2026-09-18, when transparency arrived and there was nowhere left to put an
+ * opacity: the cutout took lane 18 and the blend flag took 19, and lane 11 is a reserved program
+ * slot rather than a gap. A sixteen-byte block is 1 kB across the whole table, against the 64 kB a
+ * uniform buffer may hold.
+ */
+export const GPU_DRIVEN_MATERIAL_FLOATS = 24;
+/**
+ * Below this base-colour alpha the raster discards a fragment. Zero means no test.
+ *
+ * **Lane 18 rather than lane 11**, which looks spare and is not: the loop below initialises lanes
+ * 8 to 11 to `DECODE_NO_PROGRAM`, so eleven is a fourth program slot somebody reserved rather than
+ * a gap, and a scalar written there would be read back as a program index. Taking 18 leaves the
+ * reservation alone and leaves 19 after it.
+ */
+export const MATERIAL_ALPHA_CUTOFF = 18;
+/**
+ * Non-zero where this material's clusters are drawn blended rather than into the visibility buffer.
+ *
+ * **The last spare lane of twenty**, and a flag rather than an opacity because the opacity is the
+ * tint's fourth component. What this selects is which of the two halves of the frame a cluster
+ * belongs to, which the cut asks once per cluster.
+ */
+export const MATERIAL_BLEND = 19;
+/**
+ * How much of a blended surface is its own colour rather than what is behind it. One is opaque.
+ *
+ * **It is not the tint's fourth component**, which is the emissive gain and has been since the
+ * table was eight floats, and it is not `alphaCutoff`, which decides whether a fragment exists at
+ * all. A material that does not blend never reads this.
+ */
+export const MATERIAL_OPACITY = 20;
+/**
+ * Where a material's emissive program is: the fourth program lane, which the table reserved and
+ * initialised to none before anything used it.
+ */
+export const MATERIAL_EMISSIVE_PROGRAM = 11;
+/** Program lanes a material, and the stride `collectPrograms` writes its indices at. */
+const PROGRAM_LANES = 4;
+/** Every program the materials name, once each by identity, and where each material's are. */
+export function collectPrograms(materials) {
+    const programs = [];
+    const known = new Map();
+    const indexOf = (program) => {
+        if (program === undefined)
+            return DECODE_NO_PROGRAM;
+        const found = known.get(program);
+        if (found !== undefined)
+            return found;
+        programs.push(program);
+        known.set(program, programs.length - 1);
+        return programs.length - 1;
+    };
+    const indices = new Uint32Array(materials.length * PROGRAM_LANES);
+    materials.forEach((material, m) => {
+        indices[m * PROGRAM_LANES] = indexOf(material.textures?.baseColour);
+        indices[m * PROGRAM_LANES + 1] = indexOf(material.textures?.normal);
+        indices[m * PROGRAM_LANES + 2] = indexOf(material.textures?.orm);
+        indices[m * PROGRAM_LANES + 3] = indexOf(material.textures?.emissive);
+    });
+    return { programs, indices };
+}
+/**
+ * The table, `slots` entries long.
+ *
+ * **Written through a `DataView` because one block is integers.** A program index written as a
+ * float would be read by `vec4<u32>` as the float's bits, which names a program four billion
+ * places away and draws nothing — or, clamped, the last program in the table.
+ */
+export function writeMaterialTable(materials, indices, slots) {
+    const buffer = new ArrayBuffer(slots * GPU_DRIVEN_MATERIAL_FLOATS * 4);
+    const view = new DataView(buffer);
+    const float = (m, lane, value) => view.setFloat32((m * GPU_DRIVEN_MATERIAL_FLOATS + lane) * 4, value, true);
+    const word = (m, lane, value) => view.setUint32((m * GPU_DRIVEN_MATERIAL_FLOATS + lane) * 4, value, true);
+    for (let m = 0; m < slots; m += 1) {
+        for (let lane = 8; lane < 12; lane += 1)
+            word(m, lane, DECODE_NO_PROGRAM);
+    }
+    materials.forEach((material, m) => {
+        float(m, 0, material.tint[0]);
+        float(m, 1, material.tint[1]);
+        float(m, 2, material.tint[2]);
+        float(m, 3, material.emissive);
+        /* Roughness one and specular zero: the matte this pipeline drew before either existed. */
+        float(m, 4, material.roughness ?? 1);
+        float(m, 5, material.specular ?? 0);
+        float(m, 6, material.reflectivity ?? 0);
+        float(m, 7, material.metalness ?? 0);
+        for (let lane = 0; lane < PROGRAM_LANES; lane += 1) {
+            word(m, 8 + lane, indices[m * PROGRAM_LANES + lane]);
+        }
+        const textures = material.textures;
+        float(m, 12, textures?.uScale ?? 1);
+        float(m, 13, textures?.vScale ?? 1);
+        float(m, 14, textures?.normal === undefined ? 0 : (textures.normalStrength ?? 1));
+        float(m, 15, textures?.occlusionStrength ?? 1);
+        float(m, 16, textures?.roughnessScale ?? 1);
+        float(m, 17, textures?.metallicScale ?? 1);
+        /* Zero is off, so a material that says nothing about cutout writes the table it wrote before. */
+        float(m, MATERIAL_ALPHA_CUTOFF, material.alphaCutoff ?? 0);
+        /* Zero is opaque, so a material that says nothing about blending stays in the opaque half. */
+        float(m, MATERIAL_BLEND, material.blend === true ? 1 : 0);
+        /* One, so a material that asked to blend and said nothing else is as solid as an opaque one. */
+        float(m, MATERIAL_OPACITY, material.opacity ?? 1);
+    });
+    return buffer;
+}

package/dist/render/gpudriven/pipeline.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The GPU-driven frame, as an order and a set of dependencies.
+ *
+ * **Every stage of Wave 2A exists on its own and this is what says how they fit together.** The
+ * frame's colour is cleared, the directional map is drawn, the meshes wholly outside the view are
+ * flagged, the cut through the cluster graph is chosen without them and phase one culls what was
+ * visible last frame, phase one draws, the depth pyramid is reduced from that, phase two culls the
+ * rest against it and draws, the visibility is copied where a dispatch can read it, binned by
+ * material, and each bin is shaded. Twelve stages, and the edges between them are what stop a
+ * scheduler reordering the ones that must not move — see `twoPhase.ts` for the one that matters
+ * most.
+ *
+ * **The pipeline is opt-in and WebGPU only.** `gpuDrivenSupported` is `indirectSupport`, which is
+ * false on WebGL2 and not a thing a fallback can paper over: without an indirect draw the counts
+ * this frame produces would have to come back to the processor, and a readback is slower than the
+ * draw it would replace. Selecting it on a backend that cannot run it **fails at creation** rather
+ * than falling back, because a silent fallback means a consumer ships believing they have a
+ * pipeline they do not.
+ *
+ * **This is what `GpuDrivenPass` is scheduled by**, since 2026-09-17: the pass records these stages
+ * into a `Deps` table each frame, `scheduleGraph` decides which of them run, and the pass encodes
+ * the ones it kept in the order it kept them. Until then this was a description beside an encoder
+ * with its own fixed order — and the description had drifted, naming a separate instance cull the
+ * encoder never had and a colour both draws wrote when neither does. The instance cull is a stage
+ * of the encoder now, 2026-09-17, which is `wave2a`'s fifth task finally reaching the frame. Binding real buffers and
+ * issuing real dispatches stays the backend's; what moved here is the decision about what runs.
+ */
+import type { Deps } from '../frame/deps.ts';
+/** Whether a backend can run this pipeline at all. */
+export declare function gpuDrivenSupported(backend: 'webgl2' | 'webgpu'): boolean;
+/**
+ * Why a backend cannot, in the words a consumer sees.
+ *
+ * A sentence rather than a code, because the one thing the reader needs is that this is a property
+ * of the backend and not of their scene — and `''` where it can.
+ */
+export declare function gpuDrivenRefusal(backend: 'webgl2' | 'webgpu'): string;
+/**
+ * Every resource a GPU-driven frame moves between its stages, as an identifier each.
+ *
+ * **Named for what the encoder actually binds**, which the first version of this table was not: it
+ * described both draws writing the colour, which neither does, and an instance cull the encoder did
+ * not then have. A description that is not the encoder is a comment, and this one is what the
+ * encoder is scheduled by.
+ */
+export interface GpuDrivenResources {
+    /** Everything uploaded once: bounds, cones, errors, indices, vertices, transforms, materials. */
+    readonly clusters: number;
+    /** Which clusters last frame drew. Imported: this frame reads it and never writes it. */
+    readonly history: number;
+    readonly shadowMap: number;
+    /** Which meshes are wholly outside the view, one flag a mesh. */
+    readonly instances: number;
+    /** The cut through the cluster graph, one flag a cluster, with hidden meshes left out. */
+    readonly cut: number;
+    /** The cull's verdict, one flag a cluster, written by each phase for its own half. */
+    readonly keep: number;
+    /** Each phase's compacted list and the indirect draw that counts it. */
+    readonly listOne: number;
+    readonly listTwo: number;
+    /** Which clusters this frame drew, which is next frame's history. */
+    readonly drawn: number;
+    readonly depth: number;
+    /** The visibility attachment, and the buffer it is copied into so a dispatch can read it. */
+    readonly visibility: number;
+    readonly visibilityCopy: number;
+    readonly hzb: number;
+    readonly binCounts: number;
+    readonly binOffsets: number;
+    /** A copy of the offsets the scatter advances, because the offsets must survive it. */
+    readonly binCursors: number;
+    readonly binPixels: number;
+    readonly colour: number;
+    /** The compacted list of blended clusters and the indirect draw that counts it. */
+    readonly blendList: number;
+    /** The two weighted-transparency targets, and what resolving them writes. */
+    readonly oitAccum: number;
+    readonly oitReveal: number;
+}
+/** The identifiers one frame uses. A frame is its own graph, so they start at zero. */
+export declare const GPU_DRIVEN_RESOURCES: GpuDrivenResources;
+/**
+ * What each stage is called, in the order they are recorded — one render or compute pass each, or
+ * one copy between them.
+ */
+export declare const GPU_DRIVEN_PASSES: readonly ['clearColour', 'shadow', 'instanceCull', 'cut', 'phaseOneDraw', 'pyramid', 'phaseTwoCull', 'phaseTwoDraw', 'blendCull', 'blendDraw', 'visibilityCopy', 'bin', 'cursorCopy', 'shade', 'blendResolve'];
+export type GpuDrivenPassName = (typeof GPU_DRIVEN_PASSES)[number];
+/**
+ * **Every stage is ordered, so none merges with a neighbour.** Two adjacent compute stages could
+ * share a pass as far as their results go; they do not, because each is bracketed by its own pair
+ * of timestamps and a pair brackets a pass. What the schedule decides here is which stages run,
+ * and it checks the order the names give against the edges the stages declare.
+ */
+export declare const GPU_DRIVEN_ORDERED: Uint8Array;
+/** Where each pass landed in the dependency table, by name. */
+export type GpuDrivenNodes = Readonly<Record<GpuDrivenPassName, number>>;
+/** What about this frame changes which stages it needs. */
+export interface GpuDrivenFrameShape {
+    /**
+     * Whether the shading reads the directional map. A frame whose shadow strength is zero does not:
+     * the lookup answers one before any arithmetic, so the map's contents cannot reach a pixel and
+     * the stage that renders it is culled rather than run for nothing.
+     */
+    readonly shadowed: boolean;
+    /**
+     * Whether any material in the table asks to be blended.
+     *
+     * A frame with none schedules the whole transparent half away — the second run of the cut, the
+     * blended draw and the resolve — so a scene that never mentions transparency encodes the frame it
+     * encoded before transparency existed, command for command. `gpuDrivenPass.test.ts` holds that
+     * against a fixed list rather than against a promise.
+     */
+    readonly blended: boolean;
+}
+/**
+ * Record the whole frame, in order, and answer the index its first stage landed at.
+ *
+ * Allocates nothing once a resource table has been seen, which is what lets `GpuDrivenPass` call it
+ * every frame. Stage `i` of `GPU_DRIVEN_PASSES` is node `first + i`.
+ */
+export declare function recordGpuDrivenStages(deps: Deps, res: GpuDrivenResources, shape: GpuDrivenFrameShape): number;
+/** Record the whole frame and answer where each pass went, by name. For a reader, not a frame. */
+export declare function recordGpuDrivenFrame(deps: Deps, res: GpuDrivenResources, shape: GpuDrivenFrameShape): GpuDrivenNodes;
+/**
+ * What a frame leaves behind, which is what `scheduleGraph` is asked to keep alive.
+ *
+ * The colour, which the blit presents, and the history, which next frame's phase one reads. The
+ * depth, the pyramid, the visibility buffer and every bin are this frame's working set and nothing
+ * outside reads them. Naming more than is needed keeps resources alive that could have been
+ * aliased — which is `alias.ts`'s whole subject — and naming fewer culls a pass that was doing
+ * something.
+ */
+export declare function gpuDrivenLive(res: GpuDrivenResources): readonly number[];
+/** What a frame reads without having written: the scene, and last frame's history. */
+export declare function gpuDrivenImports(res: GpuDrivenResources): readonly number[];