@woosh/meep-engine 3.47.0 → 3.49.0

package/src/shade/renderer/texture/atlas/GPUTileAtlas3D.js

@@ -0,0 +1,671 @@
+import { assert } from "../../../../core/assert.js";
+import { gpu_texture_format_info } from "../../../descriptor/texture/format/gpu_texture_format_info.js";
+import { GPUTextureContext } from "../GPUTextureContext.js";
+
+/**
+ * One 3-D texture cut into equal tiles, each tile a `content_size³` block of texels wrapped in a
+ * `border`-texel skirt, handed out one slot at a time.
+ *
+ * **What the border is for.** A tile sampled with a linear filter reads half a texel past its
+ * content on every side. The skirt holds the texels a *wrapping* tile would find there — the
+ * opposite edge of the same content — so a trilinear tap at the tile's edge blends with the tile's
+ * other side and never with the neighbouring slot. {@link tile_atlas_bordered_block} builds that
+ * skirt on the host; a producer writing on the device (a compute bake copying in through
+ * {@link copy_from_buffer}, or storing into the texture from a shader) writes the whole
+ * `tile_size³` block, skirt included, itself. One texel of border is what a linear filter needs; a
+ * wider one is for a consumer that steps further (a distance field marched across a tile), which is
+ * why it is a parameter. A consumer that never reads past its tile — loads clamped to the content —
+ * wants none.
+ *
+ * **Slots are linear, and grow two ways.** Slot `s` sits at grid cell
+ * `(s mod slots_x, floor(s / slots_x) mod slots_y, floor(s / (slots_x · slots_y)))`, x fastest and
+ * z slowest. When none is free, {@link allocate}:
+ * - **adds a layer** of `slots_x · slots_y` slots at the end of z. Nothing already placed moves, so
+ *   the old extent is copied across as it was. This is the common grow.
+ * - **widens the layer** once z is at the device's `maxTextureDimension3D`: the smaller of x and y
+ *   doubles (x on a tie, capped at the device), the layers halve, and every tile is copied to where
+ *   its slot sits under the new footprint ({@link tile_atlas_widened_footprint}). A slot keeps its
+ *   index and its texels; its *origin* changes. Rare, and as costly as a full copy.
+ *
+ * {@link capacity_limit} is where both run out: the device's limit in tiles along every axis.
+ *
+ * **Allocation reallocates the texture.** A grow replaces {@link texture}'s `GPUTexture` (the
+ * `GPUTextureContext` stays; its views are re-made), and a widen moves every tile. Take the
+ * texture, a view, the footprint or a {@link slot_origin} *after* allocating every slot a frame
+ * needs, never across an `allocate` — a frame graph that imports the texture per frame, and a
+ * shader that takes the footprint from `textureDimensions`, do this on their own.
+ *
+ * Free slots are reused most-recently-freed first; a freed slot's texels are left as they were, and
+ * move with it.
+ *
+ * Clients: the volumetrics noise atlas (`r8unorm`, 128³ + 1, sampled) and the per-geometry SDF
+ * atlas of `GPUGeometrySDFManager` (`r32float`, 50³ + 0, stored into by its build shader). Built
+ * general — format, tile size, border, footprint and usage are all constructor arguments — so a
+ * brick SDF atlas can be another instance rather than another class.
+ */
+export class GPUTileAtlas3D {
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {GPUTextureContext}
+     */
+    #texture;
+
+    /**
+     * @type {GPUTextureFormat}
+     */
+    #format;
+
+    /**
+     * @type {number}
+     */
+    #bytes_per_texel;
+
+    /**
+     * @type {number}
+     */
+    #content_size;
+
+    /**
+     * @type {number}
+     */
+    #border;
+
+    /**
+     * @type {number}
+     */
+    #tile_size;
+
+    /**
+     * @type {number}
+     */
+    #slots_x;
+
+    /**
+     * @type {number}
+     */
+    #slots_y;
+
+    /**
+     * @type {number}
+     */
+    #slots_z = 0;
+
+    /**
+     * Slots given back, most recent last.
+     * @type {number[]}
+     */
+    #free = [];
+
+    /**
+     * The first slot never handed out.
+     * @type {number}
+     */
+    #next_fresh = 0;
+
+    /**
+     * 1 where the slot is allocated. Grows with the texture.
+     * @type {Uint8Array}
+     */
+    #live;
+
+    /**
+     * @type {string}
+     */
+    #label;
+
+    /**
+     * Every argument is required: an atlas is declared, not configured.
+     *
+     * @param {object} options
+     * @param {GPUDevice} options.device
+     * @param {GPUTextureFormat} options.format an uncompressed, copyable format — what a 3-D texture
+     * allows, and what {@link write} sizes its block by
+     * @param {number} options.content_size texels of content along each axis of a tile
+     * @param {number} options.border texels of skirt on each side of the content, at least 1 for a
+     * linear filter
+     * @param {number} options.slots_x tiles along x to start with; it changes only when the atlas
+     * widens
+     * @param {number} options.slots_y tiles along y to start with; it changes only when the atlas
+     * widens
+     * @param {number} options.capacity slots to allocate up front, rounded up to whole z layers of
+     * the starting footprint
+     * @param {GPUTextureUsageFlags} options.usage how the clients use the texture on the device —
+     * `TEXTURE_BINDING` to sample or load it, `STORAGE_BINDING` to store a tile from a shader. The
+     * atlas adds `COPY_DST` and `COPY_SRC` itself: {@link write}, {@link copy_from_buffer} and a grow
+     * are copies
+     * @param {string} options.label the texture's label
+     */
+    constructor({ device, format, content_size, border, slots_x, slots_y, capacity, usage, label }) {
+        assert.defined(device, 'device');
+        assert.isString(format, 'format');
+        assert.isNonNegativeInteger(content_size, 'content_size');
+        assert.greaterThan(content_size, 0, 'content_size');
+        assert.isNonNegativeInteger(border, 'border');
+        assert.lessThanOrEqual(border, content_size, 'border must not exceed content_size: the skirt is the opposite edge of the content, and there is no more of it');
+        assert.isNonNegativeInteger(slots_x, 'slots_x');
+        assert.greaterThan(slots_x, 0, 'slots_x');
+        assert.isNonNegativeInteger(slots_y, 'slots_y');
+        assert.greaterThan(slots_y, 0, 'slots_y');
+        assert.isNonNegativeInteger(capacity, 'capacity');
+        assert.greaterThan(capacity, 0, 'capacity');
+        assert.isNonNegativeInteger(usage, 'usage');
+        assert.greaterThan(usage, 0, 'usage: a texture no shader binds is not an atlas anyone reads');
+        assert.isString(label, 'label');
+
+        const info = gpu_texture_format_info(format);
+
+        assert.equal(info.block_width, 1, `${format} is block-compressed; a 3-D texture cannot be`);
+        assert.equal(info.copyable, true, `${format} cannot be copied into, and a tile is written by copy`);
+
+        this.#device = device;
+        this.#format = format;
+        this.#bytes_per_texel = info.bytes_per_block;
+        this.#content_size = content_size;
+        this.#border = border;
+        this.#tile_size = content_size + 2 * border;
+        this.#slots_x = slots_x;
+        this.#slots_y = slots_y;
+        this.#label = label;
+
+        const texture = new GPUTextureContext(device);
+        const td = texture.descriptor;
+
+        td.label = label;
+        td.format = format;
+        td.dimension = "3d";
+        td.mipLevelCount = 1;
+        // bound however the clients said, written by host writes and device copies, and copied out
+        // of itself when it grows
+        td.usage = usage
+            | GPUTextureUsage.COPY_DST
+            | GPUTextureUsage.COPY_SRC;
+
+        this.#texture = texture;
+
+        const axis_limit = this.#axis_limit();
+
+        assert.lessThanOrEqual(slots_x, axis_limit, `slots_x ${slots_x} of ${this.#tile_size} texels exceed maxTextureDimension3D ${device.limits.maxTextureDimension3D}`);
+        assert.lessThanOrEqual(slots_y, axis_limit, `slots_y ${slots_y} of ${this.#tile_size} texels exceed maxTextureDimension3D ${device.limits.maxTextureDimension3D}`);
+
+        const layers = Math.ceil(capacity / (slots_x * slots_y));
+
+        // the footprint was declared, so construction does not widen it
+        assert.lessThanOrEqual(layers, axis_limit, `capacity ${capacity} needs ${layers} layers of ${this.#tile_size} texels; the device allows ${axis_limit} (maxTextureDimension3D ${device.limits.maxTextureDimension3D})`);
+
+        this.#set_layers(layers);
+    }
+
+    /**
+     * @returns {GPUTextureContext}
+     */
+    get texture() {
+        return this.#texture;
+    }
+
+    /**
+     * @returns {GPUTextureFormat}
+     */
+    get format() {
+        return this.#format;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get bytes_per_texel() {
+        return this.#bytes_per_texel;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get content_size() {
+        return this.#content_size;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get border() {
+        return this.#border;
+    }
+
+    /**
+     * Texels along each axis of a tile, skirt included.
+     * @returns {number}
+     */
+    get tile_size() {
+        return this.#tile_size;
+    }
+
+    /**
+     * Tiles along x now; a widen may double it.
+     * @returns {number}
+     */
+    get slots_x() {
+        return this.#slots_x;
+    }
+
+    /**
+     * Tiles along y now; a widen may double it.
+     * @returns {number}
+     */
+    get slots_y() {
+        return this.#slots_y;
+    }
+
+    /**
+     * Layers of slots along z: one more on each grow, halved by a widen.
+     * @returns {number}
+     */
+    get slots_z() {
+        return this.#slots_z;
+    }
+
+    /**
+     * Slots the texture holds now, live or not.
+     * @returns {number}
+     */
+    get capacity() {
+        return this.#slots_x * this.#slots_y * this.#slots_z;
+    }
+
+    /**
+     * The most slots this atlas can ever hold on this device: as many tiles along each of x, y and z
+     * as fit under `maxTextureDimension3D`, x and y reached by widening. A limit of texture
+     * dimensions, not of memory — a device may refuse the texture long before.
+     * @returns {number}
+     */
+    get capacity_limit() {
+        const axis_limit = this.#axis_limit();
+
+        return axis_limit * axis_limit * axis_limit;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get live_count() {
+        return this.#next_fresh - this.#free.length;
+    }
+
+    /**
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    is_live(slot) {
+        assert.isNonNegativeInteger(slot, 'slot');
+
+        return slot < this.#live.length && this.#live[slot] === 1;
+    }
+
+    /**
+     * Hand out a slot. When none is free the texture grows by a layer, or widens when z is full —
+     * after which every tile's origin may have moved.
+     *
+     * @returns {number} the slot
+     */
+    allocate() {
+        let slot;
+
+        if (this.#free.length > 0) {
+            slot = this.#free.pop();
+        } else {
+            if (this.#next_fresh >= this.capacity) {
+                this.#grow();
+            }
+
+            slot = this.#next_fresh++;
+        }
+
+        this.#live[slot] = 1;
+
+        return slot;
+    }
+
+    /**
+     * @param {number} slot
+     */
+    free(slot) {
+        assert.ok(this.is_live(slot), `slot ${slot} is not allocated`);
+
+        this.#live[slot] = 0;
+        this.#free.push(slot);
+    }
+
+    /**
+     * Texel origin of a slot's tile — the corner of its skirt, not of its content — under the
+     * footprint as it is now.
+     *
+     * @param {number} slot
+     * @param {number[]|Uint32Array} out receives x, y, z
+     * @returns {number[]|Uint32Array} out
+     */
+    slot_origin(slot, out) {
+        assert.isNonNegativeInteger(slot, 'slot');
+        assert.lessThan(slot, this.capacity, 'slot is past the atlas');
+
+        const t = this.#tile_size;
+
+        tile_atlas_slot_cell(slot, this.#slots_x, this.#slots_y, out);
+
+        out[0] *= t;
+        out[1] *= t;
+        out[2] *= t;
+
+        return out;
+    }
+
+    /**
+     * Put content into a slot from the host: the skirt is built here and the whole tile is sent in
+     * one `writeTexture`.
+     *
+     * @param {number} slot a live slot
+     * @param {Uint8Array} content `content_size³ · bytes_per_texel` bytes, x fastest, then y, then z
+     */
+    write(slot, content) {
+        assert.ok(this.is_live(slot), `slot ${slot} is not allocated`);
+        assert.isInstanceOf(content, Uint8Array, 'content');
+
+        const n = this.#content_size;
+        const bpt = this.#bytes_per_texel;
+
+        assert.equal(content.length, n * n * n * bpt, `content holds ${content.length} bytes; a tile's content is ${n}³ texels of ${bpt} bytes`);
+
+        const t = this.#tile_size;
+        const block = tile_atlas_bordered_block(content, n, this.#border, bpt, new Uint8Array(t * t * t * bpt));
+
+        this.#device.queue.writeTexture(
+            {
+                texture: this.#texture.gpu_texture,
+                mipLevel: 0,
+                origin: this.slot_origin(slot, [0, 0, 0]),
+            },
+            block,
+            {
+                offset: 0,
+                bytesPerRow: t * bpt,
+                rowsPerImage: t,
+            },
+            [t, t, t]
+        );
+    }
+
+    /**
+     * Put a whole tile, skirt included, into a slot from a buffer on the device — the way a compute
+     * bake lands: it writes the `tile_size³` block into a storage buffer, rows padded to the copy
+     * alignment, and this copies it across in the same command stream.
+     *
+     * @param {GPUCommandEncoder} encoder
+     * @param {number} slot a live slot
+     * @param {GPUBuffer} buffer
+     * @param {number} byte_offset where the block starts in the buffer
+     * @param {number} bytes_per_row stride of a row of `tile_size` texels, a multiple of
+     * `COPY_BYTES_PER_ROW_ALIGNMENT`; rows per image is the tile size
+     */
+    copy_from_buffer(encoder, slot, buffer, byte_offset, bytes_per_row) {
+        assert.defined(encoder, 'encoder');
+        assert.ok(this.is_live(slot), `slot ${slot} is not allocated`);
+        assert.defined(buffer, 'buffer');
+        assert.isNonNegativeInteger(byte_offset, 'byte_offset');
+        assert.isNonNegativeInteger(bytes_per_row, 'bytes_per_row');
+        assert.greaterThanOrEqual(bytes_per_row, this.#tile_size * this.#bytes_per_texel, 'bytes_per_row is shorter than a row of the tile');
+
+        const t = this.#tile_size;
+
+        encoder.copyBufferToTexture(
+            {
+                buffer,
+                offset: byte_offset,
+                bytesPerRow: bytes_per_row,
+                rowsPerImage: t,
+            },
+            {
+                texture: this.#texture.gpu_texture,
+                mipLevel: 0,
+                origin: this.slot_origin(slot, [0, 0, 0]),
+            },
+            [t, t, t]
+        );
+    }
+
+    destroy() {
+        this.#texture.destroy();
+    }
+
+    /**
+     * Tiles that fit along any one axis: a 3-D texture has the same limit on all three.
+     * @returns {number}
+     */
+    #axis_limit() {
+        return Math.floor(this.#device.limits.maxTextureDimension3D / this.#tile_size);
+    }
+
+    /**
+     * Room for one more slot: a layer while z has room for one, a widen once it does not.
+     */
+    #grow() {
+        if (this.#slots_z < this.#axis_limit()) {
+            this.#set_layers(this.#slots_z + 1);
+        } else {
+            this.#widen();
+        }
+    }
+
+    /**
+     * One more layer of slots, the old extent copied across.
+     *
+     * @param {number} layers
+     */
+    #set_layers(layers) {
+        const t = this.#tile_size;
+
+        this.#slots_z = layers;
+        this.#resize_live();
+
+        // preserve: a new layer keeps every tile where it was, because x and y do not change
+        this.#texture.resize(this.#slots_x * t, this.#slots_y * t, layers * t, true);
+    }
+
+    /**
+     * A wider layer and half as many of them, every tile handed out so far copied to where its slot
+     * sits under the new footprint.
+     */
+    #widen() {
+        const sx = this.#slots_x;
+        const sy = this.#slots_y;
+        const footprint = [sx, sy];
+
+        const widened = tile_atlas_widened_footprint(sx, sy, this.#axis_limit(), footprint);
+
+        assert.ok(widened, `${this.#label}: full at ${this.capacity} slots — ${sx}×${sy}×${this.#slots_z} tiles of ${this.#tile_size} texels reach maxTextureDimension3D ${this.#device.limits.maxTextureDimension3D} on every axis`);
+
+        const nx = footprint[0];
+        const ny = footprint[1];
+
+        // every slot below the old capacity keeps a home, and the one being allocated gets one: half
+        // the layers, and one more when they halve exactly
+        const layers = Math.ceil((this.capacity + 1) / (nx * ny));
+
+        const device = this.#device;
+        const texture = this.#texture;
+        const t = this.#tile_size;
+
+        const source = texture.gpu_texture;
+
+        texture.descriptor.size = [nx * t, ny * t, layers * t];
+
+        const destination = device.createTexture(texture.descriptor);
+
+        const encoder = device.createCommandEncoder({
+            label: `${this.#label} / widen`
+        });
+
+        const from = [0, 0, 0];
+        const to = [0, 0, 0];
+        const count = this.#next_fresh;
+
+        // slots side by side along x in both footprints move in one copy: a whole old row whenever
+        // the new row is a multiple of it, which doubling makes it
+        for (let slot = 0; slot < count;) {
+            tile_atlas_slot_cell(slot, sx, sy, from);
+            tile_atlas_slot_cell(slot, nx, ny, to);
+
+            const run = Math.min(sx - from[0], nx - to[0], count - slot);
+
+            encoder.copyTextureToTexture(
+                {
+                    texture: source,
+                    mipLevel: 0,
+                    origin: [from[0] * t, from[1] * t, from[2] * t],
+                },
+                {
+                    texture: destination,
+                    mipLevel: 0,
+                    origin: [to[0] * t, to[1] * t, to[2] * t],
+                },
+                [run * t, t, t]
+            );
+
+            slot += run;
+        }
+
+        device.queue.submit([encoder.finish()]);
+
+        // destroys the old texture; the copies out of it were submitted first
+        texture.replace(destination);
+
+        this.#slots_x = nx;
+        this.#slots_y = ny;
+        this.#slots_z = layers;
+        this.#resize_live();
+    }
+
+    /**
+     * Fit the liveness flags to the capacity, keeping every slot's own.
+     */
+    #resize_live() {
+        const live = new Uint8Array(this.capacity);
+
+        if (this.#live !== undefined) {
+            live.set(this.#live);
+        }
+
+        this.#live = live;
+    }
+}
+
+/**
+ * Grid cell of a slot under a footprint: x fastest, then y, then z.
+ *
+ * @param {number} slot
+ * @param {number} slots_x
+ * @param {number} slots_y
+ * @param {number[]|Uint32Array} out receives x, y, z in tiles
+ * @returns {number[]|Uint32Array} out
+ */
+export function tile_atlas_slot_cell(slot, slots_x, slots_y, out) {
+    const per_layer = slots_x * slots_y;
+
+    const z = Math.floor(slot / per_layer);
+    const in_layer = slot - z * per_layer;
+    const y = Math.floor(in_layer / slots_x);
+
+    out[0] = in_layer - y * slots_x;
+    out[1] = y;
+    out[2] = z;
+
+    return out;
+}
+
+/**
+ * The footprint a full atlas widens to: the smaller of x and y doubles, x on a tie, capped at
+ * `axis_limit`. The smaller side reaches the limit only when both have, which is when the atlas is
+ * full.
+ *
+ * @param {number} slots_x
+ * @param {number} slots_y
+ * @param {number} axis_limit tiles that fit along an axis
+ * @param {number[]} out receives the new slots_x, slots_y
+ * @returns {boolean} false when both sides are at the limit, and nothing can widen
+ */
+export function tile_atlas_widened_footprint(slots_x, slots_y, axis_limit, out) {
+    assert.isNonNegativeInteger(slots_x, 'slots_x');
+    assert.isNonNegativeInteger(slots_y, 'slots_y');
+    assert.isNonNegativeInteger(axis_limit, 'axis_limit');
+    assert.lessThanOrEqual(slots_x, axis_limit, 'slots_x');
+    assert.lessThanOrEqual(slots_y, axis_limit, 'slots_y');
+
+    out[0] = slots_x;
+    out[1] = slots_y;
+
+    if (slots_x <= slots_y) {
+        if (slots_x === axis_limit) {
+            return false;
+        }
+
+        out[0] = Math.min(2 * slots_x, axis_limit);
+    } else {
+        out[1] = Math.min(2 * slots_y, axis_limit);
+    }
+
+    return true;
+}
+
+/**
+ * A tile's full block from its content: the content in the middle, and around it a skirt of
+ * `border` texels holding the content's opposite edge, so the block tiles with itself under a
+ * linear filter.
+ *
+ * Pure, and the one place the wrap is defined — a device-side producer has to agree with it.
+ *
+ * @param {Uint8Array} content `content_size³ · bytes_per_texel` bytes, x fastest
+ * @param {number} content_size
+ * @param {number} border at most `content_size`
+ * @param {number} bytes_per_texel
+ * @param {Uint8Array} out `(content_size + 2·border)³ · bytes_per_texel` bytes, x fastest
+ * @returns {Uint8Array} out
+ */
+export function tile_atlas_bordered_block(content, content_size, border, bytes_per_texel, out) {
+    assert.isInstanceOf(content, Uint8Array, 'content');
+    assert.isInstanceOf(out, Uint8Array, 'out');
+    assert.isNonNegativeInteger(content_size, 'content_size');
+    assert.isNonNegativeInteger(border, 'border');
+    assert.lessThanOrEqual(border, content_size, 'border');
+    assert.isNonNegativeInteger(bytes_per_texel, 'bytes_per_texel');
+
+    const n = content_size;
+    const t = n + 2 * border;
+
+    assert.equal(content.length, n * n * n * bytes_per_texel, 'content length');
+    assert.equal(out.length, t * t * t * bytes_per_texel, 'out length');
+
+    for (let tz = 0; tz < t; tz++) {
+        // (tz - border) mod n, kept non-negative: border <= n, so one n is enough
+        const cz = (tz - border + n) % n;
+
+        for (let ty = 0; ty < t; ty++) {
+            const cy = (ty - border + n) % n;
+
+            const row_out = (tz * t + ty) * t;
+            const row_in = (cz * n + cy) * n;
+
+            for (let tx = 0; tx < t; tx++) {
+                const cx = (tx - border + n) % n;
+
+                const src = (row_in + cx) * bytes_per_texel;
+                const dst = (row_out + tx) * bytes_per_texel;
+
+                for (let b = 0; b < bytes_per_texel; b++) {
+                    out[dst + b] = content[src + b];
+                }
+            }
+        }
+    }
+
+    return out;
+}