@driftengine/core 3.61.0

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

@@ -0,0 +1,94 @@
+/**
+ * What a WebGPU frame cost, from the GPU rather than from a clock.
+ *
+ * **This backend shipped without one, and that is why a phone was slow for a release without
+ * anybody being able to say by how much.** `WebGpuRenderer.gpuTimer` was a stub reporting
+ * `available: false` and `null` forever, so every GPU figure this project has ever quoted came
+ * from WebGL2 — the backend phones do not use. The consumer's own rule is that a
+ * GPU verdict needs `gpuSamples > 0`, which on the shipping backend could never be satisfied,
+ * so the frame meter, the FPS report and the diagnostics bundle all had a hole exactly where
+ * the answer was.
+ *
+ * **Nothing here is new API.** It implements `FrameTimer`, the same interface `GpuTimer`
+ * implements over `EXT_disjoint_timer_query_webgl2`, so the game that already calls
+ * `beginFrame`, `begin('rest')`, `end`, `endFrame` and `poll` starts getting numbers without
+ * one line changing over there.
+ *
+ * **The one shape difference, and it is forced by the API.** WebGL2 brackets an arbitrary run
+ * of commands with `TIME_ELAPSED_EXT`. WebGPU cannot: a timestamp is written at the start and
+ * the end of a *render pass*, declared on the pass descriptor. So the bracket becomes an
+ * attribution rather than a measurement — `begin(slot)` records which slot is open,
+ * `writesFor` hands the next query pair to each pass the renderer opens and remembers where it
+ * belonged, and the readback sums the pass deltas per slot. A pass drawn without calling
+ * `writesFor` is GPU time the total silently omits, which is the one way to get a wrong number
+ * out of this rather than no number.
+ *
+ * **Never blocks.** A frame resolves its queries into a staging buffer and asks for the
+ * mapping; the answer lands a frame or two later and is reported then. A timer that waited for
+ * its own frame would be a stall, which is the one thing a profiler must not add.
+ */
+import type { FrameTimer } from '../timer.ts';
+import { type GpuSample, type GpuSlot } from '../../gpuTimer.ts';
+export declare class GpuTimestamps implements FrameTimer {
+    /** False where the adapter withheld `timestamp-query`, which is a normal state. */
+    readonly available: boolean;
+    private readonly querySet;
+    private readonly resolveBuffer;
+    private readonly readBuffer;
+    private readonly sampleEvery;
+    /** Which slot each timed pass of the frame being recorded belongs to. */
+    private readonly passSlots;
+    /** The same, for the frame whose readback is in flight; the recorder reuses the other. */
+    private readonly inFlightSlots;
+    private passCount;
+    private inFlightCount;
+    private openSlot;
+    private frame;
+    private measuring;
+    /** Whether this frame's queries have already been copied out; a second copy is a no-op. */
+    private resolved;
+    private readbackBusy;
+    private readonly pending;
+    private lastSample;
+    get sampling(): boolean;
+    constructor(device: GPUDevice, enabled?: boolean, sampleEvery?: number);
+    /**
+     * Whether this frame is measured. Called once per frame, before any `begin`.
+     *
+     * Declines while a readback is still in flight, and that is not politeness: the read buffer
+     * belongs to the driver until the mapping lands, and copying into a mapped buffer is a
+     * validation error rather than a slow frame.
+     */
+    beginFrame(): boolean;
+    /** Open a bracket. Every pass opened until `end` is attributed to this slot. */
+    begin(slot: GpuSlot): void;
+    end(): void;
+    /**
+     * The query pair for the pass about to be opened, or undefined where there is nothing to
+     * measure with.
+     *
+     * Undefined is a legal value for `timestampWrites`, so a caller passes this straight into
+     * the descriptor without branching, and an unmeasured frame costs one property write.
+     */
+    writesFor(): GPURenderPassTimestampWrites | undefined;
+    /**
+     * Copy the frame's queries out, on the frame's own encoder, before it is submitted.
+     *
+     * The renderer calls this rather than `endFrame`, because by the time the consumer ends the
+     * frame the encoder it would have to ride on has already been finished and submitted.
+     */
+    resolve(encoder: GPUCommandEncoder): void;
+    /** Close the frame and ask for the mapping. Nothing waits for it. */
+    endFrame(): void;
+    private readBack;
+    /** The oldest finished sample, or null. Never blocks. */
+    poll(): GpuSample | null;
+    /**
+     * The whole of the last resolved frame in milliseconds, or null where nothing measured.
+     *
+     * Summed because the three brackets partition the frame rather than overlapping, which is
+     * the same arithmetic `GpuTimer.lastFrameMs` does over the same three names.
+     */
+    lastFrameMs(): number | null;
+    dispose(): void;
+}

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

