@driftengine/core 3.62.0 → 4.0.0

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

@@ -0,0 +1,728 @@
+/**
+ * The GPU-driven frame, as commands on a real encoder.
+ *
+ * **Every stage this runs already existed, twice.** `gpudriven/*.ts` is the arithmetic in
+ * TypeScript, `shaders/gpudriven/*.wgsl.ts` is the same arithmetic in WGSL, and
+ * `scripts/gpu-parity.mjs` runs both over generated input on a real device until they agree —
+ * nine checks as this was written. `gpudriven/pipeline.ts` says what each stage reads and writes, as
+ * frame-graph edges, and **the frame is scheduled by it**: each `prepare` records the stages,
+ * `scheduleGraph` keeps the ones something reads, and this encodes those in the order kept. What
+ * was missing, and what this is, is the encoder: the buffers, the bind groups, the targets and the
+ * two indirect draws.
+ *
+ * **It is a contributed pass, not a branch inside the renderer, and that is the design.**
+ * `registerPass` hands a definition a `GPUDevice` at registration and a `GPUCommandEncoder` once a
+ * frame before the frame's own render pass opens — which is exactly the window a pipeline that
+ * fills its own targets needs, and it is the seam `pass.ts` exists to provide. The alternative is
+ * rerouting `drawMesh` through clusters, which would mean a second copy of the standard material
+ * to draw anything at all; the plan refuses that in the same words this file does.
+ * `createRenderer({ pipeline: 'gpu-driven' })` is the *permission* — it fails at boot on a backend
+ * that cannot run this — and this is the implementation. A consumer states both.
+ *
+ * **What it draws.** Vertex colour times a material tint, one directional term with its specular
+ * highlight and its shadow, the forward path's hemispheric ambient or a baked probe's irradiance,
+ * the room a surface reflects, metalness, a glow scaled by the frame's clock, and DriftTexture
+ * materials decoded per pixel — the standard material's subset, which `CAPABILITIES.md` §3 lists
+ * with what it leaves out. The rigs that draw it are `DRAFT_SCENES`, never `SCENES`.
+ *
+ * **A mesh wholly outside the view is dropped before the cut reads a cluster of it**, since
+ * 2026-09-17: `instanceCull` flags each mesh against the frustum, the cut leaves a flagged mesh's
+ * clusters unselected, and the cluster cull skips whatever the cut did not select. `instances.ts`
+ * says why the flag is read there and not by the cluster cull: eight storage bindings a stage, and
+ * the cluster cull already had seven.
+ *
+ * **The shadow is this pipeline's own, and it costs what it costs.** One depth-only draw of every
+ * cluster from the light, into a 2048 map: **0.46 ms** on a million triangles, which is nearly as
+ * much again as the frame itself. There is no culling in it — the frame's cull is against the
+ * camera and a caster behind the viewer still shadows what is in front of them — so the obvious
+ * next measurement is a cull against the light's own box.
+ *
+ * **The visibility buffer is copied to a buffer once a frame, and that is a real cost.** The
+ * binning passes read `array<u32>` and a render attachment cannot be bound as one. The copy is
+ * ordered and correct where a fragment shader writing storage is neither — two fragments passing
+ * the depth test for one pixel race, and the loser can land last. `width` is rounded up to a
+ * multiple of 64 so that `bytesPerRow` is a multiple of 256 with no padding, which is what keeps
+ * the buffer linear: a padded row would put undefined words where the binning reads pixels, and
+ * an undefined word that happens to be zero is triangle 0 of cluster 0 — a real triangle.
+ *
+ * **The shading's pixel centre is the flipped row, and this is the one convention trap here.**
+ * WebGPU's framebuffer origin is the top-left, so row zero is where clip `y` is `+1`; `screenOf`
+ * maps clip `y = +1` to `height`. So the pixel at framebuffer row `y` is at screen `height - y`,
+ * and the flip is applied to the pixel rather than to the shared function — which is checked
+ * against the reference and must not learn about a framebuffer. Flipping all four points of a
+ * barycentric evaluation leaves the weights unchanged, which is why this is the whole of it. It is
+ * true of either projection, because it is a property of the viewport transform and not of the
+ * matrix.
+ *
+ * **The projection is `depthCorrection` and not `clipCorrection`.** The Y negation in the latter
+ * cancels the one `naga` writes into every *generated* vertex entry point; nothing here was
+ * generated, so taking it mirrors the picture — and mirrors the winding with it, which is how it
+ * reads as a culling problem. `PassDevice` carries both matrices and says which is which.
+ */
+import { type FogOptions } from '../../fog.ts';
+import { StreamingScene } from '../../gpudriven/streamScene.ts';
+import { type GpuDrivenTextures } from '../../gpudriven/materialTable.ts';
+import type { PassContext, PassDefinition, PassDevice, PrepareContext } from '../../pass.ts';
+/**
+ * Floats a material owns: tint rgb, emissive, roughness, specular, reflectivity, metalness.
+ *
+ * Five blocks since 2026-09-17 — the three texture programs, the UV scale and the map strengths
+ * joined the eight — and `gpudriven/materialTable.ts` writes them.
+ */
+export declare const MATERIAL_FLOATS = 24;
+/** Floats a vertex in the one interleaved buffer: position, normal, colour, uv. */
+export declare const VERTEX_FLOATS = 12;
+/**
+ * What the frame is timed in, one pair of timestamps each.
+ *
+ * **Measured rather than reasoned, because the whole wave rests on a cost claim.** A frame-time
+ * reading from `requestAnimationFrame` measures the submission loop and nothing else — with vsync
+ * off it reports half a millisecond for a scene of a million triangles, because the device is
+ * still working when the callback returns. These are the device's own clock.
+ *
+ * Only where the device has `timestamp-query`, which `createRenderer` asks for when
+ * `quality.gpuTiming` is set — `?gputiming=1` on the harness pages. Without it every figure is
+ * `null`, which is `gpuTimer.ts`'s rule: zero is a claim and unmeasured is not zero.
+ */
+export declare const GPU_DRIVEN_STAGES: readonly ['shadow', 'instanceCull', 'cut', 'phaseOneDraw', 'pyramid', 'phaseTwoCull', 'phaseTwoDraw', 'blendCull', 'blendDraw', 'blendResolve', 'bin', 'shade'];
+export type GpuDrivenStage = (typeof GPU_DRIVEN_STAGES)[number];
+/**
+ * The frame's four draw lists, each counted by the clusters it drew: phase one (what was visible
+ * last frame and still is), phase two (what the pyramid found newly visible), the blended half, and
+ * the light's map.
+ *
+ * **The occlusion cull's own figure.** A cluster the cull kept is one instance of its list's
+ * indirect draw, so the second word of each list's arguments is that list's count — the number a
+ * city in a street and above its roofs is there to show. Read back only where `countDrawn` asks.
+ */
+export declare const GPU_DRIVEN_LISTS: readonly ['phaseOne', 'phaseTwo', 'blend', 'shadow'];
+export type GpuDrivenList = (typeof GPU_DRIVEN_LISTS)[number];
+/** What a material tints and emits. */
+export interface GpuDrivenMaterial {
+    readonly tint: readonly [number, number, number];
+    /** Added to the lit colour as `albedo * emissive`. Zero for an ordinary surface. */
+    readonly emissive: number;
+    /**
+     * 0 is a mirror and 1 is fully rough. Defaults to 1, which is the matte this pipeline had.
+     *
+     * **Below 0.1 the highlight gets *dimmer* as the surface gets smoother**, which is the forward
+     * path's own lobe and is recorded in `docs/IMPROVEMENTS.md` rather than fixed here — the
+     * published scenes are calibrated against the shader that has it.
+     */
+    readonly roughness?: number;
+    /**
+     * How much of the light the surface returns as a highlight. Defaults to 0.
+     *
+     * **Zero is what keeps this from moving anything**: a material that says nothing about shininess
+     * renders exactly the frame it rendered when the lit expression was four lines.
+     */
+    readonly specular?: number;
+    /**
+     * How much of the environment the surface returns, before angle and roughness. Defaults to 0.
+     *
+     * With no probe bound this reflects the same two-colour gradient the ambient comes from, which
+     * is what the forward path reflects in the same situation — see `gpudriven/ibl.ts` for the two
+     * weights and why the selector between them is exactly 0 or exactly 1.
+     */
+    readonly reflectivity?: number;
+    /**
+     * 0 is a dielectric and 1 is a metal. Defaults to 0.
+     *
+     * **One number a material, where `flat/main.ts` reads one texel of an ORM map.** That is the
+     * whole of the difference and it is a subset rather than a second opinion: every expression it
+     * enters is the forward path's with a constant standing in for a fetch. See `gpudriven/lit.ts`
+     * for the four of them.
+     *
+     * **A metal reflects whether or not `reflectivity` asked for it**, because a metal is nothing but
+     * its reflection — and with no probe bound, what it reflects is the sky-and-ground gradient. A
+     * metal in a scene with neither is a smooth gradient rather than a picture, which is a statement
+     * about the scene rather than about the material.
+     */
+    readonly metalness?: number;
+    /**
+     * The material's maps, as DriftTexture decode programs, decoded per shaded pixel on the device.
+     *
+     * **A material with none uploads exactly the entry it uploaded before textures existed**, so the
+     * frame it draws is unchanged — the promise every term in this pipeline makes. See
+     * `gpudriven/materialTable.ts` for what each program feeds and `decodeTables.ts` for the limits.
+     */
+    readonly textures?: GpuDrivenTextures;
+    /**
+     * Discard a fragment whose base-colour alpha is below this. Zero means no test.
+     *
+     * **The test happens in the raster rather than in the shading pass**, because that is where a
+     * pixel learns which triangle owns it: a discard in `shade` would come after the visibility
+     * buffer already held the leaf, and what stood behind it was never written.
+     *
+     * Zero is the default and it skips the fetch outright, so a material that says nothing about
+     * cutout draws exactly the frame it drew before — the promise every term in this pipeline has
+     * made since it was four lines. A cluster carries one material, so the branch is coherent across
+     * every fragment of a draw rather than divergent within one.
+     *
+     * **It needs a `textures.baseColour` program to mean anything.** With no base-colour map there is
+     * no alpha to test, and the raster reads 1 — so a cutoff at or below 1 keeps every fragment and
+     * one above 1 discards the whole surface. Both are what the material asked for, stated here
+     * because an invisible mesh is a hard thing to attribute.
+     */
+    readonly alphaCutoff?: number;
+    /**
+     * Draw this material's clusters blended instead of into the visibility buffer. Defaults to false.
+     *
+     * **A visibility buffer stores one surface a pixel, so it cannot hold a blend at all** — that is
+     * architecture rather than an omission. What a blended material asks for is that its clusters
+     * skip the opaque half entirely and be drawn again by a second raster that shades in its own
+     * fragment stage and writes the two weighted-transparency targets. The cut runs a second time to
+     * find them, and a scene with no blended material runs neither stage.
+     *
+     * **The opacity is `tint`'s fourth component, not this**; this only says which half of the frame
+     * the surface belongs to. See `blendRaster.wgsl.ts` for what the second half does with it, and
+     * `orderIndependent.ts` for the weight and what it approximates.
+     */
+    readonly blend?: boolean;
+    /**
+     * How much of a blended surface is its own colour rather than what is behind it. Defaults to 1.
+     *
+     * Read only where `blend` is set. One is a solid pane, which is what a material that asked to
+     * blend and said nothing else gets — visible, and therefore findable.
+     */
+    readonly opacity?: number;
+}
+/** What the pass needs told once a frame, before `beginFrame`. */
+export interface GpuDrivenView {
+    /** The camera's view-projection, built the way the forward path builds one. */
+    readonly viewProj: ArrayLike<number>;
+    readonly eye: readonly [number, number, number];
+    /** Toward the light, normalised, as `Environment.directionalDir` is. */
+    readonly lightDir: readonly [number, number, number];
+    readonly lightColour: readonly [number, number, number];
+    readonly ambient: readonly [number, number, number];
+    readonly ambientGround: readonly [number, number, number];
+    /**
+     * The medium between the camera and everything this pass draws. Absent is no fog at all.
+     *
+     * **Absent means a density of zero and the medium mode**, which makes `mediumFog` exactly zero at
+     * every distance — arithmetically the frame this pipeline drew before it had a haze, which is the
+     * promise every term here has made since it was four lines. The three rigs pass nothing.
+     *
+     * **It is the same expression the forward path fogs with**, held to `render/fog.ts` by
+     * `scripts/gpu-parity.mjs`; a scene drawing through both pipelines at once — which is what the
+     * voxel sandbox's port is — would otherwise have its terrain recede at a different rate than its
+     * mobs do.
+     */
+    readonly fog?: FogOptions;
+    /**
+     * The projected error a cluster may carry before its children are drawn instead, in pixels.
+     *
+     * Larger keeps coarser clusters and draws fewer triangles. `lodCut.ts` is what reads it.
+     */
+    readonly lodThreshold: number;
+    /** The vertical field of view in radians, which the cut needs to project an error. */
+    readonly fovY: number;
+    /**
+     * How much of the directional light the shadow map may take away. 0 is off and 1 is the whole
+     * of it.
+     *
+     * **Off is exact rather than nearly**: `shadowFactor` returns 1 before any arithmetic at zero,
+     * so a frame that asks for none is the frame this pipeline drew before it had a map. Defaults
+     * to 1, because a pipeline that renders a map and then ignores it is a cost with no picture.
+     */
+    readonly shadowStrength?: number;
+    /**
+     * The simulation's clock, in seconds, which an animated DriftTexture reads. **Never a wall
+     * clock**: a flipbook read off one would replay differently. Defaults to 0.
+     */
+    readonly time?: number;
+    /**
+     * The frame's emissive gain and night factor, as `Environment` carries them. **Both default to
+     * 1**, which is the glow this pipeline drew before it read either.
+     *
+     * `flat/main.ts` scales every emission by their product, so a forward frame whose clock says it
+     * is day glows nowhere. A caller drawing both pipelines from one `Environment` passes its two
+     * numbers here, or the second pipeline glows where the first does not.
+     */
+    readonly emissiveGain?: number;
+    readonly nightFactor?: number;
+}
+/**
+ * What the pass is told once, at construction, about the map it renders.
+ *
+ * **Its own defaults rather than a `RenderQuality`**, because a contributed pass is handed a
+ * device and not the frame's settings — `PassDevice` is the whole of what it gets. The numbers are
+ * the forward path's, taken from `DEFAULT_RENDER_QUALITY` so the two pipelines fade a shadow out
+ * over the same distance and give up on the same low sun rather than nearly.
+ */
+export interface GpuDrivenShadowOptions {
+    /** Texels a side. 2048 is `directionalShadowMapSize`, and a draft can afford it. */
+    readonly mapSize?: number;
+    /** Metres a shadow travels along the ground before it has dissolved. */
+    readonly maxDistance?: number;
+    /** The steepest sun that still casts, as horizontal metres per vertical one. */
+    readonly maxSlope?: number;
+    /** Taps of the twelve the filter may take. Fewer is cheaper and harder-edged. */
+    readonly taps?: number;
+    /**
+     * Hand the frame this pass's depth as well as its colour, so both pipelines share one.
+     *
+     * **Off by default, because every consumer before 2026-09-18 drew nothing but this pipeline.**
+     * For them the frame's depth is something nothing reads and a write into it is a change to a
+     * frame they did not ask to change; the three GPU-driven rigs leave it alone, which is what keeps
+     * them 0 of 921,600 and keeps them the control.
+     *
+     * **On, it is what lets a forward-path mesh stand behind GPU-driven geometry.** Without it the
+     * two have no depth relationship at all and no ordering of them produces one — which is the gap
+     * the voxel sandbox's port found, where mobs, particles, falling blocks and the block highlight
+     * all draw on the forward path. `scripts/depth-share-check.mjs` is the gate.
+     *
+     * It costs one more sampled texture in the blit and a fragment depth write over the pixels this
+     * pipeline covered. A pixel it did not cover is discarded before either, so the sky keeps the
+     * depth the frame already had.
+     */
+    readonly presentDepth?: boolean;
+    /**
+     * Metres around the eye the map covers once the scene is larger than that. See `fitShadow`.
+     *
+     * **Unset, the map is fitted to the whole scene, as it always was** — right for rigs a few
+     * metres across and the fit all three were photographed with. A world sets it: the voxel
+     * sandbox's port at radius 14 is a sphere hundreds of metres across, over which one map has
+     * texels a quarter of a metre wide. Past the radius the map follows the eye, snapped to whole
+     * texels, and reaches toward the sun as far as the scene does.
+     */
+    readonly followRadius?: number;
+}
+export declare class GpuDrivenPass implements PassDefinition {
+    readonly label = "driftengine.gpu-driven";
+    private readonly scene;
+    private readonly materials;
+    private device;
+    private width;
+    private height;
+    /** The width the targets are actually allocated at: `width` rounded up. See `WIDTH_ALIGN`. */
+    private stride;
+    private readonly frameParams;
+    private readonly planes;
+    /** The light's box as six planes, from the matrix the lookup reads. */
+    private readonly lightPlanes;
+    private readonly cullSettings;
+    private readonly lodParams;
+    private readonly binSettings;
+    private readonly viewProj;
+    private readonly corrected;
+    /** The light's own, in the OpenGL convention, and the two corrections of it. */
+    private readonly light;
+    private readonly lightRaster;
+    private readonly lightLookup;
+    /** The scene's bounding sphere, computed once: centre and radius. */
+    private readonly bounds;
+    /** Which programs each material names, and the programs themselves, once each. */
+    private readonly programs;
+    /** Those programs flattened into what the shading pass binds. */
+    private readonly decode;
+    /**
+     * Every cluster's bounds, cone and error **through the transform of the mesh it belongs to**.
+     *
+     * Computed at construction and held, because it is what both the cull buffer and the LOD buffer
+     * are written from and what the light's box is fitted to — one transform, read three times. This
+     * pipeline never moves a mesh, so it is a property of the scene; a pipeline that did would have
+     * to rewrite these two buffers on the frame it moved one.
+     */
+    /**
+     * Each mesh's world sphere, round its clusters' world spheres — `instances.ts`. Fitted here
+     * rather than at mount so a cluster naming a mesh the transforms do not have is refused where the
+     * scene was handed in.
+     */
+    private readonly meshCount;
+    private shadowSpan;
+    private readonly shadowSize;
+    /** What the frame offered this time, or null. Read in `writeFrame` and nowhere else. */
+    private environment;
+    private readonly shadowMaxDistance;
+    private readonly shadowMaxSlope;
+    private readonly shadowTaps;
+    private clipCorrection;
+    private view;
+    private clusterCull;
+    private clusterLod;
+    private clusterMeta;
+    private instanceSpheres;
+    private indices;
+    private vertices;
+    private transformBuffer;
+    private materialOf;
+    private materialTable;
+    private jobs;
+    /**
+     * **The light's own front half, in the camera's two phases**: the camera's cut with no mesh
+     * hidden, a cull against the light's box from the sun's side, and a compaction into the list each
+     * half of the map draws — phase one what the light kept last frame, phase two the rest against a
+     * pyramid of what phase one drew. Every buffer the light writes is its own. See `drawShadow`.
+     */
+    private shadowList;
+    private shadowListTwo;
+    private shadowArgs;
+    private shadowArgsTwo;
+    private shadowSelected;
+    private shadowKeep;
+    private shadowPlanes;
+    private shadowCullSettings;
+    private shadowCullSettingsTwo;
+    /**
+     * The light's cull settings: its cone eye, stood `LIGHT_CONE_DISTANCE` toward the sun from the
+     * camera's (`lightConeEye`), whether to read the pyramid, the pyramid's shape, the count and the
+     * cones, which are on. One array, written into phase one's buffer and then phase two's.
+     */
+    private readonly shadowCullValues;
+    private readonly shadowConeEye;
+    private shadowCompactSettings;
+    private shadowCompactSettingsTwo;
+    /**
+     * **The light's history, one word a cluster, in two halves that swap each frame the map is
+     * drawn** — and only then, so a frame with no shadow leaves the next one reading what the last
+     * one wrote. One history per view, as `twoPhase.ts` says: the camera's would put what the camera
+     * saw into the light's phase one.
+     */
+    private shadowHistories;
+    private shadowFlipped;
+    /**
+     * The light's pyramid: half its map and every level below it (`shadowPyramidBase`), stored
+     * turned over so the camera's reduction and cull read it, and where each level starts.
+     */
+    private shadowHzb;
+    private shadowLevels;
+    private shadowLevelStart;
+    private shadowSeedSize;
+    /** The raster's matrix with its depth turned over, which is what the light's cull projects by. */
+    private shadowCullMatrix;
+    private readonly lightCull;
+    private instanceNone;
+    private shadowLodGroup;
+    private shadowCullGroups;
+    /** Each half's compaction, for each way round the history is: `[flipped][phase]`. */
+    private shadowCompactGroups;
+    private shadowSeedGroup;
+    private shadowReduceGroups;
+    private shadowSeedPipeline;
+    private shadowMatrix;
+    private shadowTexture;
+    private decodeNodes;
+    private decodeWeights;
+    private latents;
+    private latentsView;
+    private latentClamp;
+    private latentRepeat;
+    private shadowView;
+    /**
+     * What is bound as the probe where the frame has none.
+     *
+     * **One texel, one layer, and it exists because a bind group must supply every binding.** The
+     * alternative is a second pipeline and a second layout for the unlit case, which is two copies
+     * of the shading pass to avoid one 4-byte texture. The renderer binds a stand-in in exactly the
+     * same situation and for exactly the same reason — see `depthPass.ts` on the peel.
+     */
+    private emptyEnvironment;
+    private emptyEnvironmentView;
+    private emptySampler;
+    /** The probe the last frame offered, so the bind group is rebuilt only when it changes. */
+    private environmentView;
+    private environmentSampler;
+    private planesBuffer;
+    private viewProjBuffer;
+    /**
+     * The two numbers the raster's alpha test needs and nothing else in that stage carries.
+     *
+     * **A buffer of its own rather than four more floats on `viewProjBuffer`**, which the instance
+     * cull also binds and declares as `array<f32, 16>`: growing a buffer two shaders read means both
+     * have an opinion about what is past the sixteenth float, and one of them would be wrong on the
+     * day somebody used the spare.
+     */
+    private rasterParams;
+    /**
+     * The transparent half's own buffers, textures and pipelines.
+     *
+     * **`zeroHistory` is what makes the cut's second run see every cluster.** The compaction
+     * filters on `history[i] != 0` against its phase, which is how the two occlusion phases divide
+     * the scene between them; the blended set is not divided, so it is compacted as phase one against
+     * a history that is all zeros — every cluster then lands on the side that draws. `historySink` is
+     * the history that run writes and nothing reads, which is the price of leaving the compaction
+     * shader alone rather than growing it a third phase nothing else would ever take.
+     */
+    private blendList;
+    private blendArgs;
+    private blendLodBuffer;
+    private blendCompactSettings;
+    private zeroHistory;
+    private historySink;
+    private oitAccum;
+    private oitReveal;
+    private oitAccumView;
+    private oitRevealView;
+    private blendPipeline;
+    private blendResolvePipeline;
+    private blendLodGroup;
+    private blendCompactGroup;
+    private blendRasterGroup;
+    private blendResolveGroup;
+    /** Seven floats: the cut's six, and a seventh saying which half of the frame it is selecting. */
+    private readonly lodParamsBlend;
+    private readonly rasterParamValues;
+    /** One a phase, for the reason `writeFrame` gives. */
+    /** Phase one, phase two, and the blended run: see `CULL_CONES` for why the third exists. */
+    private cullBuffers;
+    private lodBuffer;
+    /** One word a mesh, written by the instance cull and read by the cut. */
+    private instanceFlags;
+    private frameBuffer;
+    private selected;
+    private keep;
+    private history;
+    private drawn;
+    private lists;
+    private args;
+    private phaseSettings;
+    private visibilityTexture;
+    private depthTexture;
+    private colourTexture;
+    private colourView;
+    private visibility;
+    private hzb;
+    private levelStart;
+    private levels;
+    private binCounts;
+    private binOffsets;
+    private binCursors;
+    private binDispatch;
+    private binPixels;
+    private binSettingsBuffer;
+    private instancePipeline;
+    private lodPipeline;
+    private cullPipeline;
+    private compactPipeline;
+    private seedPipeline;
+    private reducePipeline;
+    private countPipeline;
+    private offsetsPipeline;
+    private scatterPipeline;
+    private shadePipeline;
+    private rasterPipeline;
+    private shadowPipeline;
+    private blitPipeline;
+    /** See `GpuDrivenShadowOptions.presentDepth`: what the consumer asked for. */
+    private readonly presentDepthAsked;
+    /**
+     * Whether the blit hands the frame this pass's depth: when asked, and whenever the renderer
+     * reconstructs, which reprojects every pixel's history through that depth. Settled at `init`,
+     * where the device says which; the pipeline follows it.
+     */
+    private presentDepth;
+    /**
+     * The frame's jitter, as `prepare` was last handed it: zero until then, and on every frame that
+     * is not reconstructed. See `PrepareContext.jitter`.
+     */
+    private jitter;
+    /** See `GpuDrivenShadowOptions.followRadius`. Unset, the map is fitted to the whole scene. */
+    private readonly shadowFollow;
+    private frameDepthFormat;
+    private lodGroup;
+    private instanceGroup;
+    private compactGroups;
+    private rasterGroups;
+    private shadowGroup;
+    private shadowGroupTwo;
+    private jobGroups;
+    private cullGroups;
+    private seedGroup;
+    private reduceGroups;
+    private countGroup;
+    private offsetsGroup;
+    private scatterGroup;
+    private shadeGroup;
+    private blitGroup;
+    private queries;
+    private queryResolve;
+    private queryRead;
+    private queryCopied;
+    private queryMapping;
+    private readonly stageMs;
+    private timed;
+    /**
+     * **Whether phase two and the blended run test clusters against the depth pyramid** — the
+     * occlusion cull — **and the light's second half against its own.** On by default and off only
+     * to measure it: the instance cull is the frustum alone and phase one never reads a pyramid, so
+     * with this off each view draws every cluster its frustum and cones keep, and the drawn count's
+     * difference is the occlusion cull's own share. The pyramids are still built; a frame that
+     * measures does not also save their cost.
+     */
+    occlusion: boolean;
+    /**
+     * **Whether the pass reads back how many clusters each list drew.** Off, it encodes nothing for
+     * it and makes no buffer, which is why it is asked for rather than always on: the figure is a
+     * demo's readout and a measurement's, and a consumer who reads neither pays nothing.
+     */
+    countDrawn: boolean;
+    private counts;
+    private countsCopied;
+    private countsMapping;
+    private readonly drawnCounts;
+    private counted;
+    /** Whether `history` and `drawn` have been swapped an odd number of times. */
+    private flipped;
+    private readonly graph;
+    private readonly scheduled;
+    private readonly graphScratch;
+    private readonly shape;
+    private gradeWarned;
+    constructor(scene: StreamingScene, materials: readonly GpuDrivenMaterial[], shadow?: GpuDrivenShadowOptions);
+    /** How many clusters the scene holds, which every per-cluster dispatch is sized by. */
+    get clusterCount(): number;
+    /**
+     * What this frame is looking at. Called before `beginFrame`, once, by the caller.
+     *
+     * Held by reference rather than copied: the caller owns a `GpuDrivenView` it fills each frame,
+     * and copying it here would allocate on a per-frame path for no gain.
+     */
+    setView(view: GpuDrivenView): void;
+    /**
+     * Size the targets. Called on mount and whenever the frame's own size changes.
+     *
+     * **Dispose and recreate rather than resize**, which is `passTarget.ts`'s rule and is right for
+     * the same reason: a resize is not a per-frame path and a mutable target is one more thing to
+     * keep consistent.
+     */
+    resize(width: number, height: number): void;
+    init(device: PassDevice): void;
+    private storage;
+    private empty;
+    /**
+     * Every buffer the scene lives in, at its declared capacity.
+     *
+     * **Called `buildStatic` until 2026-09-18**, and the word was the whole of what changed: these
+     * are sized by `scene.capacity` rather than by what the scene currently holds, so there is room
+     * for a mesh that has not arrived yet. A static scene declares a capacity equal to its content,
+     * so nothing about it moves.
+     *
+     * **The scene writes two of them itself and keeps no copy of either.** `vertices` and `indices`
+     * are made empty at capacity and handed to the scene as a `GeometrySink`; the interleave —
+     * twelve floats a vertex, position, normal, colour, uv and glow — is the scene's. It is one
+     * buffer rather than five because of a device limit: a compute stage may bind eight storage
+     * buffers by default, and the shading pass wanted twelve and was refused at pipeline creation.
+     *
+     * **The two culling buffers are already in the world.** What a bake writes is a cluster in its
+     * mesh's own space, and this pass used to upload that — while the raster and the shading both
+     * multiplied by `transforms[mesh]`. A mesh placed anywhere but the origin was then frustum-culled
+     * against the wrong region, cone-culled with the wrong orientation, LOD-cut on a misprojected
+     * error and occlusion-tested on the wrong rectangle, and every rig in `DRAFT_SCENES` stood at the
+     * origin so nothing ever said so. `StreamingScene` computes them when a mesh is placed.
+     */
+    private buildBuffers;
+    private buildPipelines;
+    /**
+     * The groups that name `history` and `drawn`, rebuilt when the two swap.
+     *
+     * **Two sets rather than a copy**, because the alternative is copying a buffer the size of the
+     * cluster count every frame to keep one binding pointing at the right half. A bind group is
+     * cheap to build and this happens once a frame; making it twice and alternating would be
+     * cheaper still, and is what this does — `flipped` picks the pair.
+     */
+    private buildSwappedGroups;
+    private disposeTargets;
+    /**
+     * A pyramid's levels over a base this size, down to one texel: each level padded so its byte
+     * offset is one a bind group may name, with its own size block — the source's shape, where it
+     * starts, and where its output goes, because the reduction addresses both ends of one buffer
+     * itself (see `HZB_REDUCE_WGSL`). The camera's is over the frame; the light's over half its map.
+     */
+    private pyramidLevels;
+    private buildTargets;
+    private buildSizedGroups;
+    /**
+     * Take the frame's probe, and say whether the shading pass's bind group has to be rebuilt.
+     *
+     * **Compared by identity rather than copied**, because a texture view is the thing that changes
+     * when a grid is rebaked at a different size and nothing else in the block does. A frame that
+     * offers the same view as the last one rebuilds nothing.
+     */
+    private adoptEnvironment;
+    /** Fill the per-frame blocks from the view the caller set. */
+    /**
+     * Upload the records the scene has changed since the last frame (its geometry went up when it
+     * was placed), and nothing else.
+     *
+     * **Before anything is recorded into the encoder, because a dispatch reads what a queue write
+     * has not landed.** `queue.writeBuffer` is ordered against other queue work and *not* against an
+     * encoder's commands, which this backend has already paid for once: rewriting one params buffer
+     * between dispatches gave every dispatch the last write, and the fix there was one bind group per
+     * dispatch at a 256-aligned offset. Here the ordering is simply respected.
+     *
+     * **A frame that changed nothing uploads nothing**, which is what makes a static scene cost what
+     * it cost before this existed.
+     */
+    private applyStream;
+    /** The radius of the sphere the shadow camera is fitted to. Diagnostic, and a test reads it. */
+    shadowExtent(): number;
+    private writeFrame;
+    prepare(ctx: PrepareContext): void;
+    /**
+     * One stage of the frame, onto the encoder. `pipeline.ts` says what each reads and writes, and
+     * the schedule says whether it runs; this is what it issues.
+     */
+    private encodeStage;
+    /**
+     * The device milliseconds each stage took, or null where nothing measured them.
+     *
+     * One frame behind, because a timestamp is read back and a readback that blocked would be the
+     * measurement changing what it measures. `null` until a frame has completed a map.
+     */
+    stageTime(stage: GpuDrivenStage): number | null;
+    /** Every stage added up, which is what the pipeline costs the device. */
+    get totalMs(): number | null;
+    /** The pair of slots a stage writes, or nothing where the device cannot time. */
+    private writesFor;
+    /**
+     * Ask for last frame's figures, once the frame that recorded them has been submitted.
+     *
+     * **At the start of the next frame rather than at the end of this one**, which is the whole of
+     * the care this needs: `mapAsync` settles against the work already enqueued, and the copy is
+     * still sitting in an encoder the renderer has not submitted yet.
+     */
+    private readTimings;
+    /**
+     * How many clusters `list` drew, one frame behind as the stage times are, or null until a frame
+     * has been read — and null always where `countDrawn` was not asked for.
+     */
+    drawnClusters(list: GpuDrivenList): number | null;
+    /**
+     * Each list's count into the read buffer, **after the whole frame**, so every draw that reads an
+     * argument block has been encoded before the copy out of it. The buffer is cleared first, so a
+     * list the frame did not draw — no blended material, no shadow — reads as none rather than as
+     * whatever the last frame that drew it left. Nothing while a read is in flight: a buffer that is
+     * mapped cannot be copied into. (A copy not yet read cannot be here: `readCounts` runs at the top
+     * of every frame this ends, and maps whatever was copied.)
+     */
+    private copyCounts;
+    /** Last frame's counts, asked for as `readTimings` asks for its figures and for its reason. */
+    private readCounts;
+    /** How many workgroups one dispatch over every cluster takes. */
+    private clusterGroups;
+    /** The half of the ping-pong this frame writes, which next frame will read. */
+    private writeHistory;
+    /**
+     * The map: what the light's own cull kept, drawn from the light, depth only — **in the camera's
+     * two halves.**
+     *
+     * **The front half's three pipelines over buffers of the light's, twice**: the cut, the cull
+     * against the light's box from the sun's side, and a compaction of what the light kept last
+     * frame, drawn; then a pyramid of that depth, the same cull against it, and a compaction of the
+     * rest, drawn over it. A three-degree sun over a city sees a strip of it a kilometre deep, and
+     * everything behind the first row toward the sun is in that row's shadow — which is exactly what
+     * the pyramid of the first half says, and what the frustum and the cones alone could not.
+     * `CLUSTER_INDEX_CAP` vertices by one instance a listed cluster, as in the frame's own draw.
+     *
+     * **One figure for the stage**: the first compute pass writes where the stage began and the
+     * second render pass where it ended, so `shadow` in the stage times is all of it.
+     */
+    private drawShadow;
+    /** One half of the map: the first clears it, the second draws over it and closes the stage's time. */
+    private drawShadowHalf;
+    private drawPhase;
+    draw(ctx: PassContext): void;
+    dispose(device: PassDevice): void;
+}