@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/shadows.d.ts

@@ -0,0 +1,104 @@
+import type { OrbitCamera } from './camera.ts';
+/** The sun's shadows (ADR-0068): `false` turns them off. */
+export interface ShadowOptions {
+    /** Cascades, 1–4 (default per tier: T0 2, else 3). */
+    cascades?: number;
+    /** Texels per side of each cascade (default per tier: T0 1024, T1 1024, T2 2048). */
+    size?: number;
+    /** View depth in metres where shadows end, fading out over the last tenth (default per tier: T0 80, T1 120, T2 150). */
+    distance?: number;
+    /** Blend between logarithmic (1) and uniform (0) cascade splits (default 0.75). */
+    splitLambda?: number;
+    /**
+     * The edge filter: `soft` is a 3×3 grid of 2×2 comparisons (9 fetches), `hard` one 2×2
+     * comparison (1 fetch). Default per tier: T0 `hard`, else `soft`.
+     */
+    filter?: 'soft' | 'hard';
+}
+/** Floats of the draw's shadow uniform (`Shadow` in draw.wesl). */
+export declare const SHADOW_FLOATS = 80;
+/** Most cascades (the fragment uniform's matrix array). */
+export declare const MAX_CASCADES = 4;
+/** One cascade's vertex uniform (`Cascade` in shadow.wesl): the matrix, then the camera's offset from the instance anchor (ADR-0075). */
+export declare const CASCADE_UNIFORM_BYTES = 80;
+/**
+ * Cascaded shadow maps for the sun (ADR-0068). The view's depth range up to `distance` is
+ * split into `cascades` slices (the practical scheme: logarithmic blended with uniform);
+ * each slice's bounding sphere is fitted with an orthographic box looking down the light,
+ * its centre snapped to the shadow-map texel grid in world space (the camera's eye is f64,
+ * ADR-0008), so the map does not shimmer as the camera moves or turns. Every cascade is a
+ * square tile of one depth atlas (`cascades × size` by `size`): one texture to bind, one
+ * comparison sampler, no texture array, which compatibility mode and WebGL2 both sample.
+ */
+export declare class SunShadows {
+    #private;
+    readonly device: GPUDevice;
+    readonly cascades: number;
+    readonly size: number;
+    distance: number;
+    splitLambda: number;
+    /** PCF grid radius in taps: 1 = 3×3 (`soft`), 0 = one tap (`hard`). */
+    pcfRadius: number;
+    readonly atlas: GPUTexture;
+    readonly view: GPUTextureView;
+    readonly sampler: GPUSampler;
+    /** The vertex stage's matrices: one per cascade, `CASCADE_STRIDE` apart. */
+    readonly cascadeBuffer: GPUBuffer;
+    /** The fragment stage's: every matrix, the split depths, the texel sizes and the parameters. */
+    readonly paramsBuffer: GPUBuffer;
+    /** 4 matrices (64), splits (4), texel (4), params (4), filter (4) = 80 floats. */
+    readonly params: Float32Array<ArrayBuffer>;
+    constructor(device: GPUDevice, options: {
+        cascades: number;
+        size: number;
+        distance?: number;
+        splitLambda?: number;
+        filter?: 'soft' | 'hard';
+    });
+    get enabled(): boolean;
+    /** Byte offset of cascade `c`'s vertex uniform in `cascadeBuffer`. */
+    static offset(c: number): number;
+    /** The cascade split depths (view depth where each ends), into `out`. */
+    splits(near: number, out: Float32Array | number[]): void;
+    /**
+     * Fits every cascade to `camera`'s view (aspect = width / height) and uploads the matrices.
+     * `origin` is the camera's offset from the anchor the instance records are relative to
+     * (ADR-0075); the storage path's casters subtract it. Omit it for camera-relative records.
+     */
+    update(camera: OrbitCamera, aspect: number, origin?: ArrayLike<number>): void;
+    /**
+     * The camera's frustum planes swept towards the light, into `out` (24 floats): a plane
+     * whose inward normal faces away from the light is dropped (it always passes), so an
+     * instance between the light and the view still casts. Conservative: the hull's side
+     * planes along the frustum's silhouette are not added.
+     */
+    static sweptPlanes(camera: OrbitCamera, out: Float32Array, at: number): void;
+    destroy(): void;
+}
+/** The cascade splits (view depth where each ends) for a configuration, into `out`. */
+export declare function cascadeSplits(fit: {
+    readonly cascades: number;
+    readonly distance: number;
+    readonly splitLambda: number;
+}, near: number, out: Float32Array | number[]): void;
+/**
+ * Fits every cascade to `camera`'s view (ADR-0068) and writes the draw's shadow uniform into
+ * `p` (80 floats: 4 matrices, the splits, the texel sizes, the parameters, the filter); cascade c's
+ * matrix is `p[c * 16 .. c * 16 + 16]`. Every backend uses this one fit.
+ */
+export declare function fitCascades(fit: {
+    readonly cascades: number;
+    readonly size: number;
+    readonly distance: number;
+    readonly splitLambda: number;
+    readonly pcfRadius: number;
+}, camera: OrbitCamera, aspect: number, p: Float32Array): void;
+/**
+ * Each cascade's light-space box as the CPU cull's caster planes (ADR-0073), into `out[at…]`
+ * (five planes of 4 floats per cascade, inward, normalized): the four sides and the far side
+ * of cascade c's box, from the fit's matrices in `p` (`fitCascades`). The side towards the
+ * light stays open: casters there are pancaked onto the box (ADR-0068).
+ */
+export declare function cascadeCullPlanes(p: Float32Array, cascades: number, out: Float32Array, at: number): void;
+/** `SunShadows.sweptPlanes`, as a function (every backend's cull uses it). */
+export declare function sweptPlanes(camera: OrbitCamera, out: Float32Array, at: number): void;