@@ -0,0 +1,213 @@
+import { GPU_SLOTS } from '../../gpuTimer.js';
+/**
+ * Passes one frame may time.
+ *
+ * The heaviest frame measured on this engine is twenty — the game's courtyard, with three shadow
+ * layers, six cubemap faces, two mirrors and the occlusion chain. Thirty-two leaves room for a
+ * scene heavier than any that exists without allocating a query set nobody fills.
+ */
+const MAX_TIMED_PASSES = 32;
+const QUERIES_PER_PASS = 2;
+const BYTES_PER_QUERY = 8;
+const NS_PER_MS = 1e6;
+/** Resolved frames waiting for `poll`. Past this a frame is skipped rather than queued. */
+const POOL_DEPTH = 4;
+/*
+ * Numeric rather than `GPUBufferUsage.*`, matching the rest of this directory. Those globals
+ * do not exist under vitest, and a timer that cannot be constructed in a test is a timer whose
+ * arithmetic nobody checks.
+ */
+const USAGE_QUERY_RESOLVE = 0x0200;
+const USAGE_COPY_SRC = 0x0004;
+const USAGE_COPY_DST = 0x0008;
+const USAGE_MAP_READ = 0x0001;
+const MAP_MODE_READ = 0x0001;
+/** Slot to index, so a frame's attribution is a `Uint8Array` and costs no allocation. */
+const SLOT_INDEX = { shadows: 0, reflection: 1, rest: 2 };
+export class GpuTimestamps {
+    /** False where the adapter withheld `timestamp-query`, which is a normal state. */
+    available;
+    querySet = null;
+    resolveBuffer = null;
+    readBuffer = null;
+    sampleEvery;
+    /** Which slot each timed pass of the frame being recorded belongs to. */
+    passSlots = new Uint8Array(MAX_TIMED_PASSES);
+    /** The same, for the frame whose readback is in flight; the recorder reuses the other. */
+    inFlightSlots = new Uint8Array(MAX_TIMED_PASSES);
+    passCount = 0;
+    inFlightCount = 0;
+    openSlot = null;
+    frame = 0;
+    measuring = false;
+    /** Whether this frame's queries have already been copied out; a second copy is a no-op. */
+    resolved = false;
+    readbackBusy = false;
+    pending = [];
+    lastSample = null;
+    get sampling() {
+        return this.measuring;
+    }
+    constructor(device, enabled = false, sampleEvery = 8) {
+        this.sampleEvery = Math.max(1, Math.floor(sampleEvery));
+        /*
+         * Both halves, and `enabled` is the one that matters. A timer costs two queries a pass and
+         * attaches a block to every pass descriptor in the frame, so an implementation that
+         * disagrees about any of it invalidates the command buffer and the frame draws nothing.
+         * That risk belongs to whoever asked to measure, never to every consumer by default.
+         */
+        this.available = enabled && (device.features?.has('timestamp-query') ?? false);
+        if (!this.available)
+            return;
+        const count = MAX_TIMED_PASSES * QUERIES_PER_PASS;
+        const bytes = count * BYTES_PER_QUERY;
+        this.querySet = device.createQuerySet({ label: 'gpu.timestamps', type: 'timestamp', count });
+        /*
+         * Two buffers, because one cannot be both. `QUERY_RESOLVE` is where the driver writes and
+         * `MAP_READ` is what this side may look at, and the flags are mutually exclusive.
+         */
+        this.resolveBuffer = device.createBuffer({
+            label: 'gpu.timestamps.resolve',
+            size: bytes,
+            usage: USAGE_QUERY_RESOLVE | USAGE_COPY_SRC,
+        });
+        this.readBuffer = device.createBuffer({
+            label: 'gpu.timestamps.read',
+            size: bytes,
+            usage: USAGE_COPY_DST | USAGE_MAP_READ,
+        });
+    }
+    /**
+     * Whether this frame is measured. Called once per frame, before any `begin`.
+     *
+     * Declines while a readback is still in flight, and that is not politeness: the read buffer
+     * belongs to the driver until the mapping lands, and copying into a mapped buffer is a
+     * validation error rather than a slow frame.
+     */
+    beginFrame() {
+        if (this.querySet === null)
+            return false;
+        const measured = this.frame % this.sampleEvery === 0;
+        this.frame++;
+        this.measuring = measured && !this.readbackBusy && this.pending.length < POOL_DEPTH;
+        if (this.measuring) {
+            this.passCount = 0;
+            this.resolved = false;
+            this.openSlot = null;
+        }
+        return this.measuring;
+    }
+    /** Open a bracket. Every pass opened until `end` is attributed to this slot. */
+    begin(slot) {
+        if (!this.measuring || this.openSlot !== null)
+            return;
+        this.openSlot = slot;
+    }
+    end() {
+        this.openSlot = null;
+    }
+    /**
+     * The query pair for the pass about to be opened, or undefined where there is nothing to
+     * measure with.
+     *
+     * Undefined is a legal value for `timestampWrites`, so a caller passes this straight into
+     * the descriptor without branching, and an unmeasured frame costs one property write.
+     */
+    writesFor() {
+        if (!this.measuring || this.resolved || this.querySet === null)
+            return undefined;
+        if (this.passCount >= MAX_TIMED_PASSES)
+            return undefined;
+        const index = this.passCount;
+        this.passSlots[index] = SLOT_INDEX[this.openSlot ?? 'rest'];
+        this.passCount++;
+        return {
+            querySet: this.querySet,
+            beginningOfPassWriteIndex: index * QUERIES_PER_PASS,
+            endOfPassWriteIndex: index * QUERIES_PER_PASS + 1,
+        };
+    }
+    /**
+     * Copy the frame's queries out, on the frame's own encoder, before it is submitted.
+     *
+     * The renderer calls this rather than `endFrame`, because by the time the consumer ends the
+     * frame the encoder it would have to ride on has already been finished and submitted.
+     */
+    resolve(encoder) {
+        if (!this.measuring || this.resolved || this.readbackBusy)
+            return;
+        if (this.querySet === null || this.resolveBuffer === null || this.readBuffer === null)
+            return;
+        if (this.passCount === 0)
+            return;
+        const count = this.passCount * QUERIES_PER_PASS;
+        encoder.resolveQuerySet(this.querySet, 0, count, this.resolveBuffer, 0);
+        encoder.copyBufferToBuffer(this.resolveBuffer, 0, this.readBuffer, 0, count * BYTES_PER_QUERY);
+        this.resolved = true;
+    }
+    /** Close the frame and ask for the mapping. Nothing waits for it. */
+    endFrame() {
+        if (!this.measuring)
+            return;
+        this.measuring = false;
+        this.openSlot = null;
+        if (!this.resolved || this.readbackBusy)
+            return;
+        this.inFlightSlots.set(this.passSlots);
+        this.inFlightCount = this.passCount;
+        this.readbackBusy = true;
+        this.readBack();
+    }
+    readBack() {
+        const buffer = this.readBuffer;
+        if (buffer === null)
+            return;
+        void buffer.mapAsync(MAP_MODE_READ).then(() => {
+            const stamps = new BigUint64Array(buffer.getMappedRange());
+            const parts = { shadows: 0, reflection: 0, rest: 0 };
+            for (let i = 0; i < this.inFlightCount; i++) {
+                const started = stamps[i * QUERIES_PER_PASS] ?? 0n;
+                const finished = stamps[i * QUERIES_PER_PASS + 1] ?? 0n;
+                /*
+                 * A pair the driver never wrote reads as two zeros, and a disjoint one can read
+                 * backwards. Both mean "no measurement", and neither is worth reporting as a
+                 * confident 0.0 — see `FrameTimer` on why an invented zero is the worst answer here.
+                 */
+                if (finished <= started)
+                    continue;
+                const slot = GPU_SLOTS[this.inFlightSlots[i] ?? 2] ?? 'rest';
+                parts[slot] += Number(finished - started) / NS_PER_MS;
+            }
+            buffer.unmap();
+            this.lastSample = parts;
+            if (this.pending.length < POOL_DEPTH)
+                this.pending.push(parts);
+            this.readbackBusy = false;
+        }, () => {
+            /* A lost device or a cancelled mapping is not a reason to stop drawing. */
+            this.readbackBusy = false;
+        });
+    }
+    /** The oldest finished sample, or null. Never blocks. */
+    poll() {
+        return this.pending.shift() ?? null;
+    }
+    /**
+     * The whole of the last resolved frame in milliseconds, or null where nothing measured.
+     *
+     * Summed because the three brackets partition the frame rather than overlapping, which is
+     * the same arithmetic `GpuTimer.lastFrameMs` does over the same three names.
+     */
+    lastFrameMs() {
+        if (this.lastSample === null)
+            return null;
+        return this.lastSample.shadows + this.lastSample.reflection + this.lastSample.rest;
+    }
+    dispose() {
+        this.querySet?.destroy();
+        this.resolveBuffer?.destroy();
+        this.readBuffer?.destroy();
+        this.pending.length = 0;
+        this.lastSample = null;
+    }
+}

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

@@ -0,0 +1,19 @@
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * `color` (4), and nothing else.
+ *
+ * The rect's bounds and the canvas size were in here to place the quad and are not needed to
+ * cover a viewport that is already the rect. Kept out rather than left unread: an unused uniform
+ * is a field somebody later writes and expects to matter.
+ */
+export declare const INSET_UNIFORM_SIZE = 16;
+export declare function createInsetBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createInsetBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, uniforms: GPUBuffer): GPUBindGroup;
+/**
+ * The clearing quad.
+ *
+ * `writeColor` off is the depth-only case — `beginInset(rect, null)`, where the frame behind
+ * survives so what is drawn next sits over the scene rather than over a rectangle of flat
+ * colour. `depthCompare: 'always'` because a clear does not ask permission.
+ */
+export declare function insetPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, writeColor: boolean): GPURenderPipeline;

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

@@ -0,0 +1,108 @@
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * Clearing a *rectangle* of the frame, which WebGPU has no operation for.
+ *
+ * `beginInset` on WebGL2 is `gl.scissor` plus `gl.clear`, and the scissor confines the clear.
+ * WebGPU clears at `loadOp`, which applies to the whole attachment and cannot be confined —
+ * reopening the pass to clear would throw away the frame outside the inset, and clearing only
+ * depth that way would silently un-occlude everything a scene draws *after* `endInset`.
+ *
+ * So the rect is drawn rather than cleared: one quad at the far plane, depth always written,
+ * colour written or masked off depending on whether the caller asked for a colour.
+ *
+ * **Its own shader, and it is allowed to be.** This is not generated from GLSL and has no
+ * WebGL2 counterpart to stay honest against — the counterpart is `gl.clear`. The mip blit in
+ * `surfaceTexturePass.ts` is here for the same reason.
+ */
+const INSET_WGSL = `
+struct Rect {
+  color: vec4<f32>,
+}
+@group(0) @binding(0) var<uniform> rect: Rect;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {
+  /*
+   * The whole of the current viewport, which is the inset, because \`beginInset\` has already
+   * set it.
+   *
+   * **It used to place the quad from the rect's own CSS pixels and that is one transform too
+   * many.** Clip space is relative to the viewport in force, not to the canvas, so a quad
+   * describing "this box within the canvas" was mapped into the box a second time: it came out
+   * small and pushed toward a corner, leaving most of the inset uncleared. What a caller then
+   * saw was whatever had been in the frame there, or nothing at all where the frame was
+   * transparent — reported from the game as a hole where a portrait should be. The content
+   * inside the inset was always correct, which is what made it look like a missing draw rather
+   * than a misplaced one.
+   */
+  var corner = array<vec2<f32>, 6>(
+    vec2<f32>(0.0, 0.0), vec2<f32>(1.0, 0.0), vec2<f32>(1.0, 1.0),
+    vec2<f32>(0.0, 0.0), vec2<f32>(1.0, 1.0), vec2<f32>(0.0, 1.0),
+  );
+  let ndc = corner[index] * 2.0 - vec2<f32>(1.0, 1.0);
+  // z = 1: the far plane, which is what a depth clear writes.
+  return vec4<f32>(ndc, 1.0, 1.0);
+}
+
+@fragment
+fn fragmentMain() -> @location(0) vec4<f32> {
+  return rect.color;
+}
+`;
+/**
+ * `color` (4), and nothing else.
+ *
+ * The rect's bounds and the canvas size were in here to place the quad and are not needed to
+ * cover a viewport that is already the rect. Kept out rather than left unread: an unused uniform
+ * is a field somebody later writes and expects to matter.
+ */
+export const INSET_UNIFORM_SIZE = 16;
+export function createInsetBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'inset.layout',
+        entries: [
+            {
+                binding: 0,
+                visibility: 0x1 | 0x2,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: INSET_UNIFORM_SIZE },
+            },
+        ],
+    });
+}
+export function createInsetBindGroup(device, layout, uniforms) {
+    return device.createBindGroup({
+        label: 'inset.bindGroup',
+        layout,
+        entries: [{ binding: 0, resource: { buffer: uniforms, size: INSET_UNIFORM_SIZE } }],
+    });
+}
+/**
+ * The clearing quad.
+ *
+ * `writeColor` off is the depth-only case — `beginInset(rect, null)`, where the frame behind
+ * survives so what is drawn next sits over the scene rather than over a rectangle of flat
+ * colour. `depthCompare: 'always'` because a clear does not ask permission.
+ */
+export function insetPipeline(cache, device, layout, writeColor) {
+    return cache.get(`inset|${writeColor ? 'color' : 'depth'}`, () => {
+        const module = shaderModule(device, { label: 'inset', code: INSET_WGSL });
+        return {
+            label: `inset|${writeColor ? 'color' : 'depth'}`,
+            layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+            vertex: { module, entryPoint: 'vertexMain' },
+            fragment: {
+                module,
+                entryPoint: 'fragmentMain',
+                targets: [{ format: cache.format, writeMask: writeColor ? 0xf : 0 }],
+            },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            multisample: { count: cache.sampleCount },
+            depthStencil: {
+                format: DEPTH_FORMAT,
+                depthWriteEnabled: true,
+                depthCompare: 'always',
+            },
+        };
+    });
+}

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