package/dist/shadows.js

@@ -0,0 +1,227 @@
+/** Floats of the draw's shadow uniform (`Shadow` in draw.wesl). */
+export const SHADOW_FLOATS = 80;
+/** Most cascades (the fragment uniform's matrix array). */
+export const MAX_CASCADES = 4;
+/** Bytes between cascades' vertex uniforms (minUniformBufferOffsetAlignment's ceiling). */
+const CASCADE_STRIDE = 256;
+/** One cascade's vertex uniform (`Cascade` in shadow.wesl): the matrix, then the camera's offset from the instance anchor (ADR-0075). */
+export const CASCADE_UNIFORM_BYTES = 80;
+/** The cascade box's depth range, in sphere radii beyond the sphere towards the light (casters there are not pancaked). */
+const PULL = 1;
+/**
+ * Cascaded shadow maps for the sun (ADR-0068). The view's depth range up to `distance` is
+ * split into `cascades` slices (the practical scheme: logarithmic blended with uniform);
+ * each slice's bounding sphere is fitted with an orthographic box looking down the light,
+ * its centre snapped to the shadow-map texel grid in world space (the camera's eye is f64,
+ * ADR-0008), so the map does not shimmer as the camera moves or turns. Every cascade is a
+ * square tile of one depth atlas (`cascades × size` by `size`): one texture to bind, one
+ * comparison sampler, no texture array, which compatibility mode and WebGL2 both sample.
+ */
+export class SunShadows {
+    device;
+    cascades;
+    size;
+    distance;
+    splitLambda;
+    /** PCF grid radius in taps: 1 = 3×3 (`soft`), 0 = one tap (`hard`). */
+    pcfRadius;
+    atlas;
+    view;
+    sampler;
+    /** The vertex stage's matrices: one per cascade, `CASCADE_STRIDE` apart. */
+    cascadeBuffer;
+    /** The fragment stage's: every matrix, the split depths, the texel sizes and the parameters. */
+    paramsBuffer;
+    #cascadeData = new Float32Array((MAX_CASCADES * CASCADE_STRIDE) / 4);
+    /** 4 matrices (64), splits (4), texel (4), params (4), filter (4) = 80 floats. */
+    params = new Float32Array(SHADOW_FLOATS);
+    constructor(device, options) {
+        this.device = device;
+        this.cascades = Math.max(0, Math.min(MAX_CASCADES, Math.floor(options.cascades)));
+        const maxSide = device.limits.maxTextureDimension2D;
+        this.size = this.cascades > 0 ? Math.min(options.size, Math.floor(maxSide / this.cascades)) : 1;
+        this.distance = options.distance ?? 150;
+        this.splitLambda = options.splitLambda ?? 0.75;
+        this.pcfRadius = options.filter === 'hard' ? 0 : 1;
+        this.atlas = device.createTexture({
+            label: 'yali:shadow:atlas',
+            size: [Math.max(1, this.cascades) * this.size, this.size],
+            format: 'depth32float',
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+        });
+        this.view = this.atlas.createView();
+        // Lit when the fragment's depth is at least the stored one (reverse-Z: larger is nearer the light).
+        this.sampler = device.createSampler({ label: 'yali:shadow', compare: 'greater-equal', magFilter: 'linear', minFilter: 'linear' });
+        this.cascadeBuffer = device.createBuffer({ label: 'yali:shadow:cascades', size: Math.max(1, this.cascades) * CASCADE_STRIDE, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        this.paramsBuffer = device.createBuffer({ label: 'yali:shadow:params', size: this.params.byteLength, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+        device.queue.writeBuffer(this.paramsBuffer, 0, this.params); // count 0 until the first update
+    }
+    get enabled() {
+        return this.cascades > 0;
+    }
+    /** Byte offset of cascade `c`'s vertex uniform in `cascadeBuffer`. */
+    static offset(c) {
+        return c * CASCADE_STRIDE;
+    }
+    /** The cascade split depths (view depth where each ends), into `out`. */
+    splits(near, out) {
+        cascadeSplits(this, near, out);
+    }
+    /**
+     * Fits every cascade to `camera`'s view (aspect = width / height) and uploads the matrices.
+     * `origin` is the camera's offset from the anchor the instance records are relative to
+     * (ADR-0075); the storage path's casters subtract it. Omit it for camera-relative records.
+     */
+    update(camera, aspect, origin) {
+        if (!this.enabled)
+            return;
+        fitCascades(this, camera, aspect, this.params);
+        for (let c = 0; c < this.cascades; c++) {
+            const at = (c * CASCADE_STRIDE) / 4;
+            this.#cascadeData.set(this.params.subarray(c * 16, c * 16 + 16), at);
+            for (let i = 0; i < 3; i++)
+                this.#cascadeData[at + 16 + i] = origin ? origin[i] : 0;
+        }
+        this.device.queue.writeBuffer(this.cascadeBuffer, 0, this.#cascadeData, 0, (this.cascades * CASCADE_STRIDE) / 4);
+        this.device.queue.writeBuffer(this.paramsBuffer, 0, this.params);
+    }
+    /**
+     * The camera's frustum planes swept towards the light, into `out` (24 floats): a plane
+     * whose inward normal faces away from the light is dropped (it always passes), so an
+     * instance between the light and the view still casts. Conservative: the hull's side
+     * planes along the frustum's silhouette are not added.
+     */
+    static sweptPlanes(camera, out, at) {
+        sweptPlanes(camera, out, at);
+    }
+    destroy() {
+        this.atlas.destroy();
+        this.cascadeBuffer.destroy();
+        this.paramsBuffer.destroy();
+    }
+}
+/** The cascade splits (view depth where each ends) for a configuration, into `out`. */
+export function cascadeSplits(fit, near, out) {
+    const n = Math.max(near, 0.05);
+    const f = Math.max(fit.distance, n * 2);
+    const k = fit.cascades;
+    for (let i = 1; i <= k; i++) {
+        const log = n * (f / n) ** (i / k);
+        const uni = n + ((f - n) * i) / k;
+        out[i - 1] = fit.splitLambda * log + (1 - fit.splitLambda) * uni;
+    }
+}
+/**
+ * Fits every cascade to `camera`'s view (ADR-0068) and writes the draw's shadow uniform into
+ * `p` (80 floats: 4 matrices, the splits, the texel sizes, the parameters, the filter); cascade c's
+ * matrix is `p[c * 16 .. c * 16 + 16]`. Every backend uses this one fit.
+ */
+export function fitCascades(fit, camera, aspect, p) {
+    const v = camera.view;
+    // Forward is minus the view's third row (lookTo's back axis).
+    const fx = -v[2], fy = -v[6], fz = -v[10];
+    const lx = camera.uniform[40], ly = camera.uniform[41], lz = camera.uniform[42];
+    // The light's basis: right and up across it; the reference flips near a vertical sun.
+    let ux = 0, uy = 1, uz = 0;
+    if (Math.abs(ly) > 0.99)
+        [ux, uy, uz] = [0, 0, 1];
+    let rx = uy * lz - uz * ly, ry = uz * lx - ux * lz, rz = ux * ly - uy * lx;
+    const rl = Math.hypot(rx, ry, rz);
+    rx /= rl;
+    ry /= rl;
+    rz /= rl;
+    const upx = ly * rz - lz * ry, upy = lz * rx - lx * rz, upz = lx * ry - ly * rx;
+    const tanY = Math.tan(camera.fovY / 2);
+    const k2 = tanY * tanY * (1 + aspect * aspect); // squared half-diagonal per unit depth
+    const splits = p.subarray(64, 68);
+    cascadeSplits(fit, camera.near, splits);
+    const [ex, ey, ez] = camera.eye;
+    let d0 = camera.near;
+    for (let c = 0; c < fit.cascades; c++) {
+        const d1 = splits[c];
+        // The slice's bounding sphere: centre on the view axis, radius to the far corners.
+        let zc = ((d0 + d1) / 2) * (1 + k2);
+        if (zc > d1)
+            zc = d1;
+        let r = Math.sqrt((d1 - zc) ** 2 + k2 * d1 * d1);
+        r = Math.ceil(r * 16) / 16; // a constant radius keeps the texel size constant
+        const texel = (2 * r) / fit.size;
+        // Snap the centre to the texel grid in world space (f64), then back to camera-relative.
+        const wx = fx * zc + ex, wy = fy * zc + ey, wz = fz * zc + ez;
+        const sr = rx * wx + ry * wy + rz * wz;
+        const su = upx * wx + upy * wy + upz * wz;
+        const dr = Math.round(sr / texel) * texel - sr;
+        const du = Math.round(su / texel) * texel - su;
+        const ox = fx * zc + dr * rx + du * upx;
+        const oy = fy * zc + dr * ry + du * upy;
+        const oz = fz * zc + dr * rz + du * upz;
+        // Column-major: x = right / r, y = up / r, depth = (height along the light + r) / ((2 + PULL) r).
+        const zr = (2 + PULL) * r;
+        const m = p.subarray(c * 16, c * 16 + 16);
+        m[0] = rx / r;
+        m[4] = ry / r;
+        m[8] = rz / r;
+        m[12] = -(rx * ox + ry * oy + rz * oz) / r;
+        m[1] = upx / r;
+        m[5] = upy / r;
+        m[9] = upz / r;
+        m[13] = -(upx * ox + upy * oy + upz * oz) / r;
+        m[2] = lx / zr;
+        m[6] = ly / zr;
+        m[10] = lz / zr;
+        m[14] = (r - (lx * ox + ly * oy + lz * oz)) / zr;
+        m[3] = 0;
+        m[7] = 0;
+        m[11] = 0;
+        m[15] = 1;
+        p[68 + c] = texel;
+        d0 = d1;
+    }
+    p[72] = fit.cascades;
+    p[73] = 1 / fit.size;
+    p[74] = fit.distance * 0.9; // the fade starts
+    p[75] = fit.distance;
+    p[76] = fit.pcfRadius;
+}
+/**
+ * Each cascade's light-space box as the CPU cull's caster planes (ADR-0073), into `out[at…]`
+ * (five planes of 4 floats per cascade, inward, normalized): the four sides and the far side
+ * of cascade c's box, from the fit's matrices in `p` (`fitCascades`). The side towards the
+ * light stays open: casters there are pancaked onto the box (ADR-0068).
+ */
+export function cascadeCullPlanes(p, cascades, out, at) {
+    for (let c = 0; c < cascades; c++) {
+        const m = c * 16;
+        const row = (r) => [p[m + r], p[m + 4 + r], p[m + 8 + r], p[m + 12 + r]];
+        const planes = [
+            [...row(0).slice(0, 3), row(0)[3] + 1],
+            [...row(0).slice(0, 3).map((v) => -v), 1 - row(0)[3]],
+            [...row(1).slice(0, 3), row(1)[3] + 1],
+            [...row(1).slice(0, 3).map((v) => -v), 1 - row(1)[3]],
+            row(2),
+        ];
+        for (let j = 0; j < 5; j++) {
+            const [x, y, z, w] = planes[j];
+            const l = Math.hypot(x, y, z) || 1;
+            const o = at + (c * 5 + j) * 4;
+            out[o] = x / l;
+            out[o + 1] = y / l;
+            out[o + 2] = z / l;
+            out[o + 3] = w / l;
+        }
+    }
+}
+/** `SunShadows.sweptPlanes`, as a function (every backend's cull uses it). */
+export function sweptPlanes(camera, out, at) {
+    const u = camera.uniform;
+    const lx = u[40], ly = u[41], lz = u[42];
+    for (let k = 0; k < 6; k++) {
+        const o = 16 + k * 4;
+        const away = u[o] * lx + u[o + 1] * ly + u[o + 2] * lz < 0;
+        out[at + k * 4] = away ? 0 : u[o];
+        out[at + k * 4 + 1] = away ? 0 : u[o + 1];
+        out[at + k * 4 + 2] = away ? 0 : u[o + 2];
+        out[at + k * 4 + 3] = away ? 1 : u[o + 3];
+    }
+}
+//# sourceMappingURL=shadows.js.map

package/dist/shadows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shadows.js","sourceRoot":"","sources":["../src/shadows.ts"],"names":[],"mappings":"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,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3D,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClC,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC1C,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC"}

package/dist/staging-ring.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-frame uploads through a ring of mapped `MAP_WRITE | COPY_SRC` buffers: copy into a
+ * mapped range, unmap, record `copyBufferToBuffer`, and re-map after submit.
+ *
+ * Measured 2026-10-16 (Chrome 155, `bench/webgpu-upload`): `queue.writeBuffer` runs at
+ * ~1.7 GB/s for writes under 4 MiB and ~10 GB/s from 4 MiB up. The ring runs at
+ * 6–11 GB/s from 0.8 MiB up, so a 1.6 MiB instance upload drops from ~1.0 ms to ~0.2 ms.
+ *
+ * When no buffer is mapped yet (the GPU is behind), `write` returns false and the caller
+ * uses `writeBuffer`. The one per-frame allocation is the `Uint8Array` over the mapped
+ * range: WebGPU hands out a new `ArrayBuffer` on every map.
+ *
+ * @example
+ * const ring = new StagingRing(device, bytes);
+ * if (!ring.write(heap, address, n)) device.queue.writeBuffer(dst, 0, heap, address, n);
+ * const encoder = device.createCommandEncoder();
+ * ring.record(encoder, dst); // before the passes that read `dst`
+ * device.queue.submit([encoder.finish()]);
+ * ring.recycle();
+ */
+export declare class StagingRing {
+    #private;
+    readonly size: number;
+    /** Writes that went through the ring. */
+    writes: number;
+    /** Writes that found no mapped buffer (the caller fell back to `writeBuffer`). */
+    fallbacks: number;
+    constructor(device: GPUDevice, size: number, slots?: number);
+    /** Copies `bytes` of `src` from `offset` into a mapped buffer. False when none is mapped. */
+    write(src: Uint8Array, offset: number, bytes: number): boolean;
+    /** Records the pending copy into `dst` (call before any pass reads `dst`). */
+    record(encoder: GPUCommandEncoder, dst: GPUBuffer, dstOffset?: number): void;
+    /** Call after `queue.submit`: re-maps the buffers whose copies were submitted. */
+    recycle(): void;
+    /** GPU buffers owned (for the dispose leak check). */
+    get liveBuffers(): number;
+    /** GPU bytes owned (for the memory counter). */
+    get bytes(): number;
+    /** Destroys every staging buffer. */
+    destroy(): void;
+}

package/dist/staging-ring.js

@@ -0,0 +1,125 @@
+const IDLE = 0; // mapped, ready for a write
+const WRITTEN = 1; // unmapped, its copy not yet recorded
+const RECORDED = 2; // copy recorded; re-map after submit
+const MAPPING = 3; // mapAsync in flight
+const DEAD = 4; // mapping failed (device lost): never used again
+/**
+ * Per-frame uploads through a ring of mapped `MAP_WRITE | COPY_SRC` buffers: copy into a
+ * mapped range, unmap, record `copyBufferToBuffer`, and re-map after submit.
+ *
+ * Measured 2026-10-16 (Chrome 155, `bench/webgpu-upload`): `queue.writeBuffer` runs at
+ * ~1.7 GB/s for writes under 4 MiB and ~10 GB/s from 4 MiB up. The ring runs at
+ * 6–11 GB/s from 0.8 MiB up, so a 1.6 MiB instance upload drops from ~1.0 ms to ~0.2 ms.
+ *
+ * When no buffer is mapped yet (the GPU is behind), `write` returns false and the caller
+ * uses `writeBuffer`. The one per-frame allocation is the `Uint8Array` over the mapped
+ * range: WebGPU hands out a new `ArrayBuffer` on every map.
+ *
+ * @example
+ * const ring = new StagingRing(device, bytes);
+ * if (!ring.write(heap, address, n)) device.queue.writeBuffer(dst, 0, heap, address, n);
+ * const encoder = device.createCommandEncoder();
+ * ring.record(encoder, dst); // before the passes that read `dst`
+ * device.queue.submit([encoder.finish()]);
+ * ring.recycle();
+ */
+export class StagingRing {
+    size;
+    /** Writes that went through the ring. */
+    writes = 0;
+    /** Writes that found no mapped buffer (the caller fell back to `writeBuffer`). */
+    fallbacks = 0;
+    #slots = [];
+    #pending = null;
+    #source = null;
+    #sourceKey = { buffer: null, offset: -1, bytes: -1 };
+    #destroyed = false;
+    constructor(device, size, slots = 3) {
+        this.size = size;
+        for (let i = 0; i < slots; i++) {
+            const slot = {
+                buffer: device.createBuffer({ label: `yali:staging${i}`, size, usage: GPUBufferUsage.MAP_WRITE | GPUBufferUsage.COPY_SRC, mappedAtCreation: true }),
+                state: IDLE,
+                bytes: 0,
+                onMapped: () => {
+                    if (slot.state === MAPPING)
+                        slot.state = IDLE;
+                },
+                onFailed: () => {
+                    slot.state = DEAD;
+                },
+            };
+            this.#slots.push(slot);
+        }
+    }
+    /** Copies `bytes` of `src` from `offset` into a mapped buffer. False when none is mapped. */
+    write(src, offset, bytes) {
+        if (this.#destroyed || bytes > this.size)
+            return false;
+        let slot = null;
+        for (let i = 0; i < this.#slots.length; i++) {
+            if (this.#slots[i].state === IDLE) {
+                slot = this.#slots[i];
+                break;
+            }
+        }
+        if (!slot || this.#pending) {
+            this.fallbacks++;
+            return false;
+        }
+        // The source view is cached: the extract output's address and size rarely change.
+        const k = this.#sourceKey;
+        if (k.buffer !== src.buffer || k.offset !== src.byteOffset + offset || k.bytes !== bytes) {
+            k.buffer = src.buffer;
+            k.offset = src.byteOffset + offset;
+            k.bytes = bytes;
+            this.#source = new Uint8Array(src.buffer, k.offset, bytes);
+        }
+        new Uint8Array(slot.buffer.getMappedRange(0, bytes)).set(this.#source);
+        slot.buffer.unmap();
+        slot.state = WRITTEN;
+        slot.bytes = bytes;
+        this.#pending = slot;
+        this.writes++;
+        return true;
+    }
+    /** Records the pending copy into `dst` (call before any pass reads `dst`). */
+    record(encoder, dst, dstOffset = 0) {
+        const slot = this.#pending;
+        if (!slot)
+            return;
+        encoder.copyBufferToBuffer(slot.buffer, 0, dst, dstOffset, slot.bytes);
+        slot.state = RECORDED;
+        this.#pending = null;
+    }
+    /** Call after `queue.submit`: re-maps the buffers whose copies were submitted. */
+    recycle() {
+        if (this.#destroyed)
+            return;
+        for (let i = 0; i < this.#slots.length; i++) {
+            const s = this.#slots[i];
+            if (s.state === RECORDED || (s.state === WRITTEN && s !== this.#pending)) {
+                s.state = MAPPING;
+                s.buffer.mapAsync(GPUMapMode.WRITE).then(s.onMapped, s.onFailed);
+            }
+        }
+    }
+    /** GPU buffers owned (for the dispose leak check). */
+    get liveBuffers() {
+        return this.#destroyed ? 0 : this.#slots.length;
+    }
+    /** GPU bytes owned (for the memory counter). */
+    get bytes() {
+        return this.#destroyed ? 0 : this.#slots.length * this.size;
+    }
+    /** Destroys every staging buffer. */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        for (const s of this.#slots)
+            s.buffer.destroy();
+        this.#pending = null;
+    }
+}
+//# sourceMappingURL=staging-ring.js.map

package/dist/staging-ring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging-ring.js","sourceRoot":"","sources":["../src/staging-ring.ts"],"names":[],"mappings":"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"}