@@ -0,0 +1,27 @@
+import type { MeshInstances } from '../../instances.ts';
+import type { GpuMesh } from './buffers.ts';
+/**
+ * One mesh's per-instance buffer on the device.
+ *
+ * **Attached to a mesh rather than owning one.** The geometry an instanced draw repeats is
+ * usually the expensive kind — a loaded model rather than a blade of grass — so this holds a
+ * reference to the mesh a consumer already uploaded and adds only the placement.
+ *
+ * The staging array is allocated here and rewritten in place, which is what keeps a frame that
+ * re-uploads a moving batch allocation-free.
+ */
+export declare class GpuInstancedBatch {
+    readonly buffer: GPUBuffer;
+    readonly mesh: GpuMesh;
+    readonly capacity: number;
+    private readonly staging;
+    constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string);
+    /**
+     * Pack and push `data.count` instances, in one write.
+     *
+     * Only the live prefix, for the reason `uploadScatter` gives: the rest is not drawn and
+     * uploading it would be per-frame waste with nothing reading it.
+     */
+    upload(queue: GPUQueue, data: MeshInstances): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,49 @@
+import { INSTANCE_FLOATS, INSTANCE_STRIDE, packInstances } from '../../instances.js';
+/** VERTEX | COPY_DST, spelled the way every other pass here spells it. */
+const USAGE_VERTEX = 0x0020 | 0x0008;
+/**
+ * One mesh's per-instance buffer on the device.
+ *
+ * **Attached to a mesh rather than owning one.** The geometry an instanced draw repeats is
+ * usually the expensive kind — a loaded model rather than a blade of grass — so this holds a
+ * reference to the mesh a consumer already uploaded and adds only the placement.
+ *
+ * The staging array is allocated here and rewritten in place, which is what keeps a frame that
+ * re-uploads a moving batch allocation-free.
+ */
+export class GpuInstancedBatch {
+    buffer;
+    mesh;
+    capacity;
+    staging;
+    constructor(device, mesh, capacity, label) {
+        this.mesh = mesh;
+        this.capacity = capacity;
+        this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
+        this.buffer = device.createBuffer({
+            /*
+             * Labelled, and it is not decoration: a WebGPU validation failure arrives at `submit`
+             * naming the resource it was about, and an unlabelled buffer names nothing.
+             */
+            label,
+            size: capacity * INSTANCE_STRIDE,
+            usage: USAGE_VERTEX,
+        });
+    }
+    /**
+     * Pack and push `data.count` instances, in one write.
+     *
+     * Only the live prefix, for the reason `uploadScatter` gives: the rest is not drawn and
+     * uploading it would be per-frame waste with nothing reading it.
+     */
+    upload(queue, data) {
+        const count = Math.min(data.count, this.capacity);
+        if (count === 0)
+            return;
+        packInstances(data, this.staging);
+        queue.writeBuffer(this.buffer, 0, this.staging, 0, count * INSTANCE_FLOATS);
+    }
+    dispose() {
+        this.buffer.destroy();
+    }
+}

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

@@ -0,0 +1,75 @@
+import { type StageBindings } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The light-volume pass: a closed hull, and a march down the view ray inside it.
+ *
+ * The geometry decides which pixels run and nothing else, so this is an ordinary indexed mesh
+ * draw with an unusual pipeline: **additive, depth tested, depth never written, and culling
+ * chosen per draw** rather than fixed.
+ *
+ * Culling is the part that is not boilerplate. A volume seen from outside is entered at its
+ * front faces and a volume seen from inside is entered at its back ones, so which face survives
+ * is a property of where the camera stands — `resolveLightVolume` answers it, and this file
+ * turns the answer into one of two pipelines.
+ */
+/** Which permutation of the fragment stage: the sun-shadow lookup compiled in, or not. */
+export type LightVolumeVariant = 'none' | 'directionalShadows';
+export declare const LIGHT_VOLUME_VERT_FIELDS: {
+    readonly uViewProj: {
+        readonly offset: 0;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uModel: {
+        readonly offset: 64;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+};
+export declare const LIGHT_VOLUME_VERT_SIZE: 128;
+/** Everything the generator recorded about one permutation of the fragment stage. */
+export declare function lightVolumeFragmentBindings(variant: LightVolumeVariant): StageBindings;
+/**
+ * The layout this variant binds against. **Both blocks are dynamic.**
+ *
+ * Unlike the flat pass, where the fragment block holds the lights and the fog and is settled
+ * once a frame, every field here belongs to one volume: its strength, its reach, its aperture,
+ * its own placement and the camera expressed in its own space. Two beams in a frame have
+ * nothing in common to hoist, so both blocks come out of a ring a slot at a time — see
+ * `UniformRing` for what a single buffer does to a second draw.
+ */
+export declare function createLightVolumeBindGroupLayout(device: GPUDevice, variant: LightVolumeVariant): GPUBindGroupLayout;
+/**
+ * Bind the two rings and one view per declared map.
+ *
+ * `resolve` is asked by the shader's own name for each map, so the caller supplies what it has
+ * and a stand-in for the rest. **The stand-in has to read as unoccluded, not as absent**: the
+ * dynamic layer is sampled unconditionally, and `occlusion()` calls any stored depth below the
+ * receiver's a blocker — so a stand-in of zero would put the whole beam in shadow, which is a
+ * picture rather than an error. A white one-pixel texture is depth 1, the far plane, nothing in
+ * the way. `emptyTexture.ts` is the same value on the other backend for the same reason.
+ */
+export declare function createLightVolumeBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, variant: LightVolumeVariant, vertices: GPUBuffer, fragments: GPUBuffer, resolve: (name: string) => {
+    view: GPUTextureView;
+    sampler: GPUSampler;
+}): GPUBindGroup;
+/**
+ * The pipeline for one variant and one side of the hull.
+ *
+ * **`src-alpha, one`, which is `gl.blendFunc(SRC_ALPHA, ONE)` and the whole reason this pass
+ * exists.** Alpha blending moves what is behind a surface *toward* it, so an unlit beam drawn
+ * that way comes out darker than the sky and sweeps a solid dark wedge across the frame; see
+ * the history at the top of `shaders/lightVolume.ts`. The shader puts its energy in the colour
+ * and leaves alpha at 1, because a blend that multiplies by alpha squares anything written to
+ * both.
+ *
+ * The alpha channel is left as it was rather than accumulated, which differs from the GL call
+ * — `blendFunc` sets both channels — and is invisible here because the swap chain is
+ * configured `alphaMode: 'opaque'` and the composited alpha is discarded. It would stop being
+ * invisible the day a consumer wants the canvas composited against the page behind it, and
+ * that is the line to change.
+ *
+ * **Depth tested, never written.** A beam passes behind whatever stands in front of it, and
+ * occludes nothing itself: a volume of light is not a surface.
+ */
+export declare function lightVolumePipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, variant: LightVolumeVariant, cullMode: GPUCullMode, present: Readonly<Record<string, boolean>>, key: string): GPURenderPipeline;